Iniziare a utilizzare le funzioni Cloud Run

Iniziare a utilizzare le funzioni Cloud Run

Informazioni su questo codelab

subjectUltimo aggiornamento: mag 7, 2025
account_circleScritto da: Mete Atamel

1. Introduzione

Cloud Run functions è l'offerta Functions as a Service di Google Cloud basata su Cloud Run ed Eventarc, che offre un controllo più avanzato su prestazioni e scalabilità, nonché sul runtime e sugli attivatori delle funzioni da oltre 90 origini evento.

Questo codelab illustra la procedura per creare funzioni Cloud Run che rispondono alle chiamate HTTP e vengono attivate dai messaggi Pub/Sub e dai log di controllo di Cloud.

Questo codelab utilizza anche gli aggiornamenti automatici delle immagini di base per i deployment delle funzioni specificando un'immagine di base utilizzando il flag --base-image. Gli aggiornamenti automatici dell'immagine di base per Cloud Run consentono a Google di applicare automaticamente patch di sicurezza ai componenti di runtime del sistema operativo e del linguaggio dell'immagine di base. Non è necessario ricostruire o eseguire nuovamente il deployment del servizio per aggiornare l'immagine di base. Per ulteriori informazioni, consulta gli aggiornamenti automatici delle immagini di base.

Se preferisci non utilizzare gli aggiornamenti automatici delle immagini di base, puoi rimuovere il flag --base-image dagli esempi mostrati in questo codelab.

Obiettivi didattici

  • Panoramica delle funzioni Cloud Run e su come utilizzare gli aggiornamenti automatici delle immagini di base.
  • Come scrivere una funzione che risponda alle chiamate HTTP.
  • Come scrivere una funzione che risponda ai messaggi Pub/Sub.
  • Come scrivere una funzione che risponda agli eventi Cloud Storage.
  • Come suddividere il traffico tra due revisioni.
  • Come eliminare gli avvii a freddo con il numero minimo di istanze.

2. Configurazione e requisiti

Creare una cartella principale

Crea una cartella principale per tutti gli esempi.

mkdir crf-codelab
cd crf-codelab

Imposta le variabili di ambiente

Imposta le variabili di ambiente che verranno utilizzate durante questo codelab.

gcloud config set project <YOUR-PROJECT-ID>
REGION=<YOUR_REGION>

PROJECT_ID=$(gcloud config get-value project)

Abilita API

Attiva tutti i servizi necessari:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  eventarc.googleapis.com \
  run.googleapis.com \
  logging.googleapis.com \
  pubsub.googleapis.com

3. Funzione HTTP

Per la prima funzione, creiamo una funzione Node.js autenticata che risponda alle richieste HTTP. Utilizziamo anche un timeout di 10 minuti per mostrare come una funzione può avere più tempo per rispondere alle richieste HTTP.

Crea

Crea una cartella per l'app e vai a questa cartella:

mkdir hello-http
cd hello-http

Crea un file index.js che risponda alle richieste HTTP:

const functions = require('@google-cloud/functions-framework');

functions.http('helloWorld', (req, res) => {
  res.status(200).send('HTTP with Node.js in Cloud Run functions!');
});

Crea un file package.json per specificare le dipendenze:

{
  "name": "nodejs-run-functions-codelab",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^2.0.0"
  }
}

Esegui il deployment

Esegui il deployment della funzione:

gcloud run deploy nodejs-run-function \
      --source . \
      --function helloWorld \
      --base-image nodejs22 \
      --region $REGION \
      --timeout 600 \
      --no-allow-unauthenticated

Questo comando utilizza i buildpack per trasformare il codice sorgente della funzione in un'immagine container pronta per la produzione.

Tieni presente quanto segue:

  • il flag --source viene utilizzato per indicare a Cloud Run di compilare la funzione in un servizio basato su container eseguibile
  • Il flag --function (nuovo) viene utilizzato per impostare il punto di ingresso del nuovo servizio come la firma della funzione che vuoi che venga richiamata
  • Il flag --base-image (novità) specifica l'ambiente dell'immagine di base per la funzione, ad esempio nodejs22, python312, go123, java21, dotnet8, ruby33 o php83. Per ulteriori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta Immagini di base dei runtime.
  • (Facoltativo) il flag --timeout consente alla funzione di avere un timeout più lungo per rispondere alle richieste HTTP. In questo esempio, vengono utilizzati 600 secondi per dimostrare un tempo di risposta di 10 minuti.
  • (Facoltativo) --no-allow-unauthenticated per impedire l'invocazione pubblica della funzione

Test

Testa la funzione con i seguenti comandi:

# get the Service URL
SERVICE_URL="$(gcloud run services describe nodejs-run-function --region $REGION --format 'value(status.url)')"

# invoke the service
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

Dovresti vedere il messaggio HTTP with Node.js in Cloud Run functions! come risposta.

4. Funzione Pub/Sub

Per la seconda funzione, creiamo una funzione Python attivata da un messaggio Pub/Sub pubblicato in un argomento specifico.

Configura i token di autenticazione Pub/Sub

Se hai attivato l'account di servizio Pub/Sub il giorno 8 aprile 2021 o in una data precedente, concedi il ruolo iam.serviceAccountTokenCreator all'account di servizio Pub/Sub:

PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)')

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member  serviceAccount:service-$PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
  --role roles/iam.serviceAccountTokenCreator

Crea

Crea un argomento Pub/Sub da utilizzare per il sample:

TOPIC=cloud-run-functions-pubsub-topic
gcloud pubsub topics create $TOPIC

Crea una cartella per l'app e vai a questa cartella:

mkdir ../hello-pubsub
cd ../hello-pubsub

Crea un file main.py che registri un messaggio contenente l'ID CloudEvent:

import functions_framework

@functions_framework.cloud_event
def hello_pubsub(cloud_event):
   print('Pub/Sub with Python in Cloud Run functions! Id: ' + cloud_event['id'])

Crea un file requirements.txt con i seguenti contenuti per specificare le dipendenze:

functions-framework==3.*

Esegui il deployment

Esegui il deployment della funzione:

gcloud run deploy python-pubsub-function \
       --source . \
       --function hello_pubsub \
       --base-image python313 \
       --region $REGION \
       --no-allow-unauthenticated

Recupera il numero di progetto da utilizzare per l'identità dell'account di servizio.

PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)')

Crea l'attivatore

gcloud eventarc triggers create python-pubsub-function-trigger  \
    --location=$REGION \
    --destination-run-service=python-pubsub-function  \
    --destination-run-region=$REGION \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic=projects/$PROJECT_ID/topics/$TOPIC \
    --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

Test

Testa la funzione inviando un messaggio all'argomento:

gcloud pubsub topics publish $TOPIC --message="Hello World"

Nei log dovresti vedere il CloudEvent ricevuto:

gcloud run services logs read python-pubsub-function --region $REGION --limit=10

5. Funzione Cloud Storage

Per la prossima funzione, creiamo una funzione Node.js che risponda agli eventi di un bucket Cloud Storage.

Configura

Per utilizzare le funzioni Cloud Storage, concedi il ruolo IAM pubsub.publisher all'account di servizio Cloud Storage:

SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT \
  --role roles/pubsub.publisher

Crea

Crea una cartella per l'app e vai a questa cartella:

mkdir ../hello-storage
cd ../hello-storage

Crea un file index.js che risponda semplicemente agli eventi Cloud Storage:

const functions = require('@google-cloud/functions-framework');

functions.cloudEvent('helloStorage', (cloudevent) => {
  console.log('Cloud Storage event with Node.js in Cloud Run functions!');
  console.log(cloudevent);
});

Crea un file package.json per specificare le dipendenze:

{
  "name": "nodejs-crf-cloud-storage",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^2.0.0"
  }
}

Esegui il deployment

Innanzitutto, crea un bucket Cloud Storage (o utilizzane uno esistente):

export BUCKET_NAME="gcf-storage-$PROJECT_ID"
​​export BUCKET="gs://gcf-storage-$PROJECT_ID"
gsutil mb -l $REGION $BUCKET

Esegui il deployment della funzione:

gcloud run deploy nodejs-crf-cloud-storage \
 --source . \
 --base-image nodejs22 \
 --function helloStorage \
 --region $REGION \
 --no-allow-unauthenticated

Una volta eseguita il deployment della funzione, puoi visualizzarla nella sezione Cloud Run della console Cloud.

Ora crea l'trigger Eventarc.

BUCKET_REGION=$REGION

gcloud eventarc triggers create nodejs-crf-cloud-storage-trigger \
  --location=$BUCKET_REGION \
  --destination-run-service=nodejs-crf-cloud-storage \
  --destination-run-region=$REGION \
  --event-filters="type=google.cloud.storage.object.v1.finalized" \
  --event-filters="bucket=$BUCKET_NAME" \
  --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

Test

Testa la funzione caricando un file nel bucket:

echo "Hello World" > random.txt
gsutil cp random.txt $BUCKET/random.txt

Nei log dovresti vedere il CloudEvent ricevuto:

gcloud run services logs read nodejs-crf-cloud-storage --region $REGION --limit=10

6. Suddivisione del traffico

Le funzioni Cloud Run supportano più revisioni delle funzioni, suddividendo il traffico tra revisioni diverse ed eseguendo il rollback della funzione a una versione precedente.

In questo passaggio, eseguirai il deployment di due revisioni di una funzione e poi suddividerai il traffico tra le due in modo uniforme.

Crea

Crea una cartella per l'app e vai a questa cartella:

mkdir ../traffic-splitting
cd ../traffic-splitting

Crea un file main.py con una funzione Python che legga una variabile di ambiente di colore e risponda con Hello World in quel colore di sfondo:

import os

color = os.environ.get('COLOR')

def hello_world(request):
    return f'<body style="background-color:{color}"><h1>Hello World!</h1></body>'

Crea un file requirements.txt con i seguenti contenuti per specificare le dipendenze:

functions-framework==3.*

Esegui il deployment

Esegui il deployment della prima revisione della funzione con uno sfondo arancione:

COLOR=orange
gcloud run deploy hello-world-colors \
 --source . \
 --base-image python313 \
 --function hello_world \
 --region $REGION \
 --allow-unauthenticated \
 --update-env-vars COLOR=$COLOR

A questo punto, se testi la funzione visualizzando l'attivatore HTTP (l'output URI del comando di deployment riportato sopra) nel browser, dovresti vedere Hello World con uno sfondo arancione:

36ca0c5f39cc89cf.png

Esegui il deployment della seconda revisione con uno sfondo giallo:

COLOR=yellow
gcloud run deploy hello-world-colors \
 --source . \
 --base-image python313 \
 --function hello_world \
 --region $REGION \
 --allow-unauthenticated \
 --update-env-vars COLOR=$COLOR

Poiché si tratta dell'ultima revisione, se testi la funzione dovresti vedere Hello World con uno sfondo giallo:

391286a08ad3cdde.png

Suddividere il traffico 50-50

Per suddividere il traffico tra le revisioni arancioni e gialle, devi trovare gli ID revisione dei servizi Cloud Run. Questo è il comando per visualizzare gli ID revisione:

gcloud run revisions list --service hello-world-colors \
  --region $REGION --format 'value(REVISION)'

L'output dovrebbe essere simile al seguente:

hello-world-colors-00001-man
hello-world-colors-00002-wok

Ora suddividi il traffico tra queste due revisioni come segue (aggiorna X-XXX in base ai nomi delle revisioni):

gcloud run services update-traffic hello-world-colors \
  --region $REGION \
  --to-revisions hello-world-colors-0000X-XXX=50,hello-world-colors-0000X-XXX=50

Test

Testa la funzione visitando il relativo URL pubblico. La metà delle volte dovresti vedere la revisione arancione e l'altra metà la revisione gialla:

36ca0c5f39cc89cf.png 391286a08ad3cdde.png

Per ulteriori informazioni, consulta Rollback, implementazioni graduali e migrazione del traffico.

7. Numero minimo di istanze

Nelle funzioni Cloud Run, puoi specificare un numero minimo di istanze di funzione da mantenere disponibili e pronte per gestire le richieste. Questo è utile per limitare il numero di avvii a freddo.

In questo passaggio, eseguirai il deployment di una funzione con un'inizializzazione lenta. Noterai il problema di avvio a freddo. Poi, esegui il deployment della funzione con il valore dell'istanza minima impostato su 1 per eliminare l'avvio a freddo.

Crea

Crea una cartella per l'app e vai a questa cartella:

mkdir ../min-instances
cd ../min-instances

Crea un file main.go. Questo servizio Go ha una funzione init che rimane inattiva per 10 secondi per simulare un'inizializzazione lunga. Dispone inoltre di una funzione HelloWorld che risponde alle chiamate HTTP:

package p

import (
        "fmt"
        "net/http"
        "time"
)

func init() {
        time.Sleep(10 * time.Second)
}

func HelloWorld(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, "Slow HTTP Go in Cloud Run functions!")
}

Esegui il deployment

Esegui il deployment della prima revisione della funzione con il valore predefinito dell'istanza minima pari a zero:

gcloud run deploy go-slow-function \
 --source . \
 --base-image go123 \
 --function HelloWorld \
 --region $REGION \
 --no-allow-unauthenticated

Testa la funzione con questo comando:

# get the Service URL
SERVICE_URL="$(gcloud run services describe go-slow-function --region $REGION --format 'value(status.url)')"

# invoke the service
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

Noterai un ritardo di 10 secondi (avvio a freddo) alla prima chiamata, dopodiché vedrai il messaggio. Le chiamate successive dovrebbero essere restituite immediatamente.

Impostare il numero minimo di istanze

Per eliminare l'avvio a freddo alla prima richiesta, esegui nuovamente il deployment della funzione con il flag --min-instances impostato su 1 come segue:

gcloud run deploy go-slow-function \
 --source . \
 --base-image go123 \
 --function HelloWorld \
 --region $REGION \
 --no-allow-unauthenticated \
 --min-instances 1

Test

Testa di nuovo la funzione:

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

Non dovresti più vedere il ritardo di 10 secondi nella prima richiesta. Il problema di avvio a freddo per la prima chiamata (dopo molto tempo senza) non si verifica più, grazie al numero minimo di istanze.

Per ulteriori informazioni, consulta la sezione Utilizzare istanze minime.

8. Complimenti!

Complimenti per aver completato il codelab.

Argomenti trattati

  • Panoramica delle funzioni Cloud Run e su come utilizzare gli aggiornamenti automatici delle immagini di base.
  • Come scrivere una funzione che risponda alle chiamate HTTP.
  • Come scrivere una funzione che risponda ai messaggi Pub/Sub.
  • Come scrivere una funzione che risponda agli eventi Cloud Storage.
  • Come suddividere il traffico tra due revisioni.
  • Come eliminare gli avvii a freddo con il numero minimo di istanze.
bug_report Segnala un errore