Ereignisse mit Pub/Sub-Nachrichten empfangen (Terraform)

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 und weisen Sie ihm die erforderlichen IAM-Rollen (Identity and Access Management) zu.
    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. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

    gcloud init

  5. Create or select a Google Cloud 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.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Cloud Resource Manager and IAM APIs: 

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

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

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  9. Install the Google Cloud CLI.

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

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

    gcloud init

  12. Create or select a Google Cloud 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.

  13. Verify that billing is enabled for your Google Cloud project.

  14. Enable the Cloud Resource Manager and IAM APIs: 

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

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

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  16. Wenn Sie der Projektersteller sind, wird Ihnen die einfache Owner-Rolle (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 dieser Kurzanleitung benötigen:

    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.

    17. Terraform-Bereitstellung vorbereiten

    Bereiten Sie die Bereitstellung von Terraform-Ressourcen vor, indem 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 und konfigurieren 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-Konfigurationen 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. Google Cloud

    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 als main.tf bezeichnet.

    Terraform-Konfiguration definieren

    Kopieren Sie die folgenden Terraform-Code-Snippets in die neu erstellte main.tf-Datei. Optional können Sie den Code aus GitHub kopieren. Klicken Sie dazu 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. Verwenden Sie das folgende Code-Snippet, um die für diese Kurzanleitung erforderlichen APIs zu aktivieren:

    # 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 durcharbeiten können, müssen Sie einem vom Nutzer verwalteten Dienstkonto die folgenden IAM-Rollen zuweisen:

    Mit dem folgenden Code-Snippet können Sie ein dediziertes 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 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"
}

    Ereignisempfänger für Cloud Run bereitstellen

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

    # 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

    Erstellen Sie ein Pub/Sub-Thema mit der Terraform-Ressource google_pubsub_topic:

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

    Eventarc-Trigger erstellen

    Erstellen Sie einen Eventarc-Trigger, um Pub/Sub-Nachrichten mit der Terraform-Ressource google_eventarc_trigger 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
  ]
}

    Terraform anwenden

    Verwenden Sie die Terraform-Befehlszeile, um 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 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 und 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 in einem 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. 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!'

    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.

    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