Hello Cloud Run con Python (FastAPI)

1. Introduzione

Cloud Run è una piattaforma gestita di computing che consente di eseguire container stateless richiamabili tramite richieste HTTP. È basata sul progetto open source Knative, consente quindi la portabilità dei tuoi carichi di lavoro su più piattaforme. Cloud Run è serverless. Astrae completamente la gestione dell'infrastruttura per consentirti di concentrarti su quello che conta davvero: creare applicazioni fantastiche.

L'obiettivo di questo tutorial è creare una semplice FastAPI ed eseguirne il deployment su Cloud Run.

Obiettivi didattici

• Come creare un'applicazione "Hello World" FastAPI.
• Testare l'applicazione eseguendo il server FastAPI in modalità dev.
• Cloud Buildpacks e come la presenza di fastapi e uvicorn in un file requirements.txt consenta di non utilizzare Dockerfile.
• Come eseguire il deployment dell'applicazione FastAPI su Cloud Run.

2. Configurazione e requisiti

Configurazione dell'ambiente autonomo

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già un account Gmail o Google Workspace, devi crearne uno.

• Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi aggiornarla in qualsiasi momento.
• L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca; in genere non ti interessa quale sia. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se non ti piace l'ID generato, puoi generarne un altro casuale. In alternativa, puoi provare a utilizzare il tuo e verificare se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre i valori nella documentazione.

Attenzione: un ID progetto è univoco a livello globale e non può essere utilizzato da nessun altro dopo che lo hai selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota: se utilizzi un account Gmail, puoi lasciare la località predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una località che abbia senso per la tua organizzazione.

2. Dopodiché, dovrai abilitare la fatturazione nella console Cloud per utilizzare le risorse/API Cloud. L'esecuzione di questo codelab non costerà molto, se non nulla. Per arrestare le risorse ed evitare addebiti di fatturazione oltre questo tutorial, puoi eliminare le risorse che hai creato o eliminare il progetto. I nuovi utenti Google Cloud possono usufruire del programma di prova senza costi di 300$.

Avvia Cloud Shell

Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo tutorial utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Attiva Cloud Shell

1. Nella console Cloud, fai clic su Attiva Cloud Shell.

Se è la prima volta che avvii Cloud Shell, viene visualizzata una schermata intermedia che ne descrive le funzionalità. Se è stata visualizzata una schermata intermedia, fai clic su Continua.

Bastano pochi istanti per eseguire il provisioning e connettersi a Cloud Shell.

Questa macchina virtuale è dotata di tutti gli strumenti di sviluppo necessari. Offre una home directory permanente da 5 GB e viene eseguita in Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. La maggior parte, se non tutto, del lavoro in questo codelab può essere eseguita con un browser.

Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è autenticato e il progetto è impostato sul tuo ID progetto.

2. Esegui questo comando in Cloud Shell per verificare che l'account sia autenticato:

gcloud auth list

Output comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Nota: lo strumento a riga di comando gcloud è lo strumento a riga di comando potente e unificato in Google Cloud. È già installato in Cloud Shell. Noterai il supporto per il completamento con il tasto Tab. La prima volta che esegui un comando, potrebbe esserti chiesto di autenticarti. Per saperne di più, consulta la panoramica dello strumento a riga di comando gcloud .

3. Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto:

gcloud config list project

Output comando

[core]
project = <PROJECT_ID>

In caso contrario, puoi impostarlo con questo comando:

gcloud config set project <PROJECT_ID>

Output comando

Updated property [core/project].

Nota: se stai completando questo tutorial al di fuori di Cloud Shell, segui la procedura Configurare le credenziali predefinite dell'applicazione.

3. Abilita le API

Da Cloud Shell, abilita le API Artifact Registry, Cloud Build e Cloud Run:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com

Viene visualizzato un messaggio di operazione riuscita simile a questo:

Operation "operations/..." finished successfully.

Per eseguire il deployment dell'applicazione, Cloud Run si accoppia con l'ecosistema dei container:

• Cloud Build crea automaticamente un'immagine container dal codice sorgente ed esegue il push in Artifact Registry.
• Artifact Registry gestisce l'immagine container.

Ora puoi iniziare a lavorare e scrivere la tua applicazione...

4. Scrivi l'applicazione

In questo passaggio, creerai un'applicazione Python FastAPI "Hello World" che risponde alle richieste HTTP.

Directory di lavoro

Utilizza Cloud Shell per creare una directory di lavoro denominata helloworld-fastapi e passa a questa directory:

mkdir ~/helloworld-fastapi && cd ~/helloworld-fastapi

main.py

Crea un file denominato main.py:

touch main.py

Modifica il file con l'editor a riga di comando che preferisci (nano, vim o emacs) o facendo clic sul pulsante Editor di Cloud Shell:

Per modificare direttamente il file con l'editor di Cloud Shell, utilizza questo comando:

cloudshell edit main.py

main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def hello(name: str = "World"):
    """Return a friendly HTTP greeting."""
    return {
        "message": f"Hello {name}!"
    }

Questo codice crea un servizio web di base che risponde alle richieste HTTP GET con un messaggio amichevole.

requirements.txt

Riapri il terminale e aggiungi un file denominato requirements.txt per definire le dipendenze:

touch requirements.txt

Per modificare direttamente il file con l'editor di Cloud Shell, utilizza questo comando:

cloudshell edit requirements.txt

requirements.txt

# https://pypi.org/project/fastapi
fastapi[standard]==0.116.1

# https://pypi.org/project/uvicorn
uvicorn==0.35.0

Sono documentate molte altre lingue per iniziare a utilizzare Cloud Run. Puoi trovare le istruzioni per Go, Node.js, Java, C#, C++, PHP, Ruby, script shell e altri qui: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

L'applicazione FastAPI è pronta per il deployment, ma prima è il momento di testarla...

5. Testa l'applicazione

Per testare l'applicazione, utilizza uv (il gestore di pacchetti e progetti estremamente veloce di Python), che è preinstallato in Cloud Shell.

Per testare l'applicazione, crea un ambiente virtuale:

uv venv

Installa le dipendenze:

uv pip install -r requirements.txt

Avvia l'applicazione in modalità dev:

uv run fastapi dev main.py --port=8080

I log mostrano che sei in modalità di sviluppo:

FastAPI   Starting development server 🚀

          Searching for package file structure from directories with __init__.py files
          Importing from /home/user/code/helloworld-fastapi

  module  🐍 main.py

    code  Importing the FastAPI app object from the module with the following code:

          from main import app

     app  Using import string: main:app

  server   Server started at http://127.0.0.1:8080
  server   Documentation at http://127.0.0.1:8080/docs

     tip   Running in development mode, for production use: fastapi run

           Logs:

    INFO   Will watch for changes in these directories: ['/home/user/code/helloworld-fastapi']
    INFO   Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
    INFO   Started reloader process [19627] using WatchFiles
    INFO   Started server process [19629]
    INFO   Waiting for application startup.
    INFO   Application startup complete.

Nella finestra di Cloud Shell, fai clic sull'icona Web Preview e seleziona Preview on port 8080:

Dovrebbe aprirsi una finestra del browser con il messaggio Hello World!.

Puoi anche aprire un'altra sessione di Cloud Shell (una nuova scheda del terminale) facendo clic sull'icona + e inviando una richiesta web all'applicazione in esecuzione in locale:

curl localhost:8080

Dovresti ricevere la seguente risposta:

{"message": "Hello World!"}

Al termine, torna alla sessione principale di Cloud Shell e arresta il server di sviluppo FastAPI con CTRL+C.

L'applicazione funziona come previsto: è il momento di eseguirne il deployment...

6. Esegui il deployment in Cloud Run

Cloud Run è regionale, il che significa che l'infrastruttura che esegue i servizi Cloud Run si trova in una regione specifica ed è gestita da Google per essere disponibile in modo ridondante in tutte le zone all'interno di quella regione. Definisci la regione che utilizzerai per il deployment, ad esempio:

REGION=europe-west4

Per l'elenco completo delle regioni supportate, consulta Località di Cloud Run (completamente gestito).

Assicurati di essere ancora nella directory di lavoro:

ls

Dovrebbero essere elencati i seguenti file:

main.py  requirements.txt

Prima del deployment, crea un file .gcloudignore con .venv/ al suo interno. In questo modo, il deployment di Cloud Run non include l'ambiente virtuale creato da uv durante i test locali.

Crea il file .gcloudignore con il seguente comando:

echo ".venv/" > .gcloudignore

Esegui il deployment dell'applicazione in Cloud Run:

gcloud run deploy helloworld-fastapi \
  --source . \
  --region $REGION \
  --allow-unauthenticated

• L'opzione --allow-unauthenticated rende il servizio disponibile pubblicamente. Per evitare richieste non autenticate, utilizza --no-allow-unauthenticated.

Per controllare tutte le opzioni, utilizza gcloud run deploy --help.

La prima volta, ti verrà chiesto di creare un repository Artifact Registry. Tocca Enter per convalidare:

Deploying from source requires an Artifact Registry Docker repository to store
built containers. A repository named [cloud-run-source-deploy] in region [REGION]
will be created.

Do you want to continue (Y/n)?

Viene avviato il caricamento del codice sorgente nel repository Artifact Registry e la creazione dell'immagine container:

Building using Buildpacks and deploying container ...
* Building and deploying new service... Building Container.           
  OK Creating Container Repository...
  OK Uploading sources...
  * Building Container... Logs are available at ...

Cloud Build utilizza Buildpacks, che rileva automaticamente la lingua del codice sorgente e crea un'immagine container basata sull'ultima versione stabile dell'interprete Python (Python 3.13 al momento della scrittura).

Per utilizzare Buildpacks con un server web ASGI come uvicorn, richiesto da FastAPI, la presenza di uvicorn deve essere nel file requirements.txt. In caso contrario, Buildpacks utilizzerà per impostazione predefinita un server web WSGI che utilizza gunicorn, il che comporterà errori con FastAPI.

Per maggiori dettagli, consulta Creare un'applicazione Python.

Attendi qualche istante fino al completamento del deployment. Se l'operazione riesce, la riga di comando visualizza l'URL del servizio:

...
OK Building and deploying new service... Done.
  OK Creating Container Repository...
  OK Uploading sources...
  OK Building Container... Logs are available at ...
  OK Creating Revision... Creating Service.
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [SERVICE]... has been deployed and is serving 100 percent of traffic.
Service URL: https://SERVICE-PROJECTHASH-REGIONID.a.run.app

Puoi ottenere l'URL del servizio con questo comando:

SERVICE_URL=$( \
  gcloud run services describe helloworld-fastapi \
  --region $REGION \
  --format "value(status.address.url)" \
)
echo $SERVICE_URL

Dovrebbe essere visualizzato un risultato simile al seguente:

https://helloworld-fastapi-PROJECTHASH-REGIONID.a.run.app

Ora puoi utilizzare l'applicazione aprendo l'URL del servizio in un browser web:

Puoi anche chiamare l'applicazione da Cloud Shell:

curl $SERVICE_URL?name=me

Dovresti ricevere il saluto previsto:

{"message": "Hello me!"}

Sebbene questo breve lab sia stato eseguito utilizzando la riga di comando gcloud, Cloud Run è disponibile anche tramite la console Cloud ( console.cloud.google.com/run). Dovresti vedere il servizio helloworld-fastapi elencato:

Puoi anche utilizzare la console per eseguire il deployment dei servizi Cloud Run.

Complimenti! Hai eseguito il deployment di un'applicazione in Cloud Run. Cloud Run scala automaticamente e orizzontalmente l'immagine container per gestire le richieste ricevute, quindi fa lo scale down quando la domanda diminuisce. Paghi solo per la CPU, la memoria e le risorse di rete utilizzate durante la gestione delle richieste per questo servizio Cloud Run.

7. Libera spazio

Sebbene non siano previsti addebiti per Cloud Run quando il servizio non è in uso, ti potrebbero comunque essere addebitati i costi di archiviazione dell'immagine container in Artifact Registry. Per evitare addebiti, puoi eliminare il repository o il progetto Cloud. L'eliminazione del progetto Cloud interrompe la fatturazione per tutte le risorse utilizzate all'interno del progetto.

Per eliminare il repository di immagini container:

gcloud artifacts repositories delete cloud-run-source-deploy \
  --location $REGION

Per eliminare il servizio Cloud Run:

gcloud run services delete helloworld-fastapi \
  --region $REGION

Per eliminare il progetto Google Cloud,

1. Recupera l'ID progetto corrente:

PROJECT_ID=$(gcloud config get-value core/project)

2. Assicurati che sia il progetto che vuoi eliminare:

echo $PROJECT_ID

3. Elimina il progetto:

gcloud projects delete $PROJECT_ID

8. Complimenti!

Hai creato un'applicazione web FastAPI "Hello World" e ne hai eseguito il deployment su Cloud Run.

Argomenti trattati

• Come creare un'applicazione "Hello World" FastAPI.
• Testare l'applicazione eseguendo il server FastAPI in modalità dev.
• Cloud Buildpacks e come la presenza di fastapi e uvicorn in un file requirements.txt consenta di non utilizzare Dockerfile.
• Eseguire il deployment dell'applicazione FastAPI su Cloud Run.

Scopri di più

• Consulta la documentazione di Cloud Run
• Completa il passaggio da sviluppo a produzione in tre semplici passaggi con Cloud Run per esplorare altre opzioni
• Completa Django su Cloud Run per creare un database Cloud SQL, gestire le credenziali con Secret Manager ed eseguire il deployment di Django
• Scopri altri codelab di Cloud Run...