App Hosting 백엔드 구성 및 관리

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

환경 변수 설정 및 업데이트

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

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

Firebase console

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

`apphosting.yaml`

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

변수 업데이트

Firebase 콘솔 또는 apphosting.yaml을 사용하여 환경 변수를 추가, 수정 또는 삭제할 수 있습니다.

Firebase Console:
1. Firebase Console에서 호스팅 및 서버리스 > App Hosting으로 이동합니다.
2. 백엔드 보기 > 설정 > 환경 으로 이동합니다.
3. 환경 변수를 추가, 수정 또는 삭제합니다.
apphosting.yaml:

파일을 수동으로 만들고 수정하는 방법을 알아보세요.

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

변수 사용 가능 여부 설정

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

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 파일의 환경 변수를 Firebase Console로 전송하려면 dotenv 파일의 전체 콘텐츠를 환경 변수 설정의 '새로 추가' 양식에 있는 첫 번째 '키' 필드에 복사하여 붙여넣으면 됩니다.

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

KEY1=value1
KEY2=value2
KEY3=value3

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

자동으로 채워지는 환경 변수

App Hosting에서 자동으로 채워지는 환경 변수가 있습니다. App Hosting. 여기에는 설정 중에 백엔드에 appId 가 설정된 경우 Google Cloud에서 채워지는 환경 변수와 Firebase 관련 환경 변수가 포함됩니다.Google Cloud

FIREBASE_CONFIG: (빌드 및 런타임 환경에서 사용 가능) 다음 Firebase 프로젝트 구성 정보를 제공합니다.
```
{
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
  "projectId": 'PROJECT_ID'
}
```
이 구성은 인수 없이 Firebase Admin SDK를 초기화할 때 자동으로 적용됩니다.
FIREBASE_WEBAPP_CONFIG: (빌드 환경에서만 사용 가능) 다음 Firebase 프로젝트 구성 정보를 제공합니다.
```
{
  "apiKey": 'API_KEY',
  "appId": 'APP_ID',
  "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "messagingSenderId": 'PROJECT_NUMBER',
  "projectId": 'PROJECT_ID',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
}
```
Firebase JS SDK는 빌드 중에 postinstall 스크립트에서 이 FIREBASE_WEBAPP_CONFIG 환경 변수를 자동으로 확인하므로 인수 없이 클라이언트 SDK를 초기화할 수도 있습니다.

Firebase Admin SDK 및 웹 SDK 자동 초기화 에서 이러한 환경 변수를 사용하여 SDK를 초기화하는 방법에 관한 자세한 내용을 확인하세요.

실제 Firebase 구성의 값은 프로젝트에서 프로비저닝한 특정 리소스에 해당합니다.

변수 계층 구조

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

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

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

예약된 이름 및 제한사항

Cloud Run 컨테이너 런타임 계약 에 정의된 환경 변수는 예약되어 있으며 설정할 수 없습니다.

환경에서 제공된 환경 변수(자동으로 설정된 변수 이외)는 나중에 런타임 버전에서 변경될 수 있습니다. 명시적으로 설정하지 않은 환경 변수를 사용하거나 수정하지 않는 것이 좋으며 모든 환경 변수에 고유 키를 사용하여 프리픽스로 지정하여 충돌을 피하는 것이 좋습니다.

일부 환경 변수 키는 내부에서 사용하도록 예약되어 있습니다. 구성 파일에는 다음 키를 사용하지 마세요.

빈 문자열("")
'=' 기호가 포함된 키
X_FIREBASE_, X_GOOGLE_, CLOUD_RUN_으로 시작하는 키
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 서비스가 프로비저닝되는 방식을 구성할 수 있습니다. 서비스에 사용할 수 있는 설정은 runConfig 객체에 제공됩니다.Cloud Run

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은 감지된 프레임워크를 기반으로 앱의 빌드 및 시작 명령어를 추론합니다. 커스텀 빌드 또는 시작 명령어를 사용하려면 App Hosting의 기본값을 apphosting.yaml에서 재정의하면 됩니다.

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

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

App Hosting에서 추론한 명령어와 다른 특정 명령어를 사용하여 앱을 시작하려는 경우 실행 명령어 재정의를 사용합니다.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

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

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

VPC 액세스 구성

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

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 Console과 Firebase CLI에 제공됩니다. 이 섹션에서는 백엔드 만들기 및 삭제를 비롯한 몇 가지 일반적인 관리 작업을 설명합니다.

백엔드 만들기

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

Firebase 콘솔: 호스팅 및 서버리스 > App Hosting으로 이동한 후 백엔드 만들기를 클릭합니다 (Firebase 프로젝트의 첫 번째 백엔드인 경우 시작하기 클릭).

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

firebase apphosting:backends:create --project PROJECT_ID

Console 또는 CLI 모두에서 메시지에 따라 리전을 선택하고 GitHub 연결을 설정하고 다음과 같은 기본 배포 설정을 구성합니다.

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

일반적으로 package.json 파일이 있는 위치입니다.

라이브 브랜치 를 설정합니다.

라이브 URL에 배포되는 GitHub 저장소의 브랜치입니다. 일반적으로 기능 브랜치 또는 개발 브랜치가 병합되는 브랜치입니다.
자동 출시 버전 을 수락하거나 거부합니다.

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

백엔드 삭제

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

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

Firebase CLI: (v13.15.4 이상)

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