Erste Schritte mit ereignisgesteuerten Cloud Run-Funktionen

1. Einführung

Übersicht

Cloud Run Functions ist eine neue Möglichkeit, Arbeitslasten mit den bekannten GCF-Ereignisparadigmen und Funktionssignaturen bereitzustellen. Anstelle unseres vordefinierten Build-Prozesses und unserer Bereitstellungskonfigurationen haben Sie mit Cloud Run Functions die direkte Kontrolle über den zugrunde liegenden Dienst, der in Cloud Run erstellt wird.

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

In diesem Abschnitt erfahren Sie, wie Sie eine ereignisgesteuerte Funktion in Node bereitstellen. Sie stellen eine Funktion bereit, die immer dann 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 der 2. Generation in der Sprache Ihrer Wahl verwenden:

• Python-Funktionsbeispiele
• Node.js-Funktionsbeispiele
• Go-Funktionsbeispiele
• Java-Funktionsbeispiele
• PHP-Funktionsbeispiele
• Ruby-Funktionsbeispiele
• .NET-Funktionsbeispiele

Lerninhalte

• Bereitstellen einer ereignisgesteuerten Cloud Run-Funktion, die ausgelöst wird, wenn ein Objekt in einen GCS-Bucket hochgeladen wird
• Dienstkonto mit den richtigen Rollen erstellen, um ein Ereignis aus Cloud Storage zu empfangen und die Cloud Run-Funktion aufzurufen

2. Umgebungsvariablen einrichten und APIs aktivieren

gcloud CLI aktualisieren

Für dieses Codelab ist eine aktuelle Version der gcloud CLI erforderlich. Sie können die CLI mit dem folgenden Befehl aktualisieren:

gcloud components update

APIs aktivieren

Bevor Sie mit diesem Codelab beginnen können, müssen Sie mehrere APIs aktivieren. Für dieses Codelab müssen Sie die folgenden APIs verwenden. 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. 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-Aufruferrolle, 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 als Nächstes 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 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}`);
});

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.
• 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

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

gcloud beta run services describe $SERVICE_NAME

5. Ereignis erstellen

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

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

Hinweis:

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

Eine detaillierte Anleitung zum Einrichten des 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 $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

Nachdem wir unsere Funktion bereitgestellt und einen Trigger erstellt haben, können wir die Funktion 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 gsutil-Befehlszeilentool tun, z.B.

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

Wenn die Datei erfolgreich hochgeladen wurde, wird ein Ereignis generiert und Ihre Funktion gibt 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 mit der gcloud CLI abfragen:

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

Es sollte folgende Ausgabe angezeigt werden:

"textPayload": "File: test.txt"

7. Glückwunsch!

Herzlichen Glückwunsch zum Abschluss des Codelabs!

Wir empfehlen, die Dokumentation zu Cloud Run Functions zu lesen.

Behandelte Themen

• Bereitstellen einer ereignisgesteuerten Cloud Run-Funktion, die ausgelöst wird, wenn ein Objekt in einen GCS-Bucket hochgeladen wird
• Dienstkonto mit den richtigen Rollen erstellen, um ein Ereignis aus Cloud Storage zu empfangen und die Cloud Run-Funktion aufzurufen

8. Bereinigen

Damit keine unbeabsichtigten Gebühren anfallen (z. B. wenn dieser Cloud Run-Dienst versehentlich öfter aufgerufen wird als Ihre monatliche Cloud Run-Aufrufkontingent im kostenlosen Kontingent), können Sie entweder den Cloud Run-Dienst oder das Projekt löschen, das Sie in Schritt 2 erstellt haben.

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 Projekt aus, das Sie in Schritt 2 erstellt haben, und klicken Sie auf „Löschen“. Wenn Sie das Projekt löschen, müssen Sie das Projekt in Ihrem Cloud SDK ändern. Sie können die Liste aller verfügbaren Projekte mit gcloud projects list aufrufen.