App Hosting バックエンドの構成と管理

App Hosting は、使いやすさとメンテナンスのしやすさを考慮して設計されており、デフォルト設定はほとんどのユースケースに最適化されています。同時に、App Hosting には、特定のニーズに合わせてバックエンドを管理、構成するためのツールが用意されています。このガイドでは、これらのツールとプロセスについて説明します。

環境変数とシークレットを設定、更新する

App Hosting では、機密性の低い構成値には環境変数を使用し、API キー、データベース認証情報、サービス トークンなどの機密性の高いパラメータにはシークレットを使用できます。

  • 標準環境変数: 機密性の低い書式なしテキスト構成(公開 API URL、フィーチャー トグル、ビルド ターゲットなど)に使用されます。値はすべてのプロジェクト メンバーに表示されます。
  • シークレット: 機密性の高いパラメータ(OAuth クライアント シークレット、API トークン、データベース パスワードなど)に使用されます。シークレットは Cloud Secret Manager によってバックアップされます。シークレット値は保護され、Firebase コンソールに書式なしテキストで表示されることはありません。代わりに、コンソールには、Cloud Secret Manager でシークレット値を直接表示して管理するためのディープリンクが用意されています。

環境パラメータは、次の 2 つの補完的なアプローチを使用して定義および管理できます。

  • Firebase コンソール: バックエンドの初期作成時またはデプロイ後のバックエンド設定で、シークレットや変数を動的に追加、編集、アタッチできます。
  • コードファースト(apphosting.yaml): バージョン管理されたデプロイ用に、リポジトリの構成ファイルで環境変数とシークレット参照を宣言します。または、apphosting.<env>.yaml を使用して、環境ごとに異なる値を設定します。

Firebase コンソール

環境変数を追加するための Firebase コンソール ダイアログのスクリーンショット

apphosting.yaml

env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
  - variable: API_KEY
    secret: myApiKeySecret

Firebase コンソールで変数とシークレットを管理する

環境変数とシークレットは、バックエンドの作成時に Firebase コンソールで構成することも、バックエンドの設定からいつでも構成することもできます。デプロイせずに保存した変更は、次回のロールアウト時に有効になり、現在のロールアウトには影響しません。

バックエンドの作成時に変数とシークレットを設定する

Firebase コンソールで新しい App Hosting バックエンドを作成するときに、設定ウィザードの [バックエンドを構成する] ステップで、標準の環境変数とシークレットを構成できます。

  1. Firebase コンソールで、[Hosting & Serverless] > [App Hosting] に移動し、[バックエンドを作成] をクリックします。
  2. 最初のウィザードの手順を完了して、プライマリ リージョンとコード リポジトリを選択します。
  3. [バックエンドを構成する] セクションで、[環境変数] と [シークレット] の折りたたみ可能なカードを見つけます。ここで、標準変数を追加してシークレットをアタッチできます。
  4. バックエンド作成ウィザードを完了し、[Finish & deploy] をクリックします。

バックエンド設定で変数とシークレットを管理する

アクティブなバックエンドの環境変数とシークレットは、バックエンド設定ダッシュボードで表示、追加、編集、削除できます。

  1. Firebase コンソールで、App Hosting バックエンドを選択し、[設定] > [環境] を開きます。
  2. [環境変数] テーブルで既存の構成を確認します。
    • 標準変数: 値は、コピー可能なコードブロックに書式なしテキストとして表示されます。
    • シークレット: シークレット名(Google Cloud コンソールで Cloud Secret Manager を開く)と、ターゲット バージョン(latest や 2 などの特定のバージョン番号)を示すクリック可能なリンクとして表示されます。
  3. 変数またはシークレットを追加するには:
    1. [新しく追加] をクリックします。
    2. [ステップ 1: タイプを選択] で、[標準環境変数](すべてのプロジェクト メンバーに表示される機密性の低いデータの場合)または [シークレット](アクセスが制限された API キーと機密性の高い認証情報の場合)を選択し、[次へ] をクリックします。
    3. ステップ 2: 設定を構成するで、[キー] 名と、書式なしテキストの [値](標準変数の場合)を入力するか、[シークレット] ID と [バージョン](シークレットの場合)を選択します。
    4. 次のいずれかのオプションを使用して変更を保存します。
      • 保存してデプロイ: バックエンド構成をすぐに更新し、新しいビルドとロールアウトをトリガーします。
      • 保存のみ([保存してデプロイ] の横にあるプルダウン矢印から選択): 即時のロールアウトをトリガーせずに、構成の変更を保存します。更新された設定は、次回のデプロイ時に有効になります。
  4. 既存のエントリを編集または削除するには、行の末尾にある [操作メニュー](...)をクリックします。
    • [編集] を選択して、キー、値、シークレット マッピング、バージョンを変更し、[保存してデプロイ] または [保存のみ] をクリックします。
    • [削除] を選択し、ダイアログで削除を確定します。

dotenv ファイルから変数を転送する

Next.js アプリの場合、環境変数を含む dotenv ファイルは App Hosting で動作します。

バックエンドを作成または更新するときに、dotenv ファイルの内容全体をコピーして、[設定] > [環境] の [新規追加] フォームの最初の [キー] フィールドに貼り付けることで、dotenv ファイルから Firebase コンソールに環境変数を転送できます。

この方法でコピーされたすべての環境変数は、入力に標準の KEY=value 形式が使用されている限り、個別に指定しなくても自動的にフォームにフォーマットされます。

KEY1=value1
KEY2=value2
KEY3=value3

任意のフレームワークで複雑な環境変数やきめ細かい環境変数を制御する場合は、apphosting.yaml を使用することをおすすめします。

apphosting.yaml で変数とシークレットを管理する

コードファースト ワークフローの場合は、プロジェクト リポジトリの apphosting.yaml 構成ファイルの env: キーで、標準の環境変数とシークレット参照を宣言します(apphosting.yaml を作成して編集するをご覧ください)。

env:
  # Standard environment variables
  - variable: PUBLIC_API_URL
    value: https://api.example.com
    availability:
      - BUILD
      - RUNTIME
  - variable: FEATURE_FLAG_NEW_UI
    value: "true"

  # Secret references backed by Cloud Secret Manager
  - variable: DATABASE_URL
    secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
  - variable: GEMINI_API_KEY
    secret: myGeminiApiKeySecret@1

env: の各エントリは、次のフィールドをサポートしています。

  • variable: アプリケーション プロセスに公開される環境変数名。
  • value: 書式なしテキストの文字列値(標準の環境変数の場合)。
  • secret: Cloud Secret Manager のシークレット参照(シークレットの場合)。短いシークレット名(myGeminiApiKeySecret や固定された myGeminiApiKeySecret@1 など)または完全なリソースパス(projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION)を使用できます。詳細については、シークレット パラメータを保存してアクセスするをご覧ください。
  • availability: BUILD フェーズ、RUNTIME、またはその両方で変数またはシークレットにアクセスできるかどうかを制御します。

変数の可用性を設定する

Firebase コンソールで構成された環境変数とシークレットは、ビルド時とランタイムの両方で使用できます。これは、availability プロパティを使用してスコープを絞り込まない限り、apphosting.yaml で定義されたエントリのデフォルトの動作でもあります。apphosting.yaml(コンソールではない)では、変数またはシークレットをビルド環境(BUILD)のみ、またはランタイム環境(RUNTIME)のみに制限できます。

アプリケーション コードで変数とシークレットにアクセスする

Firebase コンソールまたは apphosting.yaml で構成されているかどうかにかかわらず、環境変数とシークレットは、標準の環境変数(Node.js の process.env など)としてアプリケーション ランタイムに公開されます。

// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;

// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;

export async function fetchData() {
  const response = await fetch(`${apiUrl}/data`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  return response.json();
}
  • サーバーサイド アクセス: すべての環境変数とシークレットは、サーバーサイドの実行コンテキスト(Next.js サーバー コンポーネント、API ルート、Node.js バックエンド ハンドラなど)で安全にアクセスできます。
  • クライアントサイドの公開: Next.js などのフレームワークで標準環境変数をブラウザに公開するには、変数キーがフレームワークの規則に従っていることを確認します(例: NEXT_PUBLIC_ という接頭辞が付いている)。

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

変数の階層

Firebase App Hosting は、ソースに基づいて優先順に環境変数とシークレットを適用します。Firebase コンソールで設定された構成は、apphosting.yaml ファイルと dotenv ファイルで宣言されたパラメータを常にオーバーライドします。同じ名前の環境変数またはシークレット キーが apphosting.yaml と Firebase コンソールの両方に存在する場合、ビルドとランタイムの実行中にコンソールの値が優先されます。

優先順位は次のとおりです。

  1. Firebase コンソール → コンソールで設定された変数とシークレット
  2. apphosting.<env>.yaml → apphosting.staging.yaml などの環境固有の YAML ファイルで指定された変数とシークレット(複数の環境をデプロイするをご覧ください)
  3. apphosting.yaml → apphosting.yaml ファイルで指定された変数とシークレット
  4. Firebase システム → FIREBASE_CONFIG または FIREBASE_WEBAPP_CONFIG の値を含む Firebase によって設定される変数。SSR アプリのホスト名とポートを設定する環境変数(bundle.yaml の App Hosting アダプタによって設定される)

自動的に設定される環境変数

App Hosting によって自動的に設定される環境変数があります。これには、Google Cloud によって入力される環境変数と、設定時にバックエンドで appId が設定されている場合の Firebase 固有の環境変数があります。

  • 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"
    }</span>
    

    Firebase JS SDK は、ビルド中にインストール後のスクリプトでこの FIREBASE_WEBAPP_CONFIG 環境変数を自動的にチェックします。これにより、引数を指定せずにクライアント SDK を初期化することもできます。

これらの環境変数を使用して SDK を初期化する方法については、Firebase Admin SDK とウェブ SDK を自動的に初期化するをご覧ください。

実際の Firebase 構成の値は、プロジェクトでプロビジョニングした特定のリソースに対応します。

変数の階層

Firebase App Hosting は、ソースに基づいて優先順に変数に適用します。たとえば、Firebase コンソールで設定された値は、apphosting.yaml ファイルと dotenv ファイルで設定された値よりも常に優先されます。

優先順位は次のとおりです。

  1. Firebase コンソール → コンソールで設定された変数
  2. apphosting.<env>.yaml → apphosting.staging.yaml などの環境固有の YAML ファイルで指定された変数(複数の環境をデプロイするをご覧ください)
  3. apphosting.yaml → apphosting.yaml ファイルで指定された変数
  4. Firebase システム → firebase_config json または firebase_webapp_config の値を含む Firebase によって設定される変数。SSR アプリのホスト名とポートを設定する環境変数(bundle.yaml の App Hosting アダプタによって設定される)

予約済みの名前と制限事項

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 サービスのプロビジョニング方法を構成できます。Cloud Run サービスで使用可能な設定は、runConfig オブジェクトで指定します。

  • cpu - 各サービング インスタンスに使用される CPU の数(デフォルトは 1)。
  • memoryMiB - 各サービス インスタンスに割り当てられるメモリ量(MiB 単位、デフォルトは 512)。
  • maxInstances – 一度に実行されるコンテナの最大数(デフォルトは 100 で、割り当てによって管理されます)。
  • minInstances - 常に維持するコンテナの数(デフォルトは 0)。
  • concurrency - 各サービング インスタンスが受信できるリクエストの最大数(デフォルトは 80)。
  • cpuAlwaysAllocated - リクエストが処理されていない場合でも CPU を常に割り当てるかどうか(デフォルトは false)。

cpu、memoryMiB、concurrency には相互依存の上限があります(たとえば、メモリ構成を高くすると、CPU の最小上限を高くする必要があり、CPU の一部を使用する場合は同時実行を 1 にする必要があります)。有効な範囲と必要な組み合わせについては、CPU の上限とメモリの上限に関する Cloud Run のドキュメントをご覧ください。

ビルド スクリプトと実行スクリプトをオーバーライドする

App Hosting は、検出されたフレームワークに基づいてアプリのビルドコマンドと起動コマンドを推測します。カスタムビルドまたは起動コマンドを使用する場合は、apphosting.yaml で App Hosting のデフォルトをオーバーライドできます。

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

ビルドコマンドのオーバーライドは他のビルドコマンドよりも優先され、アプリはフレームワーク アダプタからオプトアウトされ、App Hosting が提供するフレームワーク固有の最適化が無効になります。これは、アプリの機能がアダプタで十分にサポートされていない場合に最適です。ビルドコマンドを変更しても、提供されたアダプタを使用する場合は、App Hosting フレームワーク アダプタの説明に沿って、package.json にビルド スクリプトを設定します。

App Hosting で推測されたコマンドとは異なる特定のコマンドを使用してアプリを起動する場合は、実行コマンドのオーバーライドを使用します。

ビルド出力を構成する

App Hosting は、フレームワークで示されているように、未使用の出力ファイルを削除することで、デフォルトでアプリのデプロイを最適化します。アプリのデプロイサイズをさらに最適化する場合や、デフォルトの最適化を無視する場合は、apphosting.yaml でオーバーライドできます。

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

include パラメータは、アプリのデプロイに必要なアプリのルート ディレクトリを基準としたディレクトリとファイルのリストを受け取ります。すべてのファイルを保持する場合は、include を [.] に設定すると、すべてのファイルがデプロイされます。

シークレット パラメータを保存してアクセスする

API キーなどの機密情報は、Secret として保存する必要があります。Firebase コンソールでシークレットをバックエンドにアタッチするか、apphosting.yaml でシークレットを参照して、機密情報がソース管理にチェックインされないようにできます。

secret 型のパラメータは、Cloud Secret Manager に保存された値を持つ文字列パラメータを表します。シークレット パラメータは、値を直接導出するのではなく、Cloud Secret Manager に存在するかどうかを確認し、ロールアウト中に値を読み込みます。

env:
  - variable: API_KEY
    secret: myApiKeySecret

Cloud Secret Manager の Secret には複数のバージョンを設定できます。デフォルトでは、ライブ バックエンドで使用可能なシークレット パラメータの値は、バックエンドのビルド時に使用可能なシークレットの最新バージョンに固定されます。パラメータのバージョニングとライフサイクル管理の要件がある場合は、Firebase コンソールまたは apphosting.yaml で特定のバージョンに固定できます。たとえば、apphosting.yaml でバージョン 5 に固定するには、次のようにします。

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Firebase CLI コマンド firebase apphosting:secrets:set を使用して Secret を作成できます。必要な権限を追加するように求められます。このフローでは、シークレット参照を apphosting.yaml に自動的に追加するオプションが用意されています。

Cloud Secret Manager へのアクセス権を付与する

App Hosting がビルドとランタイムのロールアウト中にシークレット値を取得するには、App Hosting バックエンド サービス アカウントに Cloud Secret Manager へのアクセス権が必要です。

firebase apphosting:secrets:set ではなく Cloud Secret Manager コンソールまたは gcloud CLI を使用してシークレットを作成する場合は、Firebase CLI を使用してバックエンドへのアクセス権を付与します。

firebase apphosting:secrets:grantaccess SECRET_NAME

または、gcloud CLI を使用して、App Hosting サービス エージェント(service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com)またはバックエンドのランタイム サービス アカウントに Secret Manager シークレット アクセサーのロール(roles/secretmanager.secretAccessor)を付与することもできます。

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

コンソールへのアクセスとロールベースの権限

Firebase コンソールでは、ユーザーの IAM 権限に基づいて、環境と Secret Manager の管理機能が動的に制限されます。

  • 閲覧者ロール: プロジェクトの読み取り専用権限を持つユーザーは、既存の構成設定を表示できますが、変更はできません。
    • バックエンドの作成中、[バックエンドを作成] ボタンは無効になります。
    • バックエンドの [設定] > [環境] で、[新規追加] ボタンが無効になり、[その他の操作](...)行メニューが非表示になります。
  • Secret Manager の権限がない: Cloud Secret Manager を操作するための IAM 権限がないユーザーには、コンソールに警告メッセージ(シークレットを追加する権限をプロジェクト オーナーにリクエストしてください)が表示されます。
    • バックエンドの作成中は、[シークレット] カードが無効になります。
    • バックエンドの [設定] > [環境] で、[新規追加] をクリックすると [シークレット] オプションが無効になり、[その他の操作](...)行メニューの一部のオプションが既存のシークレット エントリで非表示になります。

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 コンソールと Firebase CLI で提供されています。このセクションでは、バックエンドの作成や削除など、一般的な管理タスクについて説明します。

バックエンドの作成

App Hosting バックエンドは、App Hosting がウェブアプリの構築と実行のために作成するマネージド リソースのコレクションです。

Firebase コンソール: [Hosting & Serverless] > [App Hosting] に移動し、[バックエンドを作成] をクリックします(Firebase プロジェクトの最初のバックエンドの場合は、[使ってみる] をクリックします)。

Firebase CLI:(v13.15.4 以降)バックエンドを作成するには、ローカル プロジェクト ディレクトリのルートから次のコマンドを実行し、プロジェクト ID を引数として指定します。

firebase apphosting:backends:create --project PROJECT_ID

コンソールまたは CLI のどちらの場合も、プロンプトに沿ってリージョンを選択し、GitHub 接続を設定して、次の基本的なデプロイ設定を構成します。

  • アプリのルート ディレクトリを設定します(デフォルトは /)。

    通常、ここに package.json ファイルが配置されます。

  • ライブブランチを設定する

    これは、一般公開 URL にデプロイされる GitHub リポジトリのブランチです。多くの場合、これは機能ブランチまたは開発ブランチがマージされるブランチです。

  • 自動ロールアウトを承認または拒否する

    自動ロールアウトはデフォルトで有効になっています。バックエンドの作成が完了すると、アプリを App Hosting にすぐにデプロイすることを選択できます。

  • バックエンドに名前を割り当てます。

  • ランタイム環境を選択します。デフォルトでは、最新の推奨 Node.js バージョンが事前に選択されています。

    • ベースイメージの自動更新(ABIU)を構成します。ABIU はデフォルトで有効になっており、基盤となる環境にセキュリティ パッチを自動的に適用します。ABIU を無効にするには、ランタイムで [指定なし] を選択します。

バックエンドの削除

バックエンドを完全に削除するには、まず Firebase コンソールまたは Firebase CLI を使用して削除します。その後、関連するアセットを手動で削除します。このとき、他のバックエンドや Firebase プロジェクトの他の部分で使用されている可能性のあるリソースを削除しないように注意してください。

Firebase コンソール: [設定] メニューから [バックエンドを削除] を選択します。

Firebase CLI:(v13.15.4 以降)

  1. 次のコマンドを実行して、App Hosting バックエンドを削除します。これにより、バックエンドのすべてのドメインが無効になり、関連付けられている Cloud Run サービスが削除されます。

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
    
  2. (省略可)Artifact Registry の Google Cloud コンソール タブで、「firebaseapphosting-images」にあるバックエンドのイメージを削除します。

  3. Cloud Secret Manager で、シークレット名に「apphosting」が含まれるシークレットを削除します。これらのシークレットが他のバックエンドや Firebase プロジェクトの他の部分で使用されていないことを確認してください。