Risolvere i problemi di deployment in App Engine

Diversi fattori possono causare errori di deployment in App Engine, tra cui autorizzazioni mancanti, modifiche alle policy dell'organizzazione e problemi nella configurazione dell'app.

Questa pagina descrive i seguenti errori di deployment comuni in App Engine e i metodi per risolverli:

Errori di autorizzazione

Questa sezione descrive gli errori che potrebbero verificarsi durante il deployment dell'app a causa di autorizzazioni dell'account mancanti o modifiche alle norme dell'organizzazione.

Per identificare l'account attivo che utilizzi per accedere a Google Cloud CLI e ad altri strumenti nella piattaforma Google Cloud , esegui una delle seguenti operazioni:

  • Se hai utilizzato Google Cloud CLI per il deployment, esegui il comando gcloud auth list.

  • Se hai eseguito il deployment da un IDE, visualizza le impostazioni del plug-in Cloud Tools.

Per scoprire perché l'assegnazione del solo ruolo di Deployer App Engine (roles/appengine.deployer) potrebbe non essere sufficiente in alcuni casi, consulta Ruoli App Engine.

Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

L'deployment non riesce per i nuovi progetti

Potresti visualizzare il seguente errore quando esegui il deployment della tua app per la prima volta in un nuovo progetto:

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

Per risolvere il problema, concedi il ruolo Amministratore di Storage (roles/storage.admin) al account di servizio predefinito. Per maggiori informazioni, vedi Archiviare i log di build in un bucket creato dall'utente.

Se hai già concesso il ruolo Amministratore storage, insieme agli altri ruoli richiesti in base ai diversi errori di autorizzazione che si verificano durante il deployment, e non riesci ancora a eseguire il deployment dell'app, il problema potrebbe essere dovuto ai seguenti cambiamenti ai criteri dell'organizzazione:

  • A partire da maggio 2024, Google Cloud applica policy dell'organizzazione sicure per impostazione predefinita a tutte le risorse dell'organizzazione. Questo criterio impedisce ad App Engine di concedere il ruolo Editor ai service account predefiniti di App Engine.

  • A giugno 2024, Cloud Build ha modificato il comportamento predefinito per la modalità di utilizzo degli account di servizio nei nuovi progetti. Questo è descritto in dettaglio in Modifica del account di servizio Cloud Build. A seguito di questa modifica, i nuovi progetti che eseguono il deployment delle versioni per la prima volta potrebbero utilizzare il account di servizio App Engine predefinito con autorizzazioni insufficienti per il deployment delle versioni.

Per risolvere il problema, segui questi passaggi:

Il chiamante non dispone dell'autorizzazione per accedere al progetto

Si verifica il seguente errore se il account di servizio non dispone dell'autorizzazione per eseguire il deployment delle app nel progetto corrente:

User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist).

Per risolvere il problema, concedi il ruolo Deployment App Engine (roles/appengine.deployer) al account di servizio.

Impossibile recuperare i metadati dal registry

Se utilizzi il comando gcloud app deploy da un service account che non dispone del ruolo Storage Admin (roles/storage.admin), si verifica il seguente errore:

Failed to fetch metadata from the registry, with reason: generic::permission_denied

Per risolvere il problema, concedi il ruolo Amministratore Storage al account di servizio.

I service account devono disporre delle autorizzazioni per l'immagine

Quando esegui il deployment dell'app, si verifica il seguente errore:

The App Engine appspot and App Engine flexible environment service accounts must
have permissions on the image IMAGE_NAME

Questo errore si verifica per uno dei seguenti motivi:

  • Il account di servizio App Engine predefinito non dispone del ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer).

    Per risolvere il problema, assegna il ruolo Visualizzatore oggetti Storage al account di servizio.

  • Il tuo progetto ha un perimetro di servizio Controlli di servizio VPC che limita l'accesso all'API Cloud Storage utilizzando i livelli di accesso.

    Per risolvere il problema, aggiungi il account di servizio che utilizzi per il deployment dell'app al perimetro di servizio Controlli di servizio VPC accessPolicies corrispondente.

  • Dopo il 15 maggio 2024, Artifact Registry ospita le immagini per il dominio gcr.io nei progetti Google Cloud senza precedente utilizzo di Container Registry. Se esegui il deployment di un'applicazione esistente in un nuovo progetto creato dopo questa data, il account di servizio potrebbe non disporre delle autorizzazioni necessarie per eseguire il deployment dell'app. Per concedere le autorizzazioni necessarie, consulta Deployment in App Engine.

Impossibile creare Cloud Build

Il seguente errore si verifica se utilizzi il comando gcloud app deploy da un service account che non dispone del ruolo Editor Cloud Build (roles/cloudbuild.builds.editor).

Failed to create cloud build: Permission denied

Per risolvere il problema, concedi il ruolo Editor Cloud Build al account di servizio.

Errore durante il recupero dell'applicazione

Il seguente errore si verifica quando il account di servizio che hai utilizzato per eseguire il deployment della tua app non dispone del ruolo App Engine Deployer.

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.

Per risolvere il problema, assegna il ruolo Deployer App Engine al service account che hai utilizzato per il deployment dell'app.

Errore durante il deployment di un servizio con un connettore di accesso VPC serverless

Si verifica il seguente errore quando l'utente o il account di servizio che tenta di eseguire il deployment dell'app con un connettore di accesso VPC serverless non dispone delle autorizzazioni richieste:

Please ensure you have [compute.globalOperations.get] on the service project

Per risolvere il problema, assicurati che l'utente o il account di servizio utilizzato per il deployment disponga dei ruoli IAM Utente accesso VPC serverless e Visualizzatore Compute.

Timeout durante l'attesa dell'integrità dell'infrastruttura dell'app

Quando esegui il deployment dell'app, si verifica il seguente errore:

Timed out waiting for the app infrastructure to become flex_await_healthy

Questo errore può essere causato da vari fattori, ad esempio autorizzazioni mancanti, errori di codice, CPU o memoria insufficienti o controlli di integrità non riusciti.

Per risolvere il problema, escludi le seguenti potenziali cause:

  1. Controlla se il criterio dell'organizzazione per il tuo progetto limita l'accesso agli indirizzi IP esterni. Per ulteriori informazioni, vedi Problemi noti dell'ambiente flessibile di App Engine.

  2. Verifica di aver concesso i seguenti ruoli al account di servizio che utilizzi per eseguire l'applicazione (di solito il account di servizio predefinito, app-id@appspot.gserviceaccount.com):

  3. Concedi i ruoli rimanenti in base agli errori di deployment, se il account di servizio non li ha.

  4. Se esegui il deployment in una configurazione VPC condiviso e configuri un instance_tag nel file app.yaml, consulta Errore di valore non valido durante il deployment in una configurazione VPC condiviso per risolvere il problema.

Errore durante il riavvio delle istanze nelle versioni in esecuzione

Quando esegui il deployment dell'app, si verifica il seguente errore:

error when restarting the instance under the running versions

A partire da maggio 2024, Google Cloud applica le policy dell'organizzazione sicure per impostazione predefinita per tutte le nuove organizzazioni. Questa policy richiede che tutte le istanze VM create nei nuovi progetti abilitino VM Manager. Per i progetti nuovi ed esistenti, questo vincolo impedisce gli aggiornamenti dei metadati che disabilitano VM Manager a livello di progetto o di istanza.

Per risolvere il problema, devi disattivare il vincolo della policy dell'organizzazione Richiedi OS Config (constraints/compute.requireOsConfig).

Se il problema persiste, devi disabilitare anche i seguenti criteri dell'organizzazione che potrebbero essere stati abilitati a livello di progetto o di organizzazione:

Autorizzazione compute.firewalls.list obbligatoria

Quando esegui il deployment dell'app su una VPC condiviso condivisa, si verifica il seguente errore:

Request to https://compute.googleapis.com/compute/v1/projects/projects/PROJECT_ID/global/firewalls?key failed, details: Required 'compute.firewalls.list' permission for 'projects/PROJECT_ID'

Questo errore si verifica se i seguenti service account per il progetto host non hanno il ruolo Utente di rete Compute (roles/compute.networkUser):

Per risolvere il problema, concedi il ruolo Utente di rete Compute ai service account dell'agente di servizio delle API di Google e dell'agente di servizio dell'ambiente flessibile di App Engine per il progetto host.

Il deployment non riesce a causa di un vincolo delle policy dell'organizzazione

Quando esegui il deployment di un'app, si verifica il seguente errore:

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred while processing task /app-engine-flex/....: Request to https://compute.googleapis.com/compute/VERSION/projects/PROJECT_ID/... failed, details: Constraint constraints/compute.disableGuestAttributesAccess violated for project PROJECT_ID.

Ciò potrebbe essere dovuto all'applicazione del vincolo constraints/compute.disableGuestAttributesAccess durante il deployment dell'app. Tutte le app nell'ambiente flessibile di App Engine applicano questa policy dell'organizzazione per impostazione predefinita.

Per risolvere il problema, devi disattivare il vincolo constraints/compute.disableGuestAttributesAccess.

Errori di deployment comuni

Questa sezione descrive le strategie di risoluzione dei problemi relativi agli errori di configurazione nell'app o nel progetto.

Errore di valore non valido durante il deployment in una configurazione VPC condiviso

Quando esegui il deployment dell'app, in Cloud Logging viene visualizzato il seguente errore per le istanze VM flessibili:

Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert

Si tratta di un problema noto in cui l'impostazione di instance_tag nel file app.yaml genera errori durante la creazione delle istanze.

Per risolvere il problema, rimuovi il campo instance_tag dal file app.yaml ed esegui di nuovo il deployment.

Errori durante il deployment di app con un massimo di tre istanze

Le app di cui è stato eseguito il deployment con max_instances impostato su tre o meno potrebbero riscontrare errori o tempi di inattività imprevisti. Per risolvere il problema, specifica almeno quattro istanze massime nel file app.yaml ed esegui nuovamente il deployment.

Superare il limite massimo di istanze

Quando esegui il deployment dell'app, si verifica il seguente errore:

You may not have more than 'xx' total max instances in your project.

Esiste un limite al numero massimo di istanze che puoi creare per progetto. Le richieste di creazione di istanze aggiuntive non vanno a buon fine se superi questo limite.

Per risolvere il problema, imposta il valore di max_instances nel file app.yaml su un valore inferiore a questo limite o elimina alcuni servizi o versioni per portare la somma di max_instances entro il limite.

La build durante il deployment non riesce senza errori nei log

Quando esegui il deployment dell'app, si verifica il seguente errore:

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

Se fai clic sul link nel messaggio di errore e noti che tutti i passaggi di build sono andati a buon fine, ma la build dell'app non è comunque riuscita, la causa potrebbe essere una delle seguenti:

Per risolvere il problema, modifica le seguenti impostazioni per il bucket:

Errori durante il deployment in una versione di App Engine esistente

Quando esegui il deployment in una versione esistente nell'ambiente flessibile di App Engine, potrebbe verificarsi il seguente errore:

ERROR: (gcloud.app.deploy) Error Response: [9] An internal error occurred while
processing task /app-engine-flex/flex_await_healthy/flex_await_healthy

Questo errore indica che l'aggiornamento di un deployment non integro con un'immagine Docker funzionante non sempre comporta un deployment integro. Il risultato dipende dallo stato delle istanze del deployment non integro. Nonostante l'errore, se fornisci un'immagine Docker valida, il deployment potrebbe alla fine diventare integro. L'aggiornamento di una versione esistente con una nuova immagine Docker, sebbene consentito, non è una buona pratica. Non è previsto il rollback in caso di errore della versione.

Errore IP interno durante il deployment in una configurazione VPC condiviso

Il seguente errore potrebbe verificarsi durante il deployment in una rete VPC condiviso configurata in un progetto di servizio in cui viene utilizzata l'impostazione predefinita dell'indirizzo IP privato (private-ranges-only).

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred.

Questo errore potrebbe indicare che il service agent dell'ambiente flessibile di App Engine nel progetto host del VPC condiviso non è disponibile. L'agente di servizio dell'ambiente flessibile di App Engine è stato rimosso o l'API App Engine non è abilitata nel progetto host.

Per risolvere il problema:

  1. Abilitare l'API App Engine nel progetto host della rete VPC condiviso.
  2. Se l'API App Engine è abilitata, l'agente di servizio dell'ambiente flessibile App Engine non esiste nel progetto. Fai riferimento a Ripristina il ruolo richiesto per l'agente di servizio.

Deployment non riuscito a causa della mancanza di connettività alle API di Google

Quando esegui il deployment dell'app, si verifica il seguente errore:

Your deployment has failed to become healthy in the allotted time and therefore was rolled back. If you believe this was an error, try adjusting the app_start_timeout_sec setting in the readiness_check section.

Per risolvere il problema, assicurati che il VPC associato alla tua applicazione abbia una route statica locale con la destinazione 0.0.0.0/0 e un hop successivo del gateway internet predefinito. Se utilizzi servizi privati solo interni, abilita l'accesso privato Google nella subnet selezionata.