Crea un'applicazione Python

I buildpack supportano la configurazione idiomatica della lingua tramite le variabili di ambiente.

Specificare la versione Python

Per impostazione predefinita, il buildpack Python Runtime utilizza la versione stabile più recente dell'interprete Python. Se la tua applicazione richiede una versione specifica, puoi specificarne una includendo un file .python-version nella directory principale dell'applicazione.

3.13

Utilizza GOOGLE_PYTHON_VERSION

È anche possibile specificare la versione di Python tramite la variabile di ambiente GOOGLE_PYTHON_VERSION. Se entrambe le configurazioni sono impostate, il valore GOOGLE_PYTHON_VERSION ha la precedenza sul file .python-version. Per impostazione predefinita, quando non vengono specificati sia il file .python-version sia la variabile di ambiente GOOGLE_PYTHON_VERSION, viene utilizzata l'ultima versione LTS di Python.

Per configurare il buildpack in modo che utilizzi Python 3.13 durante il deployment dell'app:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.13.x"

Puoi anche utilizzare un descrittore di progetto project.toml per codificare la variabile di ambiente insieme ai file di progetto. Consulta le istruzioni per creare l'applicazione con le variabili di ambiente.

Specificare le dipendenze con pip

Il buildpack Python supporta la gestione delle dipendenze delle applicazioni utilizzando pip. Le dipendenze dell'applicazione devono essere dichiarate in un file requirements.txt nella directory principale.

Il file requirements.txt contiene una riga per pacchetto. Ogni riga contiene il nome del pacchetto e, facoltativamente, la versione richiesta. Per maggiori dettagli, consulta il riferimento requirements.txt.

Di seguito è riportato un esempio di file requirements.txt:

requests==2.20.0
numpy

Configurare la funzionalità PIP

È possibile configurare il comportamento di pip utilizzando le variabili di ambiente:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

Dipendenze private da Artifact Registry

Un repository Python di Artifact Registry può ospitare dipendenze private per la tua funzione Python. Quando crei un'applicazione su Cloud Build, il buildpack Python genera automaticamente le credenziali di Artifact Registry per il service account Cloud Build. Devi includere solo l'URL di Artifact Registry nel tuo requirements.txt senza generare ulteriori credenziali. Ad esempio:

--extra-index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

Entry point dell'applicazione

La sezione seguente descrive il punto di ingresso predefinito per il buildpack Python.

Punto di ingresso per i deployment di origine Cloud Run

Questa funzionalità è disponibile solo se esegui il deployment del codice sorgente su Cloud Run con il runtime Python. Questa funzionalità non è applicabile se crei l'immagine container direttamente utilizzando pack build al di fuori del processo di deployment dell'origine Cloud Run.

Il buildpack Python supporta framework web moderni come FastAPI, Gradio e Streamlit.

Python versione 3.12 e precedenti

Se utilizzi Python versione 3.12 e precedenti, il buildpack Python utilizza per impostazione predefinita Gunicorn come server HTTP WSGI per il tuo workload. Il buildpack Python imposta il punto di ingresso predefinito su gunicorn -b :8080 main:app.

Python 3.13 e versioni successive

Per Python versione 3.13 e successive, il buildpack Python imposta il punto di ingresso predefinito per i deployment dell'origine Cloud Run in base alla configurazione del server web o del framework nel file requirements.txt. Questa impostazione predefinita si applica solo ai deployment dell'origine del servizio Cloud Run, non alle funzioni Cloud Run.

Quando esegui il deployment di un servizio Cloud Run dal codice sorgente utilizzando il runtime Python, il buildpack determina la versione di Python e il punto di ingresso predefinito nei seguenti modi:

  • Se non specifichi una versione di Python nei file sorgente, il buildpack Python imposta come predefinita l'ultima versione di Python supportata. Il buildpack determina il punto di ingresso predefinito in base al server web o al framework che hai configurato nel file requirements.txt.

  • Se non specifichi un server web o un framework nel file requirements.txt, il buildpack Python utilizza Gunicorn come server HTTP WSGI predefinito per il tuo workload. Il buildpack Python imposta il punto di ingresso predefinito su gunicorn -b :8080 main:app.

  • Il buildpack Python imposta il punto di ingresso predefinito in base al seguente ordine di precedenza, come definito nel file requirements.txt:

    1. gunicorn
    2. uvicorn
    3. gradio
    4. streamlit.

Configurare il server web o il framework

Per ogni configurazione Python comune nel file requirements.txt, la seguente tabella mostra i punti di ingresso predefiniti durante il deployment in Cloud Run dall'origine:

Configurazione principale Punto di ingresso predefinito Variabili di ambiente
gunicorn gunicorn -b :8080 main:app
numpy gunicorn -b :8080 main:app
fastapi
uvicorn		 uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn
gunicorn		 gunicorn -b :8080 main:app
gradio python main.py GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=8080
streamlit streamlit run main.py --server.address 0.0.0.0 --server.port 8080

Per evitare errori di deployment, utilizza una versione di Python supportata nei file sorgente e specifica un server web nel file requirements.txt.

In alternativa, puoi specificare il punto di ingresso eseguendo il seguente comando di deployment dell'origine:

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

Sostituisci quanto segue:

  • SERVICE: il nome del servizio di cui vuoi eseguire il deployment.
  • ENTRYPOINT: il punto di ingresso predefinito che vuoi utilizzare per il codice sorgente.

Se non riesci a eseguire il deployment del codice sorgente su Cloud Run o a trovare errori nei log, consulta la Guida alla risoluzione dei problemi di Cloud Run.

Punto di accesso per tutti gli altri deployment

Il buildpack Python utilizza Gunicorn come server HTTP WSGI predefinito per il tuo workload. Le app create con il buildpack Python avviano il processo gunicorn con le impostazioni predefinite, in modo simile all'esecuzione di:

gunicorn --bind :8080 main:app

Personalizzare il punto di ingresso dell'applicazione

Puoi personalizzare il comando di avvio delle applicazioni utilizzando un Procfile o una variabile di ambiente. Potresti doverlo fare per personalizzare le configurazioni dei punti di accesso predefiniti.

Puoi creare un file Procfile con le tue impostazioni personalizzate nella directory principale. Esempio:

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

In alternativa, puoi utilizzare la variabile di ambiente GOOGLE_ENTRYPOINT con il comando pack. Esempio:

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

Variabili di ambiente

Il buildpack Python supporta le seguenti variabili di ambiente per personalizzare il container

PIP_<key>

Consulta la documentazione di pip.

Esempio: PIP_DEFAULT_TIMEOUT=60 imposta --default-timeout=60 per i comandi pip.