Ereignisse mit Pub/Sub-Nachrichten empfangen (Terraform)

Ereignisse mit Pub/Sub-Nachrichten empfangen (Terraform)

Standard

In dieser Kurzanleitung erfahren Sie, wie Sie mit Terraform einen Eventarc-Trigger erstellen, der direkte Ereignisse von Pub/Sub empfängt und an einen Cloud Run-Dienst weiterleitet. Weitere Informationen zum Erstellen von Eventarc-Triggern mit Terraform finden Sie unter Trigger mit Terraform erstellen.

In dieser Kurzanleitung führen Sie die folgenden Schritte aus:

1. Bereiten Sie die Bereitstellung von Terraform vor.

2. Definieren Sie eine Terraform-Konfiguration, die Folgendes tut:

   1. APIs aktivieren
   2. Erstellen Sie ein Dienstkonto und gewähren Sie ihm die erforderlichen IAM-Rollen (Identity and Access Management).
   3. Stellen Sie einen Dienst in Cloud Run als Ereignisziel bereit.
   4. Erstellen Sie ein Pub/Sub-Thema als Ereignisanbieter.
   5. Eventarc-Trigger erstellen

3. Wenden Sie Ihre Terraform-Konfiguration an.

4. Eine Nachricht in einem Pub/Sub-Thema veröffentlichen, um ein Ereignis zu generieren und in den Logs von Cloud Run aufzurufen

Vorbereitung

Von Ihrer Organisation definierte Sicherheitsbeschränkungen verhindern möglicherweise, dass die folgenden Schritte ausgeführt werden. Informationen zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud Umgebung entwickeln.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Cloud Resource Manager and IAM APIs:

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

7. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

10. Create or select a Google Cloud project.

    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

11. Make sure that billing is enabled for your Google Cloud project.

12. Enable the Cloud Resource Manager and IAM APIs:

    gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

13. If you're using a local shell, then create local authentication credentials for your user account:

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

14. Wenn Sie der Projektersteller sind, wird Ihnen die einfache Rolle „Inhaber“ (roles/owner) zugewiesen. Standardmäßig enthält diese IAM-Rolle (Identity and Access Management) die Berechtigungen, die für den vollständigen Zugriff auf die meisten Google Cloud-Ressourcen erforderlich sind. Sie können diesen Schritt überspringen.

    Wenn Sie nicht der Project Creator sind, müssen dem entsprechenden Hauptkonto die erforderlichen Berechtigungen für das Projekt erteilt werden. Ein Hauptkonto kann beispielsweise ein Google-Konto (für Endnutzer) oder ein Dienstkonto (für Anwendungen und Computing-Arbeitslasten) sein. Weitere Informationen finden Sie auf der Seite Rollen und Berechtigungen für Ihr Ereignisziel.

    Erforderliche Berechtigungen

    Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Kurzanleitung benötigen:

    • Cloud Run-Administrator (roles/run.admin)
    • Eventarc Admin (roles/eventarc.admin)
    • Zugriffsberechtigter für Logbetrachtung (roles/logging.viewAccessor)
    • Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin)
    • Pub/Sub Publisher (roles/pubsub.publisher)
    • Service Account Admin (roles/iam.serviceAccountAdmin)
    • Service Account User (roles/iam.serviceAccountUser)
    • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Terraform-Bereitstellung vorbereiten

Erstellen Sie eine Terraform-Konfigurationsdatei, um die Bereitstellung von Terraform-Ressourcen vorzubereiten. In einer Terraform-Konfigurationsdatei können Sie den gewünschten Endzustand Ihrer Infrastruktur mithilfe der Terraform-Syntax definieren.

1. Wenn Sie eine lokale Shell verwenden, installieren und konfigurieren Sie Terraform.

   Terraform ist bereits in die Cloud Shell-Umgebung integriert. Sie können Ihre Terraform-Ressourcen also mit Cloud Shell bereitstellen, ohne Terraform installieren zu müssen.

2. Legen Sie in Cloud Shell oder in Ihrer lokalen Shell das Standardprojekt Google Cloud fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten. Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Ersetzen Sie PROJECT_ID durch die ID Ihres Google Cloud -Projekts.

Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.

Verzeichnis vorbereiten

Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet). Erstellen Sie ein Verzeichnis und eine neue Datei in diesem Verzeichnis:

mkdir DIRECTORY && cd DIRECTORY && touch main.tf

Der Dateiname muss die Erweiterung .tf haben. In dieser Kurzanleitung wird die Datei beispielsweise main.tf genannt.

Terraform-Konfiguration definieren

Kopieren Sie die folgenden Terraform-Code-Snippets in die neu erstellte main.tf-Datei. Sie können den Code auch aus GitHub kopieren. Klicken Sie rechts oben im Code-Snippet auf > Auf GitHub ansehen.

APIs aktivieren

Bei Terraform-Beispielen wird in der Regel davon ausgegangen, dass die erforderlichen APIs in IhremGoogle Cloud -Projekt aktiviert sind. Aktivieren Sie mit dem folgenden Code-Snippet die für diese Kurzanleitung erforderlichen APIs:

# Enable Cloud Run API
resource "google_project_service" "run" {
  service            = "run.googleapis.com"
  disable_on_destroy = false
}

# Enable Eventarc API
resource "google_project_service" "eventarc" {
  service            = "eventarc.googleapis.com"
  disable_on_destroy = false
}

# Enable Pub/Sub API
resource "google_project_service" "pubsub" {
  service            = "pubsub.googleapis.com"
  disable_on_destroy = false
}

Dienstkonto erstellen und Zugriff konfigurieren

Jeder Eventarc-Trigger ist mit einem IAM-Dienstkonto verknüpft. Damit Sie diese Kurzanleitung abschließen können, müssen Sie einem nutzerverwalteten Dienstkonto die folgenden IAM-Rollen zuweisen:

• Cloud Run Invoker-Rolle (roles/run.invoker)
• Rolle „Pub/Sub-Publisher“ (roles/pubsub.publisher)

Mit dem folgenden Code-Snippet können Sie ein spezielles Dienstkonto erstellen und ihm bestimmte IAM-Rollen zum Verwalten von Ereignissen zuweisen:

# Used to retrieve project information later
data "google_project" "project" {}

# Create a dedicated service account
resource "google_service_account" "eventarc" {
  account_id   = "eventarc-trigger-sa"
  display_name = "Eventarc trigger service account"
}

# Grant permission to invoke Cloud Run services
resource "google_project_iam_member" "runinvoker" {
  project = data.google_project.project.id
  role    = "roles/run.invoker"
  member  = "serviceAccount:${google_service_account.eventarc.email}"
}

# Grant permission to publish messages to a Pub/Sub topic
resource "google_project_iam_member" "pubsubpublisher" {
  project = data.google_project.project.id
  member  = "serviceAccount:${google_service_account.eventarc.email}"
  role    = "roles/pubsub.publisher"
}

Wenn Sie den Pub/Sub-Dienst-Agent am oder vor dem 8. April 2021 aktiviert haben, weisen Sie dem Dienst-Agent die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) zu.

resource "google_project_iam_member" "tokencreator" {
  project  = data.google_project.project.id
  role     = "roles/iam.serviceAccountTokenCreator"
  member   = "serviceAccount:service-${data.google_project.project.number}@gcp-sa-pubsub.iam.gserviceaccount.com"
}

Ereignisempfänger für Cloud Run bereitstellen

Erstellen Sie mit der Terraform-Ressource google_cloud_run_v2_service einen Cloud Run-Dienst als Ereignisziel für den Eventarc-Trigger:

# Deploy a Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "hello-events"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # This container will log received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

Pub/Sub-Thema als Ereignisanbieter erstellen

Mit der Terraform-Ressource google_pubsub_topic ein Pub/Sub-Thema erstellen:

# Create a Pub/Sub topic
resource "google_pubsub_topic" "default" {
  name = "pubsub_topic"
}

Eventarc-Trigger erstellen

Erstellen Sie mit der Terraform-Ressource google_eventarc_trigger einen Eventarc-Trigger, um Pub/Sub-Nachrichten zu überwachen:

# Create an Eventarc trigger, routing Pub/Sub events to Cloud Run
resource "google_eventarc_trigger" "default" {
  name     = "trigger-pubsub-cloudrun-tf"
  location = google_cloud_run_v2_service.default.location

  # Capture messages published to a Pub/Sub topic
  matching_criteria {
    attribute = "type"
    value     = "google.cloud.pubsub.topic.v1.messagePublished"
  }

  # Send events to Cloud Run
  destination {
    cloud_run_service {
      service = google_cloud_run_v2_service.default.name
      region  = google_cloud_run_v2_service.default.location
    }
  }

  transport {
    pubsub {
      topic = google_pubsub_topic.default.id
    }
  }

  service_account = google_service_account.eventarc.email
  depends_on = [
    google_project_service.eventarc,
    google_project_iam_member.pubsubpublisher
  ]
}

Hinweis: Der Trigger wird zwar sofort erstellt, es kann jedoch bis zu zwei Minuten dauern, bis Trigger vollständig funktionieren.

Terraform anwenden

Verwenden Sie die Terraform-Befehlszeile, um die Infrastruktur basierend auf der Konfigurationsdatei bereitzustellen.

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle.

1. Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich.

   terraform init

   Fügen Sie optional die Option -upgrade ein, um die neueste Google-Anbieterversion zu verwenden:

   terraform init -upgrade

2. Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen:

   terraform plan

   Korrigieren Sie die Konfiguration nach Bedarf.

3. Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein:

   terraform apply

   Normalerweise wenden Sie die gesamte Konfiguration auf einmal an. Sie können die Anzeigen aber auch auf eine bestimmte Ressource ausrichten. Beispiel:

   terraform apply -target="google_eventarc_trigger.default"

   Nachdem Sie die APIs aktiviert haben, kann es einige Minuten dauern, bis die Aktion übernommen wird und Sie weitere Ressourcen bereitstellen können. Sollten Probleme auftreten, versuchen Sie noch einmal, die Terraform-Konfiguration anzuwenden.

   Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.

Erstellung von Ressourcen prüfen

1. Prüfen Sie, ob der Cloud Run-Dienst erstellt wurde:

   gcloud run services list --region us-central1
   

   Die Ausgabe sollte in etwa so aussehen:

   SERVICE: hello-events
   REGION: us-central1
   URL: https://hello-events-13335919645.us-central1.run.app
   LAST DEPLOYED BY: ...
   LAST DEPLOYED AT: 2024-12-16T15:00:52.606160Z
   

2. Prüfen Sie, ob der Eventarc-Trigger erstellt wurde:

   gcloud eventarc triggers list --location us-central1
   

   Die Ausgabe sollte in etwa so aussehen:

   NAME: trigger-pubsub-cloudrun-tf
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: Cloud Run service: hello-events
   ACTIVE: Yes
   LOCATION: us-central1
   

Generieren Sie ein Pub/Sub-Thema und rufen Sie es auf.

Sie können ein Ereignis generieren, indem Sie eine Nachricht im Pub/Sub-Thema veröffentlichen. Der Eventarc-Trigger leitet die Nachricht an den in Cloud Run bereitgestellten Ereignisempfängerdienst weiter, der die Ereignisnachricht protokolliert.

1. Suchen Sie das Pub/Sub-Thema und legen Sie es als Umgebungsvariable fest:

   gcloud config set eventarc/location us-central1
   export RUN_TOPIC=$(gcloud eventarc triggers describe trigger-pubsub-cloudrun-tf \
       --format='value(transport.pubsub.topic)')
   

2. Senden Sie eine Nachricht an das Pub/Sub-Thema, um ein Ereignis zu generieren:

   gcloud pubsub topics publish $RUN_TOPIC --message "Hello World!"
   

   Das Ereignis wird an den Cloud Run-Dienst gesendet, der die Ereignisnachricht loggt.

3. Führen Sie den folgenden Befehl aus, um die von Ihrem Dienst erstellten ereignisbezogenen Logeinträge aufzurufen:

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.pubsub.topic.v1.messagePublished"'
   

4. Suchen Sie nach einem Logeintrag wie dem folgenden:

   jsonPayload:
   ...
   message: 'Received event of type google.cloud.pubsub.topic.v1.messagePublished.
       Event data: Hello World!'
   

   Hinweis: Wenn kein Logeintrag angezeigt wird, warten Sie einige Minuten und führen dann den Befehl gcloud logging read noch einmal aus. Nach dem Erstellen eines Triggers kann es bis zu zwei Minuten dauern, bis Ereignisse gefiltert werden können.

Sie haben mit Terraform einen Ereignisempfängerdienst in Cloud Run bereitgestellt und einen Eventarc-Trigger erstellt. Nachdem Sie ein Ereignis über Pub/Sub generiert haben, können Sie es in den Cloud Run-Logs aufrufen.

Bereinigen

Nach Abschluss der in dieser Kurzanleitung beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen.

Entfernen Sie Ressourcen, die zuvor mit Ihrer Terraform-Konfiguration angewendet wurden, indem Sie den folgenden Befehl ausführen und yes an der Eingabeaufforderung eingeben:

terraform destroy

Alternativ können Sie Ihr Google Cloud -Projekt löschen, um wiederkehrende Gebühren zu vermeiden. Wenn Sie Ihr Google Cloud -Projekt löschen, wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beendet.

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:

• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Wenn Sie mehrere Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

Nächste Schritte

• Dienste für Cloud Run entwickeln
• Dokumentation zu Terraform in Google Cloud