Testa ed esegui il deployment dell'applicazione

ID regione

Il REGION_ID è un codice abbreviato che Google assegna in base alla regione selezionata quando crei l'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono sembrare simili ai codici di paesi e province di uso comune. Per le app create dopo febbraio 2020, REGION_ID.r è incluso negli URL App Engine. Per le app esistenti create prima di questa data, l'ID regione è facoltativo nell'URL.

Scopri di più sugli ID regione.

Ok

Go Java Node.js PHP Python Ruby .NET Personalizzato

Scopri come eseguire la tua applicazione localmente, come eseguirne il deployment e come testarla in App Engine.

Esegui in locale

Per testare l'applicazione prima del deployment, esegui l'applicazione nel tuo ambiente locale con gli strumenti di sviluppo che utilizzi di solito. Ad esempio, in genere puoi eseguire un'applicazione Flask con il server di sviluppo Flask utilizzando:

python main.py

Avvia le applicazioni Django utilizzando:

python manage.py runserver

Per simulare un ambiente di produzione App Engine, puoi eseguire il server Web Server Gateway Interface (WSGI) completo in locale. Utilizza lo stesso comando specificato come entrypoint nel file app.yaml, ad esempio:

gunicorn -b :$PORT main:app

Esegui il deployment dell'applicazione

Esegui il deployment dell'applicazione in App Engine utilizzando il comando gcloud app deploy.

Il servizio Cloud Build crea automaticamente il deployment in un'immagine container ed esegue il deployment dell'immagine nell'ambiente flessibile di App Engine. Il container include eventuali modifiche locali apportate all'immagine runtime.

Per eseguire il deployment delle tue app in modo programmatico, utilizza l'API Admin.

Prima di iniziare

Prima di poter eseguire il deployment dell'applicazione:

• Il proprietario del progetto Google Cloud deve configurare il tuo progetto Google Cloud per App Engine.

• Assicurati che il tuo account utente includa i privilegi richiesti.

Garantire il successo del deployment

Se attivi i controlli di integrità aggiornati, i deployment vengono ritirati se l'applicazione non raggiunge lo stato integro. Quando esegui il deployment della tua prima applicazione nell'ambiente flessibile, potrebbe verificarsi un ritardo durante la configurazione della macchina virtuale (VM) e di altre infrastrutture. Dopo la configurazione iniziale, i controlli di integrità assicurano che l'istanza sia integra e pronta a ricevere il traffico. Se la tua applicazione non raggiunge lo stato pronto in un periodo di tempo specificato, indicato dal campo initial_delay_sec nella sezione liveness_check del file app.yaml, il deployment non va a buon fine e viene eseguito il rollback.

Potrebbe essere necessario più tempo per preparare la tua applicazione. Ad esempio, potresti inizializzare l'applicazione scaricando file di grandi dimensioni o precaricando le cache. Se utilizzi i controlli di integrità aggiornati, puoi aumentare il periodo di tempo modificando l'impostazione di configurazione app_start_timeout_sec nella sezione readiness_check del file app.yaml.

Se il deployment non va a buon fine, assicurati che l'API Cloud Build sia abilitata nel tuo progetto. App Engine abilita questa API automaticamente la prima volta che esegui il deployment di un'app, ma se qualcuno ha disattivato l'API, i deployment non vanno a buon fine.

Esegui il deployment di un servizio

Esegui il deployment dell'applicazione su App Engine eseguendo il deployment delle versioni dei servizi dell'applicazione e di ciascuno dei relativi file di configurazione.

Per eseguire il deployment del servizio dell'applicazione, esegui questo comando dalla directory in cui si trova il file app.yaml del servizio:

gcloud app deploy

Per impostazione predefinita, il comando gcloud app deploy esegue il deployment solo del file app.yaml nella directory corrente. Ogni volta che esegui questo comando, App Engine genera un ID univoco per la versione che distribuisci, la distribuisce al progettoGoogle Cloud per cui hai configurato gcloud CLI e instrada tutto il traffico verso la nuova versione. La nuova versione diventa la versione predefinita.

Nota :è consigliabile controllare la pagina Versioni di App Engine nella consoleGoogle Cloud o eseguire gcloud app versions list dopo aver eseguito il comando gcloud app deploy per verificare la versione che riceve traffico.

Puoi modificare il comportamento predefinito del comando di deployment scegliendo come target file specifici, specificando versioni o includendo parametri aggiuntivi:

• Puoi eseguire il deployment degli altri file di configurazione del tuo servizio scegliendo come target e eseguendo il deployment di ogni file separatamente, ad esempio:

  gcloud app deploy cron.yaml
  gcloud app deploy dispatch.yaml
  gcloud app deploy index.yaml
  

• Per specificare un ID versione personalizzato, utilizza il flag --version.

• Per impedire che il traffico venga indirizzato automaticamente alla nuova versione, utilizza il flag --no-promote.

• Per eseguire il deployment in un progetto Google Cloud specifico, utilizza il flag --project.

Ad esempio, per eseguire il deployment del servizio definito dal file app.yaml in un progettoGoogle Cloud specifico, assegna al servizio un ID versione personalizzato e impedisci il routing del traffico alla nuova versione:

gcloud app deploy --project PROJECT_ID --version VERSION_ID --no-promote

Per ulteriori informazioni, consulta il riferimento gcloud app deploy.

Puoi impostare le proprietà per gcloud CLI e creare e gestire configurazioni SDK in modo da non dover specificare flag come --project ogni volta che esegui il deployment.

Quando esegui il deployment di una nuova versione con lo stesso nome di una versione esistente, App Engine esegue immediatamente la migrazione del traffico alla nuova versione. Si verifica un picco di latenza quando App Engine carica le richieste nella nuova versione. La nuova versione sovrascrive quella precedente e non potrai eseguire la migrazione del traffico alla versione precedente. Quando esegui il deployment di una nuova versione con lo stesso nome della versione precedente, App Engine esegue il deployment della nuova immagine container nelle macchine virtuali esistenti per un deployment più rapido e aggiorna il container dell'applicazione nelle macchine virtuali esistenti.

Esegui il deployment di più servizi

Utilizzi lo stesso comando di deployment per eseguire il deployment o l'aggiornamento dei più servizi che compongono la tua applicazione.

Prima di iniziare:

• Devi inizialmente eseguire il deployment di una versione dell'applicazione nel servizio default prima di poter creare ed eseguire il deployment dei servizi successivi.

• L'ID di ciascun servizio deve essere specificato nei file di configurazione app.yaml corrispondenti. Per specificare l'ID servizio, includi la definizione dell'elemento service in ogni file di configurazione. Per impostazione predefinita, l'esclusione di questa definizione dell'elemento dal file di configurazione esegue il deployment della versione nel servizio default.

Per eseguire il deployment di più servizi, devi eseguire il deployment separato del file app.yaml di ogni servizio, ad esempio:

gcloud app deploy service1/app.yaml
gcloud app deploy service2/app.yaml

Puoi specificare più file con un unico comando di deployment:

gcloud app deploy service1/app.yaml service2/app.yaml

Ignorare i file

Puoi utilizzare un file .gcloudignore per specificare i file e le directory da non caricare su Google Cloud quando esegui il deployment dei servizi. Questa opzione è utile per ignorare gli artefatti di build e altri file che non devono essere caricati con il deployment.

Nota: non puoi specificare il campo skip_files nel file app.yaml se hai un file .gcloudignore.

Scopri di più sulla sintassi del file .gcloudignore nel riferimento gcloud.

Creare manualmente un container per il deployment

Attenzione: Container Registry è stato ritirato. A partire dal 18 marzo 2025, Container Registry è stato chiuso e la scrittura di immagini in Container Registry non è disponibile. Per dettagli sul ritiro e su come eseguire la migrazione ad Artifact Registry, consulta Ritiro di Container Registry.

Per creare le immagini container al di fuori di Google Cloud:

1. Carica le immagini in un repository Artifact Registry. Per saperne di più, vedi Push e pull delle immagini.
2. Esegui il deployment in App Engine con il comando gcloud app deploy.

Ad esempio, se crei le immagini container localmente con Docker, puoi eseguire il push di queste immagini in Artifact Registry e specificare l'URL dell'immagine nel flag --image-url del comando:

gcloud app deploy --image-url LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

Sostituisci:

• LOCATION con la posizione del repository in cui è archiviata l'immagine.

• PROJECT-ID con il tuo Google Cloud ID progetto.

• REPOSITORY con il nome del repository in cui è archiviata l'immagine.

• IMAGE con il nome dell'immagine container.

Utilizzare pipeline di deployment continuo automatizzate

Puoi utilizzare Cloud Build per automatizzare i deployment nelle pipeline di deployment continuo. Per saperne di più, consulta Deployment in App Engine e Creare e gestire trigger di build nella documentazione di Cloud Build.

Immagini di base Docker

Se vuoi creare un'applicazione runtime personalizzata, vedi Crea un file Docker.

visualizza l'applicazione

Dopo aver eseguito il deployment dell'applicazione in App Engine, puoi eseguire il comando seguente per avviare il browser e visualizzarla all'indirizzo https://PROJECT_ID.REGION_ID.r.appspot.com:

gcloud app browse

Test su App Engine

Prima di configurare una nuova versione per ricevere traffico, puoi testarla su App Engine. Ad esempio, per testare una nuova versione del tuo servizio default:

1. Esegui il deployment della nuova versione e includi il flag --no-promote:

   gcloud app deploy --no-promote

2. Accedi alla nuova versione andando al seguente URL:

   https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

   Nota: puoi trovare l'ID versione nella consoleGoogle Cloud oppure specificarne uno quando esegui il deployment con il parametro version.

   Ora puoi testare la nuova versione nell'ambiente di runtime di App Engine. Puoi eseguire il debug della tua applicazione visualizzando i relativi log in Google Cloud Esplora log della console . Per ulteriori informazioni, consulta Scrittura dei log delle applicazioni.

   Le richieste inviate a https://PROJECT_ID.REGION_ID.r.appspot.com verranno comunque indirizzate alla versione precedentemente configurata per ricevere traffico.

3. Quando vuoi inviare traffico alla nuova versione, utilizza la consoleGoogle Cloud per eseguire la migrazione del traffico:

   Gestisci le versioni

   Seleziona la versione appena implementata e fai clic su Esegui la migrazione del traffico.

Puoi utilizzare la stessa procedura per testare le nuove versioni di altri servizi sostituendo default nell'URL con il nome del servizio:

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

Per saperne di più sul targeting di servizi e versioni specifici, consulta la sezione Come vengono instradate le richieste.

Utilizzare le variabili di ambiente di build

Puoi impostare le variabili di ambiente di build per i runtime che supportano i buildpack.

Le variabili di ambiente di build sono coppie chiave-valore che puoi specificare per configurare il buildpack che utilizzi per il deployment dell'app. Ad esempio, potresti voler specificare le opzioni del compilatore.

Prima di iniziare:

• Le chiavi devono iniziare con una lettera ASCII maiuscola e possono includere lettere ASCII maiuscole, cifre e trattini bassi.
• Evita di creare variabili con un prefisso della chiave GOOGLE_*.
• Le seguenti chiavi sono riservate all'utilizzo da parte di Google:
  • GOOGLE_RUNTIME
  • GOOGLE_RUNTIME_VERSION
  • GOOGLE_ENTRYPOINT
  • GOOGLE_DEVMODE
• Puoi utilizzare qualsiasi chiave supportata dai buildpack.

Per utilizzare le variabili di ambiente con i buildpack, specifica il campo build_env_variables nel file app.yaml.

Scopri di più sui buildpack.

Utilizzare Cloud Trace

Cloud Trace è utile per capire come si propagano le richieste nella tua applicazione. Puoi analizzare informazioni dettagliate sulla latenza per una singola richiesta o visualizzare la latenza aggregata per l'intera applicazione.

Puoi visualizzare i dettagli della traccia. In Explorer tracce, puoi filtrare in base al servizio e alla versione specifici di App Engine.

Risoluzione dei problemi

Di seguito sono riportati i messaggi di errore comuni che potresti riscontrare durante il deployment delle app:

PERMISSION_DENIED: Operation not allowed

The "appengine.applications.create" permission is required.

Se il Google Cloud progetto non include l'applicazione App Engine richiesta, il comando gcloud app deploy può non riuscire quando tenta di eseguire il comando gcloud app create. Solo gli account con il ruolo Proprietario dispongono delle autorizzazioni necessarie per creare applicazioni App Engine.

502 Bad Gateway

L'avvio del Google Cloud progetto potrebbe non riuscire se app.yaml non è configurato correttamente. Controlla i log dell'app per messaggi di errore più dettagliati.

[13] An internal error occurred while creating a Cloud Storage bucket.

App Engine crea un bucket Cloud Storage multiregionale predefinito per tuo conto nella stessa regione in cui crea l'applicazione. Richiede questo bucket per archiviare i contenuti della tua applicazione. L'errore viene restituito quando non è possibile creare questo bucket, ad esempio nei seguenti scenari:

• L'agente di servizio dell'ambiente flessibile App Engine non è presente nel tuo progetto o non dispone del ruolo App Engine flexible environment Service Agent. Puoi aggiungere di nuovo il account di servizio dell'agente al tuo progetto concedendogli le autorizzazioni IAM corrette. Vedi Ripristinare un agente di servizio eliminato.

• Il service account predefinito di App Engine non è presente nel tuo progetto. Se il account di servizio App Engine è stato rimosso prima che siano trascorsi 30 giorni dalla sua eliminazione, puoi ripristinarlo.

• Il tuo progetto si trova in un'organizzazione che applica i criteri constraints/gcp.resourceLocations e l'organizzazione non consente la creazione di risorse nella stessa regione in cui è stato creato App Engine. Devi ignorare il criterio constraints/gcp.resourceLocations applicato per il tuo progetto e consentire le località multiregionali nella stessa regione in cui viene creata l'app App Engine.

Ad esempio, se la tua app App Engine viene creata nella regione europe-west, anche se la regione è mappata alle località europe-west1, devi modificare il vincolo per consentire le risorse in in:eu-locations, che include tutte le regioni EU. Questo è necessario perché i bucket creati da App Engine sono multiregionali. Se la tua app App Engine è creata nella regione US, devi consentire in:us-locations. Se la tua app è creata nelle regioni ASIA, devi consentire in:asia-locations.

[13] An internal error occurred.

Questo errore può verificarsi se esegui il deployment del servizio con una configurazione di rete che utilizza una configurazione VPC condiviso. Prova a procedere come segue:

1. Assicurati che la configurazione di app.yaml sia valida.
2. Assicurati che l'ambiente flessibile di App Engine soddisfi tutti i requisiti per una configurazione VPC condiviso. Consulta Utilizzo dell'ambiente flessibile di App Engine su una VPC condiviso condivisa.
3. Assicurati di aver configurato i service account nel tuo progetto. In caso contrario, devi ripristinare gli account. La regione della subnet nel progetto host VPC condiviso deve corrispondere alla posizione in cui è stato creato l'ambiente App Engine.

Se il problema persiste, esegui nuovamente il deployment del servizio utilizzando Google Cloud SDK. Assicurati di aggiungere il flag --verbosity=debug. Contatta l'Google Cloud assistenza e fornisci l'output del comando.

IP space of {USER_SUBNETWORK_NAME} is exhausted and needs to be expanded.

Se il deployment non va a buon fine con questo messaggio di errore, la rete configurata per il servizio App Engine non dispone di indirizzi da allocare per le nuove istanze del servizio. Per risolvere il problema, espandi gli intervalli VPC nella subnet configurata per il servizio dell'ambiente flessibile di App Engine.