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 die Ereignisse 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 ausführt:

   1. APIs aktivieren
   2. Erstellen Sie ein Dienstkonto.
   3. Erstellen Sie ein Pub/Sub-Thema als Ereignisanbieter.
   4. Stellen Sie einen Dienst in Cloud Run als Ereignisziel bereit.
   5. Eventarc-Trigger erstellen

3. Wenden Sie Ihre Terraform-Konfiguration an.

So können Sie 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 Dienst protokolliert die Ereignisnachricht und bietet so ein einfaches Beispiel für eine ereignisgesteuerte Architektur.

Hinweis

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.

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

• So erstellen Sie ein Google Cloud -Projekt:

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die Cloud Resource Manager API und die Identity and Access Management (IAM) API:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

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

Wenn Sie eine lokale Shell verwenden, erstellen Sie lokale Anmeldedaten zur Authentifizierung für Ihr Nutzerkonto:

gcloud auth application-default login

Wenn Sie Cloud Shell verwenden, müssen Sie das nicht tun.

Wenn ein Authentifizierungsfehler zurückgegeben wird und Sie einen externen Identitätsanbieter (IdP) verwenden, prüfen Sie, ob Sie sich mit Ihrer föderierten Identität in der gcloud CLI angemeldet haben.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

• So erstellen Sie ein Google Cloud -Projekt:

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die Cloud Resource Manager API und die Identity and Access Management (IAM) API:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

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

Wenn Sie eine lokale Shell verwenden, erstellen Sie lokale Anmeldedaten zur Authentifizierung für Ihr Nutzerkonto:

gcloud auth application-default login

Wenn Sie Cloud Shell verwenden, müssen Sie das nicht tun.

Wenn ein Authentifizierungsfehler zurückgegeben wird und Sie einen externen Identitätsanbieter (IdP) verwenden, prüfen Sie, ob Sie sich mit Ihrer föderierten Identität in der gcloud CLI angemeldet haben.

1. Wenn Sie für diese Anleitung ein vorhandenes Projekt verwenden, prüfen Sie, ob Sie die erforderlichen Berechtigungen haben. Wenn Sie ein neues Projekt erstellt haben, haben Sie bereits die erforderlichen Berechtigungen.

   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)

   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

Bevor Sie Terraform-Ressourcen bereitstellen, müssen Sie eine Terraform-Konfigurationsdatei erstellen. Mit einer Terraform-Konfigurationsdatei können Sie den bevorzugten Endzustand für Ihre Infrastruktur mit der Terraform-Syntax definieren.

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

   Terraform ist bereits in die Cloud Shell-Umgebung integriert. Sie können Cloud Shell verwenden, um Ihre Terraform-Ressourcen bereitzustellen, 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-Konfiguration anwenden möchten. Sie müssen diesen Befehl nur einmal pro Projekt und in einem beliebigen Verzeichnis ausführen:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

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

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

   Ersetzen Sie DIRECTORY durch den Namen Ihres Terraform-Verzeichnisses.

   Der Dateiname muss die Erweiterung .tf haben. In diesem Schnellstart ist die Konfigurationsdatei beispielsweise main.tf.

Terraform-Konfiguration definieren

Kopieren Sie die folgenden Terraform-Code-Snippets in Ihre main.tf-Datei. Wenn Sie das gesamte Codebeispiel aus GitHub kopieren möchten, klicken Sie rechts oben in einem Code-Snippet auf > Auf GitHub ansehen.

APIs aktivieren

Aktivieren Sie die APIs, die zum Anwenden der Terraform-Konfiguration erforderlich sind, mit der Terraform-Ressource google_project_service:

# 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

Jeder Eventarc-Trigger ist mit einem IAM-Dienstkonto verknüpft. Wenn Sie ein dediziertes Dienstkonto für Testzwecke erstellen möchten, verwenden Sie die Terraform-Ressource google_service_account:

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

Wenn Sie den Pub/Sub-Dienst-Agent am oder vor dem 8. April 2021 aktiviert haben, weisen Sie ihm 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"
}

Pub/Sub-Thema als Ereignisanbieter erstellen

Verwenden Sie zum Erstellen eines Pub/Sub-Themas die Terraform-Ressource google_pubsub_topic. Wenn Sie Ihrem Dienstkonto die Rolle Pub/Sub Publisher (roles/pubsub.publisher) auf Themenebene zuweisen möchten, verwenden Sie die Terraform-Ressource google_pubsub_topic_iam_member:

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

# Grant permission to publish messages to a Pub/Sub topic
resource "google_pubsub_topic_iam_member" "pubsubpublisher" {
  project    = google_pubsub_topic.default.project
  topic      = google_pubsub_topic.default.name
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  role       = "roles/pubsub.publisher"
  depends_on = [google_pubsub_topic.default]
}

Ereignisempfänger für Cloud Run bereitstellen

Verwenden Sie zum Erstellen eines Cloud Run-Dienstes als Ereignisziel die Terraform-Ressource google_cloud_run_v2_service. Wenn Sie Ihrem Dienstkonto die Rolle Cloud Run Invoker (roles/run.invoker) auf Dienstebene zuweisen möchten, verwenden Sie die Terraform-Ressource google_cloud_run_v2_service_iam_member:

# 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 sample container listens to HTTP requests and logs received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

# Grant permission to invoke Cloud Run services
resource "google_cloud_run_v2_service_iam_member" "runinvoker" {
  project    = google_cloud_run_v2_service.default.project
  location   = google_cloud_run_v2_service.default.location
  name       = google_cloud_run_v2_service.default.name
  role       = "roles/run.invoker"
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  depends_on = [google_cloud_run_v2_service.default]
}

Eventarc-Trigger erstellen

Verwenden Sie zum Erstellen eines Eventarc-Triggers, der auf Pub/Sub-Nachrichten wartet, die Terraform-Ressource google_eventarc_trigger:

# 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_pubsub_topic_iam_member.pubsubpublisher
  ]
}

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

Wenden Sie die Terraform-Konfiguration an:

Verwenden Sie die Terraform-Befehlszeile, um Infrastruktur basierend auf der Konfigurationsdatei bereitzustellen. Weitere Informationen finden Sie unter Grundlegende Terraform-Befehle.

1. Initialisieren Sie Terraform. Dies ist nur einmal pro 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 jedoch auch eine bestimmte Ressource als Ziel festlegen. Beispiel:

   terraform apply -target="google_eventarc_trigger.default"

   Nachdem Sie die APIs aktiviert haben, kann es einige Minuten dauern, bis die Aktion übernommen wird, bevor Sie weitere Ressourcen bereitstellen können. Sollte ein Problem auftreten, versuchen Sie, die Terraform-Konfiguration noch einmal 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 und der Dienst loggt die Ereignisnachricht.

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. Um ein Ereignis zu generieren, veröffentlichen Sie eine Nachricht im Pub/Sub-Thema:

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

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

3. So filtern Sie die von Ihrem Dienst erstellten Logeinträge:

   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 Sie den Befehl gcloud logging read noch einmal aus.

Sie haben Terraform erfolgreich verwendet, um einen Ereignisempfängerdienst in Cloud Run bereitzustellen und einen Eventarc-Trigger zu erstellen. Nachdem Sie ein Ereignis über Pub/Sub generiert haben, können Sie es in den Cloud Run-Logs ansehen.

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. Durch das Löschen des Google Cloud -Projekts 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, zum Beispiel eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, anstatt das gesamte Projekt.

Google Cloud -Projekt löschen:

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 Google Cloud