Hello Cloud Run con Python (FastAPI)

1. Introduzione

Cloud Run è una piattaforma di computing gestita che consente di eseguire container stateless richiamabili tramite richieste HTTP. È basato 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 applicazione web FastAPI ed eseguirne il deployment su Cloud Run.

Obiettivi didattici

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

2. Configurazione e requisiti

Configurazione dell'ambiente autonoma

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora 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 sempre aggiornarlo.
• 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, di solito non ti interessa di cosa si tratta. 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 crearne uno e vedere 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 questi 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 posizione predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono beneficiare del programma 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 è caricata con tutti gli strumenti di sviluppo necessari. Offre una home directory permanente da 5 GB e viene eseguita in Google Cloud, migliorando notevolmente le prestazioni di rete e l'autenticazione. Gran parte, se non tutto, il lavoro in questo codelab può essere svolto 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 è il potente strumento a riga di comando unificato di Google Cloud. È già installato in Cloud Shell. Noterai il supporto del completamento automatico. Potrebbe esserti chiesto di autenticarti la prima volta che esegui un comando. 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 completi questo tutorial al di fuori di Cloud Shell, segui la procedura per 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 abbina all'ecosistema di 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 il tuo editor della riga di comando preferito (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 essere implementata, ma prima è il momento di testarla…

5. testa l'applicazione

Per testare l'applicazione, utilizza uv (il gestore di progetti e pacchetti 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 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 tuoi 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-west1

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

Assicurati di trovarti 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/. 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 il linguaggio del codice sorgente e crea un'immagine container basata sull'ultima versione stabile dell'interprete Python (Python 3.13 al momento della stesura).

Per utilizzare i buildpack 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.

Quindi, 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!"}

Anche se questo breve lab è 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 su 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. Esegui la pulizia

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. Puoi eliminare il repository o il progetto Cloud per evitare addebiti. L'eliminazione del progetto Cloud interrompe la fatturazione per tutte le risorse utilizzate al suo interno.

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 tuo 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.
• Test dell'applicazione eseguendo il server FastAPI in modalità dev.
• Cloud Buildpacks e come la presenza di fastapi e uvicorn in un requirements.txt consenta di non dover utilizzare Dockerfile.
• Deployment dell'applicazione FastAPI in Cloud Run.

Scopri di più

• Consulta la documentazione di Cloud Run.
• Completa Dev to Prod in Three Easy Steps with 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 per Cloud Run…