Erste Schritte mit ereignisgesteuerten Cloud Run-Funktionen

1. Einführung

Übersicht

Cloud Run-Funktionen bieten eine neue Möglichkeit, Arbeitslasten mit den bekannten GCF-Ereignismodellen und der Funktionssignatur bereitzustellen. Anstatt unsere speziellen Build-Prozess- und Bereitstellungskonfigurationen zu verwenden, geben Ihnen Cloud Run-Funktionen direkte Kontrolle über den zugrunde liegenden Dienst, der in Cloud Run erstellt wird.

Cloud Run-Funktionen ermöglichen die einfache Bereitstellung von Cloud Run-Quellen, sodass Entwicklerinnen und Entwickler mithilfe von Cloud Run-Konfigurationen die volle Kontrolle über ihre Arbeitslasten haben.

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 Beispielen unten Node.js-Beispiele verwendet. Sie können jedoch die Codebeispiele für Cloud Functions (2nd gen) in der Sprache Ihrer Wahl verwenden:

• Python-Funktionsbeispiele
• Nodejs-Funktionsbeispiele
• Go-Funktionsbeispiele
• Java-Funktionsbeispiele
• PHP-Funktionsbeispiele
• Ruby-Funktionsbeispiele
• .NET-Funktionsbeispiele

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 erstellen, um ein Ereignis von Cloud Storage zu empfangen und die Cloud Run-Funktion aufzurufen

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 aktualisieren, indem Sie den folgenden Befehl ausführen:

gcloud components update

APIs aktivieren

Bevor Sie dieses Codelab verwenden können, müssen Sie mehrere APIs aktivieren. Für dieses Codelab müssen die folgenden APIs verwendet werden. Sie können diese APIs aktivieren, indem Sie den folgenden Befehl ausführen:

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. Storage-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 Cloud Run-Aufrufer-Rolle, um ein Ereignis von 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"

Als Nächstes weisen Sie dem Dienstkonto, das mit Ihrem Eventarc-Trigger verknüpft ist, die Rolle „Eventarc Event Receiver“ (roles/eventarc.eventReceiver) für das Projekt zu, damit der Trigger Ereignisse von Ereignisanbietern 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 zunächst ein Verzeichnis für den Quellcode und speichern Sie das Verzeichnis mit cd.

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

Jetzt können Sie die Cloud Run-Funktion 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.
• Das Flag -function (new) wird verwendet, um den Einstiegspunkt des neuen Dienstes als Funktionssignatur festzulegen, die aufgerufen werden soll
• (optional) „-no-allow-unauthenticated“, um zu verhindern, dass Ihre Funktion öffentlich aufgerufen werden kann

Sie können den neuen Dienst crf-nodejs-event mit dem folgenden Befehl aufrufen:

gcloud beta run services describe $SERVICE_NAME

5. Ereignis erstellen

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

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 die Funktion bereitgestellt wird
• Verwenden Sie für das Flag –event-filters im Bucket-Namen nicht das Präfix gs://.

Eine ausführliche Anleitung zum Einrichten eines Trigger-Dienstes in Cloud Storage mithilfe von 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 Prinzips senden, das die Rolle „Cloud Run Invoker“ hat, wie unten gezeigt:

# 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 die Funktion bereitgestellt und ein Trigger erstellt wurde, können Sie die Funktion aufrufen.

Erstellen Sie eine Datei und laden Sie sie in Ihren Cloud Storage-Bucket hoch. Sie können dazu die Weboberfläche der Cloud Console oder das gsutil-CLI-Tool verwenden, 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 gibt einige grundlegende Informationen über das 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 über die 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-Funktionen.

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 erstellen, um ein Ereignis von Cloud Storage zu empfangen und die Cloud Run-Funktion aufzurufen

8. Bereinigen

Um versehentliche Gebühren zu vermeiden, z. B. wenn diese Cloud Run-Dienstleistung versehentlich mehr Mal aufgerufen wird als Ihre monatliche Zuweisung von Cloud Run-Aufrufen 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 crf-event-codelab-Dienst, 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 die Liste aller verfügbaren Projekte mit dem Befehl gcloud projects list aufrufen.