Ambiente di runtime Python 3

Il runtime Python è lo stack software responsabile dell'installazione del codice del tuo servizio web e delle relative dipendenze, nonché dell'esecuzione del tuo servizio App Engine.

Il runtime Python per App Engine nell'ambiente standard è dichiarato nel file app.yaml:

runtime: pythonVERSION

Dove VERSION sono i numeri di versione di Python MAJOR e MINOR. Ad esempio, per utilizzare l'ultima versione di Python, Python 3.15 (anteprima), specifica 315.

Per altre versioni di Python supportate e la versione di Ubuntu corrispondente alla tua versione di Python, consulta la Pianificazione del supporto di runtime.

Versioni di Python 3

L'ultima versione di Python supportata è la 3.15 (anteprima). Il runtime Python utilizza l'ultima release stabile della versione specificata nel file app.yaml. App Engine esegue automaticamente l'aggiornamento alle nuove versioni delle patch, ma non aggiorna automaticamente la versione secondaria.

Ad esempio, il deployment della tua applicazione potrebbe essere eseguito in Python 3.7.0 e successivamente aggiornato automaticamente a Python 3.7.1, ma non verrà aggiornato automaticamente alla versione secondaria successiva Python 3.8.0.

App Engine esegue le app Python in un container protetto da gVisor su una distribuzione Ubuntu Linux aggiornata.

Dipendenze

Durante il deployment, App Engine utilizza il gestore di pacchetti Python pip per installare le dipendenze definite nel file di metadati requirements.txt che si trova nella directory root del progetto. Non è necessario caricare le dipendenze, poiché App Engine esegue una nuova installazione.

La specifica delle dipendenze mediante lo standard Pipfile/Pipfile.lock non è attualmente supportata e il tuo progetto non deve contenere questi file.

Avvio dell'applicazione

Il runtime avvia l'app eseguendo il comando specificato nel campo entrypoint nel file app.yaml. Se hai configurato un entry point del server web Gunicorn nel file app.yaml, devi anche aggiungere gunicorn al file requirements.txt.

L'entrypoint deve avviare un server web in ascolto sulla porta specificata dalla variabile di ambiente PORT. Ad esempio:

entrypoint: gunicorn -b :$PORT main:app

Il framework web utilizzato dalla tua app è responsabile del routing delle richieste ai gestori appropriati nell'app.

Se la tua app soddisfa i seguenti requisiti, App Engine la avvierà con il server web gunicorn se non specifichi il campo entrypoint:

  • La directory principale dell'app contiene un file main.py con un oggetto compatibile con WSGI chiamato app.

  • La tua app non contiene file Pipfile o Pipfile.lock.

Se non specifichi un entrypoint per il runtime Python 3, App Engine configura e avvia il server web Gunicorn predefinito utilizzando la classe worker gthread con 4 thread per worker. Per le istanze F1 e B1, la classe worker gthread utilizza worker 4, mentre per le istanze F2, B2 e più grandi utilizza worker 8. Se specifichi un entrypoint personalizzato senza impostare --workers (-w), Gunicorn utilizza per impostazione predefinita un worker sync.

Best practice per i punti di accesso

  • Assicurati che il modulo Python richiesto per eseguire l'entrypoint specificato in app.yaml sia presente nel file requirements.txt. Aggiungi gunicorn al file requirements.txt solo se un endpoint gunicorn è specificato esplicitamente nel file app.yaml.

  • Per prestazioni ottimali, l'entry point deve essere leggero perché viene eseguito ogni volta che viene creata una nuova istanza della tua applicazione.

  • Puoi utilizzare il campo entrypoint per ottimizzare le prestazioni della tua app. Ad esempio, se utilizzi gunicorn come server web, puoi utilizzare il flag --workers nel campo entrypoint per configurare il numero di worker che gestiscono la tua app.

    Il numero di worker specificato deve corrispondere alla classe di istanza della tua app App Engine:

    Classe di istanza Worker
    F1 4
    F2 8
    F4 8
    F4_1G 8
    B1 4
    B2 8
    B4 8
    B4_1G 8
    B8 8

    Queste indicazioni servono come punto di partenza per la selezione del numero di worker. Potresti dover utilizzare un numero diverso di worker a seconda delle caratteristiche di prestazioni della tua app. L'esempio seguente mostra un deployment di App Engine che utilizza due worker gunicorn per la gestione delle app:

    entrypoint: gunicorn -b :$PORT -w 2 main:app

  • Ti consigliamo di configurare il server web in modo che ascolti e risponda alle richieste HTTP sulla porta specificata dalla variabile di ambiente $PORT. L'utilizzo della porta predefinita 8080 impedisce ad App Engine di utilizzare il livello NGINX per comprimere le risposte HTTP. Tieni presente che se utilizzi la porta 8080, nei file di log della tua app verranno visualizzati avvisi relativi alla porta 8080 e a NGINX.

Altri framework web

Oltre a Django e Flask, puoi utilizzare altri framework web con App Engine, come uwsgi e Tornado. L'esempio seguente mostra come utilizzare uwsgi con App Engine:

runtime: python313
entrypoint: uwsgi --http-socket :$PORT --wsgi-file main.py --callable app --master --processes 1 --threads 2
 
uwsgi==2.0.22
Flask==3.1.3; python_version >= '3.9'

Variabili di ambiente

Le seguenti variabili di ambiente vengono impostate dal runtime:

Variabile di ambiente Descrizione
GAE_APPLICATION L'ID della tua applicazione App Engine. Questo ID ha il prefisso "region code~", ad esempio "e~" per le applicazioni di cui è stato eseguito il deployment in Europa.
GAE_DEPLOYMENT_ID L'ID del deployment corrente.
GAE_ENV L'ambiente App Engine. Da impostare su standard.
GAE_INSTANCE L'ID dell'istanza su cui è attualmente in esecuzione il servizio.
GAE_MEMORY_MB La quantità di memoria disponibile per il processo dell'applicazione, in MB.
GAE_RUNTIME Il runtime specificato nel file app.yaml.
GAE_SERVICE Il nome del servizio specificato nel file app.yaml. Se non viene specificato alcun nome del servizio, viene impostato su default.
GAE_VERSION L'etichetta della versione attuale del servizio.
GOOGLE_CLOUD_PROJECT L'ID progetto Google Cloud associato alla tua applicazione.
PORT La porta che riceve le richieste HTTP.
NODE_ENV (disponibile solo nel runtime Node.js) Impostato su production quando viene eseguito il deployment del servizio.

Puoi definire variabili di ambiente aggiuntive nel file app.yaml, ma i valori precedenti non possono essere sostituiti, ad eccezione di NODE_ENV.

Proxy HTTPS e di forwarding

App Engine termina le connessioni HTTPS sul bilanciatore del carico e inoltra le richieste alla tua applicazione. Alcune applicazioni devono determinare l'IP e il protocollo della richiesta originale. L'indirizzo IP dell'utente è disponibile nell'intestazione X-Forwarded-For standard. Le applicazioni che richiedono queste informazioni devono configurare il proprio framework web in modo che consideri attendibile il proxy.

Filesystem

Il runtime include un file system completo. Il file system è di sola lettura, ad eccezione della posizione /tmp, che è un disco virtuale che archivia i dati nella RAM dell'istanza App Engine.

Server di metadati

Ogni istanza della tua applicazione può utilizzare il server dei metadati di App Engine per eseguire query sulle informazioni relative all'istanza e al progetto.

Puoi accedere al server di metadati tramite i seguenti endpoint:

  • http://metadata
  • http://metadata.google.internal

Le richieste inviate al server dei metadati devono includere l'intestazione della richiesta Metadata-Flavor: Google. Questa intestazione indica che la richiesta è stata inviata con l'intenzione di recuperare i valori dei metadati.

La tabella seguente elenca gli endpoint in cui puoi effettuare richieste HTTP per metadati specifici:

Endpoint dei metadati Descrizione
/computeMetadata/v1/project/numeric-project-id Il numero di progetto assegnato al tuo progetto.
/computeMetadata/v1/project/project-id L'ID progetto assegnato al tuo progetto.
/computeMetadata/v1/instance/region La regione in cui è in esecuzione l'istanza.
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email L'indirizzo email del account di servizio predefinito assegnato al tuo progetto.
/computeMetadata/v1/instance/service-accounts/default/ Elenca tutti i service account predefiniti per il tuo progetto.
/computeMetadata/v1/instance/service-accounts/default/scopes Elenca tutti gli ambiti supportati per i service account predefiniti.
/computeMetadata/v1/instance/service-accounts/default/token Restituisce il token di autenticazione che può essere utilizzato per autenticare la tua applicazione in altre API Google Cloud.

Ad esempio, per recuperare l'ID progetto, invia una richiesta a http://metadata.google.internal/computeMetadata/v1/project/project-id.