Inizia a utilizzare le funzioni Cloud Run basate su eventi

1. Introduzione

Panoramica

Cloud Run Functions è un nuovo modo per eseguire il deployment dei carichi di lavoro utilizzando i paradigmi di gestione degli eventi e la firma della funzione GCF. Anziché utilizzare il nostro processo di build e le nostre configurazioni di deployment, Cloud Run Functions ti offre il controllo diretto sul servizio di base creato su Cloud Run.

Con Cloud Run Functions, forniamo la semplice esperienza utente del deployment dell'origine Cloud Run, offrendo agli sviluppatori il controllo completo sui loro carichi di lavoro utilizzando le configurazioni di Cloud Run.

In questa sezione, imparerai a eseguire il deployment di una funzione basata su eventi in Node. Esegui il deployment di una funzione che viene attivata ogni volta che un oggetto viene finalizzato in un bucket Google Cloud Storage.

Questo codelab utilizza gli esempi di Node.js riportati di seguito. Tuttavia, puoi utilizzare gli esempi di codice di Cloud Functions (2ª gen.) nella lingua che preferisci:

Cosa imparerai a fare

  • Come eseguire il deployment di una funzione Cloud Run basata su eventi che viene attivata ogni volta che un oggetto viene caricato in un bucket GCS
  • Come creare un service account con i ruoli appropriati per ricevere un evento da Cloud Storage e richiamare la funzione Cloud Run

2. Configura le variabili di ambiente e abilita le API

Aggiorna gcloud CLI

Questo codelab richiede l'installazione di una versione recente di gcloud CLI. Puoi aggiornare la CLI eseguendo

gcloud components update

Abilita API

Prima di poter iniziare a utilizzare questo codelab, devi abilitare diverse API. Questo codelab richiede l'utilizzo delle seguenti API. Puoi abilitare queste API eseguendo il seguente comando:

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

Configura le variabili di ambiente

Puoi impostare le variabili di ambiente che verranno utilizzate in questo codelab.

PROJECT_ID=<YOUR_PROJECT_ID>
REGION=<YOUR_REGION, e.g. us-central1>

gcloud config set project $PROJECT_ID
SERVICE_NAME=crf-event-codelab
BUCKET_NAME=$PROJECT_ID-$SERVICE_NAME
TRIGGER_NAME=$SERVICE_NAME-trigger

3. Crea un bucket di archiviazione e un service account

Crea un bucket di archiviazione

Puoi creare un bucket Cloud Storage eseguendo questo comando:

gsutil mb -l us-central1 gs://$BUCKET_NAME

Crea un account di servizio

Per questo esempio, creerai un service account con le autorizzazioni Eventarc e il ruolo Invoker di Cloud Run richiesti per ricevere un evento da Cloud Storage e richiamare la funzione Cloud Run.

Innanzitutto, crea il service account.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

SERVICE_ACCOUNT="cloud-run-functions"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run functions Eventarc service account"

Successivamente, concedi il ruolo Destinatario di eventi Eventarc (roles/eventarc.eventReceiver) al progetto al service account associato al trigger Eventarc in modo che il trigger possa ricevere eventi dai provider di eventi.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/eventarc.eventReceiver

Poi, concedi al service account il ruolo Invoker di Cloud Run in modo che possa richiamare la funzione.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/run.invoker

4. Crea ed esegui il deployment della funzione

Innanzitutto, crea una directory per il codice sorgente e accedi tramite cd.

mkdir ../$SERVICE_NAME && cd $_

Quindi, crea un file package.json con il seguente contenuto:

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

Successivamente, crea un file index.js con il seguente contenuto:

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

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent("helloGCS", (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);

    const file = cloudEvent.data;
    console.log(`Bucket: ${file.bucket}`);
    console.log(`File: ${file.name}`);
    console.log(`Metageneration: ${file.metageneration}`);
    console.log(`Created: ${file.timeCreated}`);
    console.log(`Updated: ${file.updated}`);
});

Ora puoi eseguire il deployment della funzione Cloud Run eseguendo il seguente comando:

gcloud beta run deploy $SERVICE_NAME \
 --source . \
      --function helloGCS \
      --region $REGION \
      --no-allow-unauthenticated

Tieni presente quanto segue:

  • il flag –source viene utilizzato per indicare a Cloud Run di creare la funzione in un servizio basato su container eseguibile
  • Il flag –function (nuovo) viene utilizzato per impostare il punto di ingresso del nuovo servizio in modo che sia la firma della funzione che vuoi richiamare
  • (facoltativo) –no-allow-unauthenticated per impedire che la funzione possa essere chiamata pubblicamente

Puoi visualizzare il nuovo servizio crf-event-codelab eseguendo questo comando:

gcloud beta run services describe $SERVICE_NAME

5. Creare l'evento

Possiamo creare un trigger Eventarc per inviare messaggi alla nostra funzione ogni volta che un oggetto viene finalizzato in Google Cloud Storage:

BUCKET_REGION=$REGION

gcloud eventarc triggers create $TRIGGER_NAME \
     --location=$REGION \
     --destination-run-service=$SERVICE_NAME \
  --destination-run-region=$BUCKET_REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$BUCKET_NAME" \
     --service-account=$SERVICE_ACCOUNT_ADDRESS

Tieni presente quanto segue:

  • gcs-function-trigger è il nome del trigger
  • crf-event-codelab è il nome del servizio Cloud Run in cui viene eseguito il deployment della nostra funzione
  • Per il flag –event-filters, non utilizzare il prefisso gs:// nel nome del bucket.

Un tutorial dettagliato sulla configurazione del servizio di attivazione da Cloud Storage utilizzando Eventarc è disponibile nella documentazione di Cloud Run qui: https://cloud.google.com/run/docs/tutorials/eventarc

6. Testa la funzione

Al termine del deployment, vedrai l'URL del servizio. Per richiamare la funzione, devi inviare una richiesta autenticata con il tuo token ID o il token ID di un'entità che dispone del ruolo Invoker di Cloud Run, come mostrato di seguito:

# get the Service URL
SERVICE_URL="$(gcloud run services describe $SERVICE_NAME --region us-central1 --format 'value(status.url)')"

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

Ora che la funzione è stata sottoposta a deployment e il trigger è stato creato, possiamo richiamarla.

Crea un file e caricalo nel bucket Cloud Storage. Puoi farlo tramite l'interfaccia web di Cloud Console o utilizzando lo strumento CLI gsutil, ad esempio:

echo "hello world" > test.txt
gsutil cp test.txt gs://$BUCKET_NAME

Quando il file viene caricato correttamente, viene generato un evento e la funzione stampa alcune informazioni di base sull'oggetto, ad esempio il nome del file. Puoi trovare questo output nelle voci di log della funzione nella console Cloud. In alternativa, puoi eseguire una query per questo output utilizzando gcloud CLI:

gcloud logging read "resource.labels.service_name=$SERVICE_NAME AND textPayload: File" --format=json

e dovresti vedere l'output seguente

"textPayload": "File: test.txt"

7. Complimenti!

Congratulazioni per aver completato il codelab.

Ti consigliamo di consultare la documentazione di Cloud Run Functions.

Argomenti trattati

  • Come eseguire il deployment di una funzione Cloud Run basata su eventi che viene attivata ogni volta che un oggetto viene caricato in un bucket GCS
  • Come creare un service account con i ruoli appropriati per ricevere un evento da Cloud Storage e richiamare la funzione Cloud Run

8. Esegui la pulizia

Per evitare addebiti involontari (ad esempio, se questo servizio Cloud Run viene richiamato inavvertitamente più volte rispetto all'allocazione mensile di chiamate a Cloud Run nel livello senza costi), puoi eliminare il servizio Cloud Run o il progetto che hai creato nel passaggio 2.

Per eliminare i servizi Cloud Run, vai alla console Cloud Run all'indirizzo https://console.cloud.google.com/run/ ed elimina il servizio crf-event-codelab che hai creato in questo codelab.

Se scegli di eliminare l'intero progetto, puoi andare alla pagina https://console.cloud.google.com/cloud-resource-manager, selezionare il progetto che hai creato nel passaggio 2 e scegliere Elimina. Se elimini il progetto, dovrai cambiare progetto in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.