Il runtime di Python

Il runtime Python è lo stack software responsabile dell'installazione del codice e delle dipendenze dell'applicazione e della sua esecuzione nell'ambiente flessibile.

Versioni di Python

Python 3.14 uses buildpacks. Per l'elenco completo delle versioni di Python supportate e della versione di Ubuntu corrispondente, consulta la pianificazione del supporto del runtime.

Per utilizzare una versione di Python supportata, devi:

  • Includere le impostazioni runtime_config e operating_system nel file app.yaml per specificare un sistema operativo.

  • Installare la versione 420.0.0 o successive di gcloud CLI. Puoi aggiornare gli strumenti CLI eseguendo il gcloud components update comando. Per visualizzare la versione installata, esegui il gcloud version comando.

  • Facoltativamente, puoi specificare una versione del runtime includendo l'impostazione runtime_version nel file app.yaml. Per impostazione predefinita, se l'impostazione runtime_version non è specificata, viene utilizzata l'ultima versione di Python.

Esempi

  • Per specificare Python 3.14 su Ubuntu 24:

    runtime: python
env: flex
entrypoint: gunicorn -b :$PORT main:app

runtime_config:
    operating_system: "ubuntu24"
    runtime_version: "3.14"

  • Per specificare l'ultima versione di Python supportata su Ubuntu 24:

      runtime: python
  env: flex
  entrypoint: gunicorn -b :$PORT main:app

  runtime_config:
      operating_system: "ubuntu24"

Per ulteriori informazioni, consulta la pagina di app.yaml riferimento.

Supporto di altri runtime Python

Se devi utilizzare una versione di Python non supportata, puoi creare un runtime personalizzato e selezionare un'immagine di base valida con la versione di Python di cui hai bisogno.

Per le immagini di base fornite da Google o immagini di base Python di Docker, consulta Creazione di runtime personalizzati.

Per ulteriori informazioni sulla containerizzazione delle app App Engine per Cloud Run, consulta la guida alla migrazione.

Dipendenze

Il runtime cerca un requirements.txt file nella directory di origine dell'applicazione e utilizza pip per installare le dipendenze prima di avviare l'applicazione. Per ulteriori informazioni sulla dichiarazione e sulla gestione dei pacchetti, consulta Utilizzo delle librerie Python.

Se la tua app richiede dipendenze private, devi utilizzare un runtime personalizzato basato sul runtime Python per installare i pacchetti appropriati.

Avvio dell'applicazione

Il runtime avvia l'applicazione utilizzando il entrypoint definito nel tuo app.yaml file. L'entrypoint deve avviare un processo che risponde alle richieste HTTP sulla porta definita dalla variabile di ambiente PORT.

La maggior parte delle applicazioni web utilizza un server WSGI come Gunicorn, uWSGI o Waitress.

Prima di poter utilizzare uno di questi server, devi aggiungerli come dipendenza in requirements.txt dell'applicazione. Se utilizzi gunicorn per l'applicazione Flask, assicurati che la versione Python dell'applicazione sia compatibile con gunicorn.

Il runtime garantisce che tutte le dipendenze siano installate prima della chiamata dell'entrypoint.

Flask==2.0.2
gunicorn==20.1.0

Un esempio di entrypoint che utilizza gunicorn per un'applicazione Flask:

entrypoint: gunicorn -b :$PORT main:app

Un esempio di entrypoint che utilizza gunicorn per un'applicazione Django:

entrypoint: gunicorn -b :$PORT mydjangoapp:wsgi

Gunicorn è il server WSGI consigliato, ma è possibile utilizzare qualsiasi altro server WSGI. Ad esempio, ecco un entrypoint che utilizza uWSGI con Flask:

entrypoint: uwsgi --http :$PORT --wsgi-file main.py --callable app

Per le applicazioni in grado di gestire le richieste senza un server WSGI, puoi semplicemente eseguire uno script Python:

entrypoint: python main.py

Gli esempi di entrypoint di base mostrati sopra sono pensati per essere punti di partenza e potrebbero funzionare per le tue applicazioni web. La maggior parte delle applicazioni, tuttavia, dovrà configurare ulteriormente il server WSGI. Anziché specificare tutte le impostazioni nell'entrypoint, crea un file gunicorn.conf.py nella directory principale del progetto, in cui si trova il file app.yaml, e specificalo nell'entrypoint:

entrypoint: gunicorn -c gunicorn.conf.py -b :$PORT main:app

Puoi leggere tutti i valori di configurazione di Gunicorn nella relativa documentazione.

Worker

Gunicorn utilizza i worker per gestire le richieste. Per impostazione predefinita, Gunicorn utilizza i worker di sincronizzazione. Questa classe di worker è compatibile con tutte le applicazioni web, ma ogni worker può gestire una sola richiesta alla volta. Per impostazione predefinita, gunicorn utilizza solo uno di questi worker. Spesso, questo può causare una sottoutilizzazione delle istanze e aumentare la latenza nelle applicazioni con un carico elevato.

Ti consigliamo di impostare il numero di worker su 2-4 volte il numero di core CPU per l'istanza più uno. Puoi specificarlo in gunicorn.conf.py come:

import multiprocessing

workers = multiprocessing.cpu_count() * 2 + 1

Inoltre, alcune applicazioni web che sono principalmente vincolate all'I/O possono vedere un miglioramento delle prestazioni utilizzando una classe di worker diversa. Se la classe di worker richiede dipendenze aggiuntive come gevent o tornado, queste dipendenze devono essere dichiarate in requirements.txt dell'applicazione.

Proxy HTTPS e di forwarding

App Engine termina la connessione HTTPS nel bilanciatore del carico e inoltra la richiesta all'applicazione. La maggior parte delle applicazioni non ha bisogno di sapere se la richiesta è stata inviata tramite HTTPS o meno, ma le applicazioni che richiedono queste informazioni devono configurare Gunicorn in modo che consideri attendibile il proxy App Engine in gunicorn.conf.py:

forwarded_allow_ips = '*'
secure_scheme_headers = {'X-FORWARDED-PROTO': 'https'}

Gunicorn ora garantirà che wsgi.url_scheme sia impostato su 'https', che la maggior parte dei web framework utilizzerà come indicazione che la richiesta è sicura. Se il server o il framework WSGI non supporta questa funzionalità, controlla manualmente il valore dell'intestazione X-Forwarded-Proto.

Alcune applicazioni devono anche accertare l'indirizzo IP dell'utente. Questo è disponibile nell'intestazione X-Forwarded-For.

Tieni presente che l'impostazione secure_scheme_headers in gunicorn.conf.py deve essere in maiuscolo, ad esempio X-FORWARDED-PROTO, ma le intestazioni che il codice può leggere saranno in maiuscolo e minuscolo, ad esempio X-Forwarded-Proto.

Estensione del runtime

Il runtime Python dell'ambiente flessibile può essere utilizzato per creare un runtime personalizzato. Per ulteriori informazioni, consulta Personalizzazione di Python.

Variabili di ambiente

Le seguenti variabili di ambiente sono impostate dall'ambiente di runtime:

Variabile di ambiente Descrizione
GAE_INSTANCE Il nome dell'istanza corrente.
GAE_MEMORY_MB La quantità di memoria disponibile per il processo dell'applicazione.
GAE_SERVICE Il nome del servizio specificato nel file app.yaml dell'applicazione o, se non è specificato alcun nome del servizio, viene impostato su default.
GAE_VERSION L'etichetta della versione dell'applicazione corrente.
GOOGLE_CLOUD_PROJECT L'ID progetto associato all'applicazione, visibile in the Google Cloud console
PORT La porta che riceverà le richieste HTTP.

Puoi impostare variabili di ambiente aggiuntive nel app.yaml file.

Server di metadati

Ogni istanza dell'applicazione può utilizzare il server di metadati di Compute Engine per eseguire query sulle informazioni sull' istanza, inclusi il nome host, l'indirizzo IP esterno, l'ID istanza, i metadati personalizzati e le informazioni sull'account di servizio. App Engine non consente di impostare metadati personalizzati per ogni istanza, ma puoi impostare metadati personalizzati a livello di progetto e leggerli dalle istanze App Engine e Compute Engine.

Questa funzione di esempio utilizza il server di metadati per ottenere l'indirizzo IP esterno dell'istanza:

METADATA_NETWORK_INTERFACE_URL = (
    "http://metadata/computeMetadata/v1/instance/network-interfaces/0/"
    "access-configs/0/external-ip"
)


def get_external_ip():
    """Gets the instance's external IP address from the Compute Engine metadata
    server.

    If the metadata server is unavailable, it assumes that the application is running locally.

    Returns:
        The instance's external IP address, or the string 'localhost' if the IP address
        is not available.
    """
    try:
        r = requests.get(
            METADATA_NETWORK_INTERFACE_URL,
            headers={"Metadata-Flavor": "Google"},
            timeout=2,
        )
        return r.text
    except requests.RequestException:
        logging.info("Metadata server could not be reached, assuming local.")
        return "localhost"