App Hosting 백엔드 구성 및 관리

App Hosting는 사용 편의성과 낮은 유지관리 비용을 위해 설계되었으며, 대부분의 사용 사례에 최적화된 기본 설정을 제공합니다. 동시에 App Hosting는 특정 요구사항에 맞게 백엔드를 관리하고 구성할 수 있는 도구를 제공합니다. 이 가이드에서는 이러한 도구와 프로세스를 설명합니다.

환경 변수 설정 및 업데이트

빌드 프로세스에 추가 구성이 필요한 경우가 있습니다. App Hosting는 Firebase 콘솔을 통해 또는 apphosting.yaml에서 프로젝트의 이러한 데이터 유형을 저장하고 검색할 수 있는 환경 구성을 제공합니다.

콘솔에서 환경 변수를 설정하는 것이 가장 빠르게 시작하는 방법입니다. 보안 비밀 매개변수를 저장하고 액세스하거나, 빌드 또는 런타임에만 사용할 수 있는 변수를 설정하거나, 여러 환경에서 환경 변수를 공유해야 하는 경우 apphosting.yaml를 사용합니다. 콘솔과 apphosting.<env>.yaml를 모두 사용하면 환경마다 다른 값을 설정할 수 있습니다.

Firebase Console

환경 변수를 추가하기 위한 Firebase Console 대화상자의 화면 캡처

`apphosting.yaml`

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

변수 업데이트

백엔드의 설정 탭에 있는 Firebase 콘솔에서 환경 변수를 추가하고 수정할 수 있습니다. 백엔드 보기 >> 설정 >> 환경으로 이동한 다음 환경 변수를 추가, 수정 또는 삭제합니다.

apphosting.yaml,에서 환경 변수를 추가하고 수정하려면 파일을 수동으로 만들고 수정하세요.

변경사항은 다음 출시에만 적용되며 현재 출시에 영향을 미치지 않습니다. 저장하고 새 출시를 만들거나 변수를 저장하고 나중에 배포합니다.

변수 사용 가능 여부 설정

Firebase Console에서 생성된 환경 변수는 빌드 시간과 런타임 모두에서 사용할 수 있습니다. availability 속성을 사용하여 범위를 좁히지 않은 경우 apphosting.yaml에 정의된 변수의 기본 조건이기도 합니다. apphosting.yaml에서는 (콘솔에서는 안 됨) 환경 변수가 빌드 환경에서만 사용 가능하거나 런타임 환경에서만 사용 가능하도록 제한할 수 있습니다.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Next.js 앱의 경우 dotenv 파일에서와 동일한 방식으로 NEXT_PUBLIC_ 접두사를 사용하여 브라우저에서 변수에 액세스할 수도 있습니다.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Next.js용 dotenv 파일

Next.js 앱의 경우 환경 변수가 포함된 dotenv 파일이 App Hosting과 호환됩니다.

백엔드를 만들거나 업데이트할 때 dotenv 파일의 전체 콘텐츠를 복사하여 환경 변수 설정의 '새로 추가' 양식에 있는 첫 번째 '키' 필드에 붙여넣으면 dotenv 파일의 환경 변수를 Firebase 콘솔로 전송할 수 있습니다.

입력에 다음과 같은 형식이 있는 경우 이 방식으로 복사된 모든 환경 변수는 각 변수를 개별적으로 입력할 필요 없이 양식에 깔끔하게 형식이 지정됩니다.

KEY1=value1
KEY2=value2
KEY3=value3

프레임워크를 사용하여 복잡하거나 세부적인 환경 변수를 제어하려면 apphosting.yaml을 사용하는 것이 좋습니다.

변수 계층 구조

Firebase App Hosting은 소스에 따라 우선순위 순서로 변수를 적용합니다. 예를 들어 콘솔에서 설정된 값은 항상 apphosting.yaml 및 dotenv 파일에서 설정된 값보다 우선 적용됩니다.

전체 우선순위는 다음과 같습니다.

Firebase Console → 콘솔에서 설정된 변수
apphosting.<env>.yaml → apphosting.staging.yaml과 같은 환경별 yaml 파일에 지정된 변수 (여러 환경 배포 참고)
apphosting.yaml → apphosting.yaml 파일에 지정된 변수
Firebase 시스템 → firebase_config json 또는 firebase_webapp_config의 값을 포함하는 Firebase에 의해 설정된 변수와 SSR 앱의 호스트 이름 및 포트를 설정하는 환경 변수 (bundle.yaml의 앱 호스팅 어댑터에 의해 설정됨)

예약된 이름 및 제한사항

유효한 변수 키는 대문자로 시작해야 하며 대문자, 숫자, 밑줄만 포함할 수 있습니다. 일부 환경 변수 키는 내부에서 사용하도록 예약되어 있습니다. 구성 파일에는 다음 키를 사용하지 마세요.

빈 문자열 ('')
'='이 포함된 변수
X_FIREBASE_로 시작하는 모든 변수
PORT
K_SERVICE
K_REVISION
K_CONFIGURATION
중복 키

`apphosting.yaml` 만들기 및 수정

비밀번호나 동시 실행, CPU, 메모리 제한과 같은 런타임 설정과 같은 고급 구성의 경우 앱의 루트 디렉터리에서 apphosting.yaml 파일을 만들고 수정해야 합니다. 이 파일은 Cloud Secret Manager로 관리되는 보안 비밀에 대한 참조를 지원하므로 소스 제어에 안전하게 체크인할 수 있습니다.

apphosting.yaml을 만들려면 다음 명령어를 실행합니다.

firebase init apphosting

이렇게 하면 예시 (주석 처리됨) 구성이 포함된 기본 스타터 apphosting.yaml 파일이 생성됩니다. 수정 후 일반적인 apphosting.yaml 파일은 백엔드의 Cloud Run 서비스 설정, 일부 환경 변수, Cloud Secret Manager에서 관리하는 보안 비밀에 대한 일부 참조와 함께 다음과 같이 표시될 수 있습니다.

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

이 가이드의 나머지 부분에서는 이러한 예시 설정에 관한 추가 정보와 컨텍스트를 제공합니다.

Cloud Run 서비스 설정 구성

apphosting.yaml 설정을 사용하면 Cloud Run 서비스가 프로비저닝되는 방식을 구성할 수 있습니다. Cloud Run 서비스에 사용할 수 있는 설정은 runConfig 객체에 제공됩니다.

cpu – 각 서빙 인스턴스에 사용되는 CPU 수입니다 (기본값 0).
memoryMiB - 각 서비스 인스턴스에 할당된 메모리 양(MiB)(기본값 512)
maxInstances – 한 번에 실행할 수 있는 최대 컨테이너 수 (기본값 100, 할당량으로 관리)
minInstances – 항상 활성 상태로 유지할 컨테이너 수입니다 (기본값 0).
concurrency – 각 서빙 인스턴스가 수신할 수 있는 최대 요청 수입니다 (기본값 80).

cpu과 memoryMiB 사이의 중요한 관계를 참고하세요. 메모리는 128~32768 사이의 정수 값으로 설정할 수 있지만 메모리 한도를 늘리려면 CPU 한도를 늘려야 할 수 있습니다.

4GiB 초과에는 CPU가 2개 이상 필요합니다.
8GiB 초과에는 CPU가 4개 이상 필요합니다.
16GiB 초과에는 CPU가 6개 이상 필요합니다.
24GiB 초과에는 CPU가 8개 이상 필요합니다.

마찬가지로 cpu 값은 동시 실행 설정에 영향을 미칩니다. CPU를 1 미만으로 설정하면 동시 실행을 1로 설정해야 하며 CPU는 요청 처리 중에만 할당됩니다.

빌드 및 실행 스크립트 재정의

App Hosting는 감지된 프레임워크를 기반으로 앱의 빌드 및 시작 명령어를 추론합니다. 맞춤 빌드 또는 시작 명령어를 사용하려면 apphosting.yaml에서 App Hosting의 기본값을 재정의하면 됩니다.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

빌드 명령어 재정의는 다른 빌드 명령어보다 우선하며, 앱이 프레임워크 어댑터를 선택 해제하고 App Hosting에서 제공하는 프레임워크별 최적화를 사용 중지합니다. 앱 기능이 어댑터에서 잘 지원되지 않는 경우에 사용하는 것이 가장 좋습니다. 빌드 명령어를 변경하되 Google 제공 어댑터를 계속 사용하려면 App Hosting 프레임워크 어댑터에 설명된 대로 package.json에 빌드 스크립트를 설정하세요.

App Hosting에서 추론한 명령어와 다른 명령어를 사용하여 앱을 시작하려는 경우 실행 명령어 재정의를 사용하세요.

빌드 출력 구성

App Hosting는 프레임워크에서 표시된 대로 사용하지 않는 출력 파일을 삭제하여 기본적으로 앱 배포를 최적화합니다. 앱 배포 크기를 추가로 최적화하거나 기본 최적화를 무시하려면 apphosting.yaml에서 이를 재정의하면 됩니다.

outputFiles:
  serverApp:
    include: [dist, server.js]

include 매개변수는 앱을 배포하는 데 필요한 앱 루트 디렉터리와 관련된 디렉터리 및 파일 목록을 가져옵니다. 모든 파일을 유지하려면 include를 [.]로 설정하면 모든 파일이 배포됩니다.

보안 비밀 파라미터 저장 및 액세스

API 키와 같은 민감한 정보는 보안 비밀로 저장해야 합니다. apphosting.yaml에서 보안 비밀을 참조하여 민감한 정보를 소스 제어에 체크인하지 않도록 할 수 있습니다.

secret 유형의 매개변수는 Cloud Secret Manager에 값이 저장된 문자열 매개변수를 나타냅니다. 보안 비밀 매개변수는 값을 직접 파생하는 대신 Cloud Secret Manager의 존재 여부를 확인하고 출시 중에 값을 로드합니다.

  -   variable: API_KEY
      secret: myApiKeySecret

Cloud Secret Manager의 보안 비밀에는 여러 버전이 있을 수 있습니다. 기본적으로 라이브 백엔드에서 사용할 수 있는 보안 비밀 파라미터의 값은 백엔드가 빌드된 시점에 사용 가능한 최신 버전의 보안 비밀에 고정됩니다. 매개변수의 버전 관리 및 수명 주기 관리에 대한 요구사항이 있는 경우 Cloud Secret Manager를 사용하여 특정 버전에 고정할 수 있습니다. 예를 들어 버전 5에 고정하려면 다음을 실행합니다.

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

CLI 명령어 firebase apphosting:secrets:set를 사용하여 보안 비밀을 만들 수 있으며 필요한 권한을 추가하라는 메시지가 표시됩니다. 이 흐름을 사용하면 apphosting.yaml에 보안 비밀 참조를 자동으로 추가할 수 있습니다.

Cloud Secret Manager의 전체 기능을 사용하려면 대신 Cloud Secret Manager 콘솔을 사용하세요. 이렇게 하면 CLI 명령어 firebase apphosting:secrets:grantaccess를 사용하여 App Hosting 백엔드에 권한을 부여해야 합니다.

VPC 액세스 구성

App Hosting 백엔드를 Virtual Private Cloud(VPC) 네트워크에 연결할 수 있습니다. 자세한 내용과 예시는 Firebase App Hosting를 VPC 네트워크에 연결을 참고하세요.

apphosting.yaml 파일에서 vpcAccess 매핑을 사용하여 액세스를 구성합니다. 정규화된 네트워크/커넥터 이름 또는 ID를 사용합니다. ID를 사용하면 커넥터/네트워크가 서로 다른 스테이징 환경과 프로덕션 환경 간에 이동할 수 있습니다.

직접 VPC 이그레스 구성 (`apphosting.yaml`):

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

서버리스 커넥터 구성 (`apphosting.yaml`):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

백엔드 관리

App Hosting 백엔드의 기본 관리를 위한 명령어는 Firebase CLI 및 Firebase 콘솔에 제공됩니다. 이 섹션에서는 백엔드 생성 및 삭제를 비롯한 일반적인 관리 작업을 설명합니다.

백엔드 만들기

App Hosting 백엔드는 App Hosting에서 웹 앱을 빌드하고 실행하기 위해 만드는 관리 리소스 모음입니다.

Firebase Console: 빌드 메뉴에서 App Hosting을 선택한 다음 백엔드 만들기를 선택합니다 (Firebase 프로젝트의 첫 번째 백엔드인 경우 시작하기를 선택).

CLI: (버전 13.15.4 이상) 백엔드를 만들려면 로컬 프로젝트 디렉터리의 루트에서 다음 명령어를 실행하고 projectID를 인수로 제공합니다.

firebase apphosting:backends:create --project PROJECT_ID

콘솔 또는 CLI 모두 프롬프트에 따라 리전을 선택하고, GitHub 연결을 설정하고, 다음 기본 배포 설정을 구성합니다.

앱의 루트 디렉터리를 설정합니다 (기본값은 /).

일반적으로 package.json 파일이 있는 폴더입니다.

라이브 브랜치 설정

라이브 URL에 배포되는 GitHub 저장소의 브랜치입니다. 기능 브랜치나 개발 브랜치가 병합되는 브랜치인 경우가 많습니다.
자동 출시 수락 또는 거부

자동 출시가 기본적으로 사용 설정되어 있습니다. 백엔드 생성이 완료되면 앱이 App Hosting에 즉시 배포되도록 선택할 수 있습니다.
백엔드에 이름을 할당합니다.

백엔드 삭제

백엔드를 완전히 삭제하려면 먼저 Firebase CLI 또는 Firebase 콘솔을 사용하여 삭제한 다음 관련 애셋을 수동으로 삭제합니다. 이때 다른 백엔드나 Firebase 프로젝트의 다른 측면에서 사용할 수 있는 리소스는 삭제하지 않도록 특별히 주의하세요.

Firebase Console: 설정 메뉴에서 백엔드 삭제를 선택합니다.

CLI: (버전 13.15.4 이상)

다음 명령어를 실행하여 App Hosting 백엔드를 삭제합니다. 이렇게 하면 백엔드의 모든 도메인이 사용 중지되고 연결된 Cloud Run 서비스가 삭제됩니다.
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
```
(선택사항) Artifact Registry의 Google Cloud 콘솔 탭에서 'firebaseapphosting-images'의 백엔드 이미지를 삭제합니다.
Cloud Secret Manager에서 보안 비밀 이름에 'apphosting'이 포함된 보안 비밀을 삭제합니다. 이러한 보안 비밀이 다른 백엔드나 Firebase 프로젝트의 다른 측면에서 사용되지 않도록 특별히 주의하세요.