Erste Schritte mit ereignisgesteuerten Cloud Run-Funktionen

1. Einführung

Übersicht

Cloud Run-Funktionen sind eine neue Möglichkeit, Arbeitslasten mit den bekannten GCF-Ereignisparadigmen und Funktionssignaturen bereitzustellen. Anstatt unseren Buildprozess und unsere Bereitstellungskonfigurationen zu verwenden, haben Sie mit Cloud Run Functions die direkte Kontrolle über den zugrunde liegenden Dienst, der in Cloud Run erstellt wurde.

Mit Cloud Run Functions bieten wir die einfache Benutzeroberfläche des Cloud Run-Quell-Deployments und Entwicklern die vollständige Kontrolle über ihre Arbeitslasten mit Cloud Run-Konfigurationen.

In diesem Abschnitt erfahren Sie, wie Sie eine ereignisgesteuerte Funktion in Node bereitstellen. Sie stellen eine Funktion bereit, die ausgelöst wird, wenn ein Objekt in einem Google Cloud Storage-Bucket abgeschlossen wird.

In diesem Codelab werden in den folgenden Beispielen Node.js-Beispiele verwendet. Sie können die Codebeispiele für Cloud Functions der 2. Generation jedoch in der Sprache Ihrer Wahl verwenden:

Aufgaben in diesem Lab

  • Ereignisgesteuerte Cloud Run-Funktion bereitstellen, die ausgelöst wird, wenn ein Objekt in einen GCS-Bucket hochgeladen wird
  • Dienstkonto mit den richtigen Rollen zum Empfangen eines Ereignisses aus Cloud Storage und Aufrufen der Cloud Run-Funktion erstellen

2. Umgebungsvariablen einrichten und APIs aktivieren

gcloud CLI aktualisieren

Für dieses Codelab muss eine aktuelle Version der gcloud CLI installiert sein. Sie können die Befehlszeile mit dem Befehl

gcloud components update

APIs aktivieren

Bevor Sie dieses Codelab verwenden können, müssen Sie mehrere APIs aktivieren. Für dieses Codelab sind die folgenden APIs erforderlich. Sie können diese APIs mit dem folgenden Befehl aktivieren:

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

Umgebungsvariablen einrichten

Sie können Umgebungsvariablen festlegen, die in diesem Codelab verwendet werden.

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. Speicher-Bucket und Dienstkonto erstellen

Storage-Bucket erstellen

Sie können einen Cloud Storage-Bucket mit dem folgenden Befehl erstellen:

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

Dienstkonto erstellen

In diesem Beispiel erstellen Sie ein Dienstkonto mit den erforderlichen EventArc-Berechtigungen und der Rolle „Cloud Run-Aufrufer“, um ein Ereignis aus Cloud Storage zu empfangen und die Cloud Run-Funktion aufzurufen.

Erstellen Sie zuerst das Dienstkonto.

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"

Weisen Sie dem Dienstkonto, das Ihrem Eventarc-Trigger zugeordnet ist, die Rolle „Eventarc-Ereignisempfänger“ (roles/eventarc.eventReceiver) für das Projekt zu, damit der Trigger Ereignisse vom Ereignisanbieter empfangen kann.

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

Weisen Sie dem Dienstkonto dann die Rolle „Cloud Run-Aufrufer“ zu, damit es die Funktion aufrufen kann.

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

4. Funktion erstellen und bereitstellen

Erstellen Sie zuerst ein Verzeichnis für den Quellcode und wechseln Sie mit „cd“ in dieses Verzeichnis.

mkdir ../$SERVICE_NAME && cd $_

Erstellen Sie dann eine package.json-Datei mit folgendem Inhalt:

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

Erstellen Sie als Nächstes eine index.js-Datei mit folgendem Inhalt:

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}`);
});

Sie können die Cloud Run-Funktion jetzt mit dem folgenden Befehl bereitstellen:

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

Hinweis:

  • Mit dem Flag „–source“ wird Cloud Run angewiesen, die Funktion in einem ausführbaren containerbasierten Dienst zu erstellen.
  • Mit dem Flag „–function“ (neu) wird der Einstiegspunkt des neuen Dienstes auf die Funktionssignatur festgelegt, die aufgerufen werden soll.
  • Optional: „–no-allow-unauthenticated“, um zu verhindern, dass Ihre Funktion öffentlich aufgerufen werden kann

Sie können sich Ihren neuen Dienst crf-nodejs-event mit dem folgenden Befehl ansehen:

gcloud beta run services describe $SERVICE_NAME

5. Ereignis erstellen

Wir können einen Eventarc-Trigger erstellen, um jedes Mal, wenn ein Objekt in Google Cloud Storage fertiggestellt wird, Nachrichten an unsere Funktion zu senden:

BUCKET_REGION=$REGION

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

Hinweis:

  • gcs-function-trigger ist der Name des Triggers.
  • crf-nodejs-event ist der Name des Cloud Run-Dienstes, in dem unsere Funktion bereitgestellt wird.
  • Verwenden Sie für das Flag „–event-filters“ kein gs://-Präfix im Bucket-Namen.

Eine ausführliche Anleitung zum Einrichten eines Trigger-Dienstes aus Cloud Storage mit Eventarc finden Sie in der Cloud Run-Dokumentation unter https://cloud.google.com/run/docs/tutorials/eventarc.

6. Funktion testen

Wenn die Bereitstellung abgeschlossen ist, wird die Dienst-URL angezeigt. Zum Aufrufen der Funktion müssen Sie eine authentifizierte Anfrage mit Ihrem Identitätstoken oder dem Identitätstoken eines Hauptkontos mit der Rolle „Cloud Run Invoker“ senden, wie unten dargestellt:

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

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

Nachdem wir unsere Funktion bereitgestellt und einen Trigger erstellt haben, können wir sie jetzt aufrufen.

Erstellen Sie eine Datei und laden Sie sie in Ihren Cloud Storage-Bucket hoch. Sie können dies über die Weboberfläche der Cloud Console oder mit dem Befehlszeilentool gsutil tun, z.B.

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

Wenn die Datei erfolgreich hochgeladen wurde, wird ein Ereignis generiert und Ihre Funktion druckt einige grundlegende Informationen zum Objekt aus, z.B. den Dateinamen. Sie finden diese Ausgabe in den Logeinträgen für die Funktion in der Cloud Console. Alternativ können Sie diese Ausgabe auch mit der gcloud CLI abfragen:

gcloud logging read "resource.labels.service_name=crf-nodejs-event AND textPayload: File" --format=json 

Sie sollten die folgende Ausgabe sehen:

"textPayload": "File: test.txt"

7. Glückwunsch!

Herzlichen Glückwunsch zum Abschluss des Codelabs!

Weitere Informationen finden Sie in der Dokumentation zu Cloud Run-Functions.

Behandelte Themen

  • Ereignisgesteuerte Cloud Run-Funktion bereitstellen, die ausgelöst wird, wenn ein Objekt in einen GCS-Bucket hochgeladen wird
  • Dienstkonto mit den richtigen Rollen zum Empfangen eines Ereignisses aus Cloud Storage und Aufrufen der Cloud Run-Funktion erstellen

8. Bereinigen

Wenn Sie versehentliche Kosten vermeiden möchten, z. B. wenn dieser Cloud Run-Dienst versehentlich mehrmals aufgerufen wird als Ihre monatliche Cloud Run-Aufrufzuweisung in der kostenlosen Stufe, können Sie entweder den Cloud Run-Dienst oder das in Schritt 2 erstellte Projekt löschen.

Wenn Sie die Cloud Run-Dienste löschen möchten, rufen Sie die Cloud Run-Cloud Console unter https://console.cloud.google.com/run/ auf und löschen Sie den Dienst crf-event-codelab, den Sie in diesem Codelab erstellt haben.

Wenn Sie das gesamte Projekt löschen möchten, rufen Sie https://console.cloud.google.com/cloud-resource-manager auf, wählen Sie das in Schritt 2 erstellte Projekt aus und klicken Sie auf „Löschen“. Wenn Sie das Projekt löschen, müssen Sie die Projekte in Ihrem Cloud SDK ändern. Sie können eine Liste aller verfügbaren Projekte aufrufen, indem Sie gcloud projects list ausführen.