App Engine でデプロイエラーが発生する原因としては、権限不足、組織のポリシーの変更、アプリ構成の問題など、いくつかの問題があります。
このページでは、App Engine で発生する一般的なデプロイエラーと、そのトラブルシューティング方法について説明します。
権限に関するエラー
このセクションでは、アカウント権限がない、または組織のポリシーが変更されたためにアプリのデプロイ時に発生する可能性のあるエラーについて説明します。
Google Cloud Platform で Google Cloud CLI やその他のツールにアクセスするために使用しているアクティブなアカウントを特定するには、次のいずれかを行います。
Google Cloud CLI を使用してデプロイした場合は、
gcloud auth listコマンドを実行します。IDE からデプロイした場合は、Cloud Tools プラグインの設定を表示します。
App Engine デプロイ担当者（roles/appengine.deployer）のロールのみでは十分でない理由については、App Engine のロールをご覧ください。
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
新しいプロジェクトのデプロイに失敗する
新しいプロジェクトに初めてアプリをデプロイすると、次のエラーが表示されることがあります。
ERROR: (gcloud.app.deploy) Error Response: [13] Failed to create cloud build: com.google.net.rpc3.client.RpcClientException:..........invalid bucket "staging.PROJECT_ID.appspot.com"; service account PROJECT_ID@appspot.gserviceaccount.com does not have access to the bucket
この問題を解決するには、デフォルトのサービス アカウントにストレージ管理者（roles/storage.admin）のロールを付与します。詳細については、ユーザーが作成したバケットにビルドログを保存するをご覧ください。
デプロイ中に発生したさまざまな権限エラーに基づいて、ストレージ管理者ロールと他の必要なロールを付与しているにもかかわらず、アプリをデプロイできない場合は、組織のポリシーに次の変更が加えられている可能性があります。
2024 年 5 月以降、 Google Cloud はすべての組織リソースにデフォルトで保護されている組織のポリシーを適用します。このポリシーにより、App Engine が App Engine のデフォルトのサービス アカウントに
Editorロールを付与できなくなります。2024 年 6 月より、Cloud Build が新しいプロジェクトでサービス アカウントを使用する際のデフォルトの動作が変更されています。この変更の詳細については、Cloud Build サービス アカウントの変更をご覧ください。この変更により、バージョンを初めてデプロイする新しいプロジェクトで、バージョンのデプロイに必要な権限が不足しているデフォルトの App Engine サービス アカウントが使用される可能性があります。
この問題を解決するには、次の操作を行います。
App Engine のデフォルトのサービス アカウント（
PROJECT_ID@appspot.gserviceaccount.com）にEditorロールを付与します。デフォルトのサービス アカウントの変更に関する Cloud Build のガイダンスを確認し、新しいプロジェクトのデフォルトの変更をオプトアウトします。
呼び出し元にプロジェクトにアクセスする権限がない
サービス アカウントに対して、現在のプロジェクトにアプリをデプロイする権限を付与していない場合、次のエラーが発生します。
User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist).
この問題を解決するには、サービス アカウントに App Engine デプロイ担当者（roles/appengine.deployer）のロールを付与します。
レジストリからメタデータを取得できない
ストレージ管理者（roles/storage.admin）ロールを持たないサービス アカウントから gcloud app deploy コマンドを使用すると、次のエラーが発生します。
Failed to fetch metadata from the registry, with reason: generic::permission_denied
この問題を解決するには、サービス アカウントにストレージ管理者のロールを付与します。
イメージに対する権限がサービス アカウントに必要
アプリをデプロイすると、次のエラーが発生します。
The App Engine appspot and App Engine flexible environment service accounts must
have permissions on the image IMAGE_NAME
このエラーは、次のいずれかの理由によって発生します。
デフォルトの App Engine サービス アカウントに、Storage オブジェクト閲覧者（
roles/storage.objectViewer）ロールがない。この問題を解決するには、サービス アカウントに Storage オブジェクト閲覧者ロールを付与します。
アクセスレベルを使用して Cloud Storage API へのアクセスを制限する VPC Service Controls サービス境界がプロジェクトに存在する。
この問題を解決するには、アプリのデプロイに使用するサービス アカウントを、対応する VPC Service Controls サービス境界の accessPolicies に追加します。
2024 年 5 月 15 日以降、Artifact Registry は、Container Registry の使用歴がない Google Cloud プロジェクトで
gcr.ioドメインのイメージをホストします。この日以降に作成された新しいプロジェクトに既存のアプリケーションをデプロイする場合、サービス アカウントにアプリのデプロイに必要な権限がない可能性があります。必要な権限を付与するには、App Engine へのデプロイをご覧ください。
Cloud Build の作成に失敗
Cloud Build 編集者（roles/cloudbuild.builds.editor）ロールを持たないサービス アカウントから gcloud app deploy コマンドを使用すると、次のエラーが発生します。
Failed to create cloud build: Permission denied
この問題を解決するには、サービス アカウントに Cloud Build 編集者ロールを付与します。
アプリケーションの取得中にエラーが発生する
アプリのデプロイに使用したサービス アカウントに App Engine デプロイ担当者のロールがない場合は、次のエラーが発生します。
Permissions error fetching application apps/app_name. Please make sure you are using the correct project ID and that you have permission to view applications on the project.
If you are running Google Cloud CLI version 328 or later, the following error occurs
when you deploy your app:
make sure that you have permission to view applications on the project and that
SERVICE_ACCOUNT has the App Engine Deployer (roles/appengine.deployer) role.
この問題を解決するには、アプリのデプロイに使用したサービス アカウントに App Engine デプロイ担当者のロールを付与します。
サーバーレス VPC アクセス コネクタを使用してサービスをデプロイするとエラーが発生する
サーバーレス VPC アクセス コネクタを使用してアプリをデプロイしようとしているユーザーまたはサービス アカウントに必要な権限がない場合は、次のエラーが発生します。
Please ensure you have [compute.globalOperations.get] on the service project
この問題を解決するには、デプロイを行うユーザーまたはサービス アカウントに、サーバーレス VPC アクセス ユーザーのロールと Compute 閲覧者 IAM ロールを付与します。
デプロイに関する一般的なエラー
このセクションでは、アプリまたはプロジェクトの構成エラーのトラブルシューティング方法について説明します。
共有 VPC 設定内でのデプロイ時に発生する無効な値のエラー
アプリをデプロイするときに柔軟な VM インスタンスの Cloud Logging に次のエラーが表示されます。
Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert
これは既知の問題で、app.yaml ファイルで instance_tag を設定すると、インスタンスの作成時にエラーが発生します。
この問題を解決するには、app.yaml ファイルから instance_tag フィールドを削除して再デプロイします。
最大インスタンス数が 3 以下のアプリをデプロイする際に発生するエラー
max_instances を 3 以下に設定してアプリをデプロイすると、予期しないエラーやダウンタイムが発生する可能性があります。この問題を解決するには、app.yaml ファイルに 4 つ以上の最大インスタンス数を指定して再デプロイします。
最大インスタンス数の上限を超えた
アプリをデプロイすると、次のエラーが発生します。
You may not have more than 'xx' total max instances in your project.
プロジェクトごとに作成できるインスタンスには上限があります。この上限を超えると、追加のインスタンスの作成リクエストは失敗します。
この問題を解決するには、app.yaml ファイルの max_instances の値をこの上限を下回る値に設定するか、一部のサービスまたはバージョンを削除して max_instances の合計が上限内に収まるようにします。
デプロイ中のビルドが失敗しログにエラーが記録されない
アプリをデプロイすると、次のエラーが発生します。
ERROR: (gcloud.app.deploy) Cloud build failed. Check logs at https://console.cloud.google.com/cloud-build/builds/BUILD_ID?project=PROJECT_NUMBER Failure status: UNKNOWN: Error Response: [2] Build failed; check build logs for details
エラー メッセージのリンクをクリックして、すべてのビルドステップが正常に完了しているのに、アプリがビルドされない場合は、次のいずれかの理由が考えられます。
この問題を解決するには、バケットの以下の設定を変更します。
- 暗号化を Google-owned and Google-managed encryption keys に設定します。
- 保持ポリシーを削除します。
Node.js アプリケーションの実行時にビルドが失敗する
Node.js アプリケーションをデプロイする際に、ビルドエラーが発生することがあります。
デフォルトでは、package.json ファイルでバッチ スクリプトが検出されると、Node.js ランタイムは npm run build を実行します。その結果、長時間実行ビルドやメモリ不足エラーのような予期しない動作が発生する可能性があります。
この問題を解決するには、app.yaml ファイルに NODE_ENV=development を指定して、実行に必要な依存関係がすべて存在するようにします。
エラーにもかかわらず、app.yaml ファイルの build-env-variables で NODE_ENV: 'production' を指定すると、本番環境を強制できます。
build_env_variables:
NODE_ENV: 'production'
詳細については、デプロイ時のカスタムビルド ステップの実行をご覧ください。