Publier et recevoir des événements en créant un bus et un enregistrement (Terraform)

Publier et recevoir des événements en créant un bus et un enregistrement (Terraform)

Advanced

Ce guide de démarrage rapide vous explique comment utiliser Terraform pour créer un bus et un enregistrement Eventarc Advanced dans votre Google Cloud projet afin de pouvoir publier et recevoir des messages d'événement.

• Un bus sert de routeur central, recevant des messages provenant de sources d'événements ou publiés par des fournisseurs.

• Un enregistrement achemine les messages reçus par le bus vers une ou plusieurs destinations via un pipeline de traitement.

Dans le cadre de ce guide démarrage rapide, vous allez effectuer les étapes suivantes :

1. Déployer un service récepteur d'événements sur Cloud Run.

2. Créer un bus Eventarc Advanced.

3. Activer les événements provenant de sources Google.

4. Créer un pipeline et un enregistrement Eventarc Advanced.

5. Publier un message d'événement sur le bus en créant un workflow.

6. Afficher les données d'événement dans les journaux Cloud Run.

Vous pouvez effectuer la plupart des étapes de ce guide de démarrage rapide à l'aide de Terraform. Pour effectuer toutes les étapes à l'aide de Google Cloud CLI, consultez Publier des événements à partir d'une source Google.

Pour en savoir plus sur l'utilisation de Terraform, consultez la documentation Terraform on Google Cloud.

Avant de commencer

Les contraintes de sécurité définies par votre organisation peuvent vous empêcher d'effectuer les étapes suivantes. Pour en savoir plus sur la résolution des problèmes, consultez Développer des applications dans un environnement Google Cloud limité.

Connectez-vous à votre Google Cloud compte. Si vous n'avez jamais utilisé Google Cloud, créez un compte pour évaluer les performances de nos produits dans des scénarios réels. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. Dans la Google Cloud console, activez Cloud Shell.

   Activer Cloud Shell

   En bas de la fenêtre de la console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Google Cloud Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

Terraform est intégré à l'environnement Cloud Shell. Vous pouvez donc utiliser Cloud Shell pour déployer vos ressources Terraform sans avoir à installer Terraform.

Rôles requis

Pour obtenir les autorisations nécessaires pour suivre ce guide de démarrage rapide, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

• Administrateur Cloud Run (roles/run.admin)
• Développeur Eventarc (roles/eventarc.developer)
• Administrateur de bus de messages Eventarc (roles/eventarc.messageBusAdmin)
• Accesseur de vues de journaux (roles/logging.viewAccessor)
• Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)
• Administrateur de compte de service (roles/iam.serviceAccountAdmin)
• Utilisateur du compte de service (roles/iam.serviceAccountUser)
• Éditeur de workflows (roles/workflows.editor)

Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Se préparer à déployer Terraform

Avant de déployer des ressources Terraform, vous devez créer un fichier de configuration Terraform. Un fichier de configuration Terraform vous permet de définir l'état final souhaité pour votre infrastructure à l'aide de la syntaxe Terraform.

1. Dans Cloud Shell, définissez le projet par défaut Google Cloud dans lequel vous souhaitez appliquer votre configuration Terraform. Vous ne devez exécuter cette commande qu'une seule fois par projet, et vous pouvez l'exécuter dans n'importe quel répertoire :

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Remplacez PROJECT_ID par l'ID de votre Google Cloud projet.

   Notez que les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

2. Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine). Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire :

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

   Remplacez DIRECTORY par le nom de votre répertoire Terraform.

   Le nom du fichier doit comporter l'extension .tf. Par exemple, dans ce guide de démarrage rapide, le fichier de configuration est main.tf.

Définir votre configuration Terraform

Copiez les extraits de code Terraform suivants dans votre fichier main.tf. Pour copier l'exemple de code complet à partir de GitHub, en haut à droite d'un extrait de code, cliquez sur > Afficher sur GitHub.

Activer les API

Utilisez la google_project_service ressource Terraform pour activer les API requises afin d'appliquer la configuration Terraform :

# Enable APIs
resource "google_project_service" "apis" {
  for_each = toset([
    "eventarc.googleapis.com",
    "eventarcpublishing.googleapis.com",
    "run.googleapis.com"
  ])
  service            = each.key
  disable_on_destroy = false
}

Créer un compte de service

À des fins de test, créez un compte de service dédié et accordez-lui des rôles IAM spécifiques.

Utilisez les google_service_account et google_project_iam_member ressources Terraform pour créer le compte de service et lui accorder les rôles nécessaires pour publier et recevoir des événements :

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

# Create a dedicated service account
resource "google_service_account" "default" {
  account_id   = "eventarc-advanced-sa"
  display_name = "Eventarc Advanced quickstart service account"
}

# Grant permission to receive Eventarc events
resource "google_project_iam_member" "eventreceiver" {
  project = data.google_project.project.id
  role    = "roles/eventarc.eventReceiver"
  member  = "serviceAccount:${google_service_account.default.email}"
}

# 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.default.email}"
}

Créer une destination d'événement

Utilisez la google_cloud_run_v2_service ressource Terraform pour créer un service Cloud Run en tant que destination d'événement qui enregistre le contenu d'un événement :

# Deploy Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "example-service"
  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.default.email
  }

  depends_on = [google_project_service.apis]
}

Créer un bus Eventarc Advanced

Un bus reçoit des messages d'événement d'une source de messages ou publiés par un fournisseur, et sert de routeur de messages. Pour en savoir plus, consultez Créer un bus pour router les messages.

Remarque : Vous pouvez créer un bus par Google Cloud projet et par région compatible.

Utilisez la google_eventarc_message_bus ressource Terraform pour créer un bus Eventarc Advanced :

# Create an Eventarc Advanced bus
resource "google_eventarc_message_bus" "default" {
  location       = "us-central1"
  message_bus_id = "example-bus"
}

Activer les événements provenant de sources Google

Pour publier des événements à partir de sources Google, vous devez créer une GoogleApiSource ressource qui représente un abonnement aux événements de l'API Google pour un bus Eventarc Advanced spécifique. Pour en savoir plus, consultez Publier des événements à partir de sources Google.

Remarque : Vous pouvez créer une ressource GoogleApiSource par Google Cloud projet et par région compatible.

Utilisez la google_eventarc_google_api_source ressource Terraform pour activer les événements provenant de sources Google :

# Enable events from Google API sources
resource "google_eventarc_google_api_source" "default" {
  location             = "us-central1"
  google_api_source_id = "example-google-api-source"
  destination          = google_eventarc_message_bus.default.id
}

Tous les types d'événements Google compatibles envoyés directement à partir d'une source Google sont désormais collectés et publiés sur votre bus.

Créer un pipeline Eventarc Advanced

Un pipeline vous permet de configurer une destination cible et vous offre également la possibilité de transformer les événements correspondants avant de les distribuer à la destination.

Utilisez la google_eventarc_pipeline ressource Terraform pour créer un pipeline :

# Create an Eventarc Advanced pipeline
resource "google_eventarc_pipeline" "default" {
  location    = "us-central1"
  pipeline_id = "example-pipeline"
  destinations {
    http_endpoint {
      uri = google_cloud_run_v2_service.default.uri
    }
    authentication_config {
      google_oidc {
        service_account = google_service_account.default.email
      }
    }
  }
}

La destination de l'événement est l'URL complète de votre service Cloud Run , par exemple https://SERVICE_NAME-abcdef-uc.a.run.app. L'adresse e-mail du compte de service est utilisée pour générer un jeton OIDC.

Remarque : La création d'un pipeline peut prendre plusieurs minutes.

Créer un enregistrement Eventarc Advanced

Un enregistrement détermine les messages qui sont acheminés vers une destination et spécifie également le pipeline utilisé pour configurer une destination pour les messages d'événement. Pour en savoir plus, consultez Créer un enregistrement pour recevoir des événements.

Utilisez la ressource google_eventarc_enrollment Terraform pour créer un enregistrement :

# Create an Eventarc Advanced enrollment
resource "google_eventarc_enrollment" "default" {
  location      = "us-central1"
  enrollment_id = "example-enrollment"
  message_bus   = google_eventarc_message_bus.default.id
  destination   = google_eventarc_pipeline.default.id
  cel_match     = "message.type == 'google.cloud.workflows.workflow.v1.created'"
}

L'expression de correspondance pour l'enregistrement utilise le langage CEL (Common Expression Language) pour publier des messages d'événement chaque fois qu'un workflow est créé. À l'étape suivante, vous allez créer un workflow.

Appliquer la configuration Terraform

Utilisez la CLI Terraform pour provisionner l'infrastructure en fonction du fichier de configuration. Pour en savoir plus, consultez Commandes Terraform de base.

1. Initialisez Terraform. Vous ne devez effectuer cette opération qu'une seule fois par répertoire.

   terraform init

   Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade :

   terraform init -upgrade

2. Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes :

   terraform plan

   Corrigez la configuration si nécessaire.

3. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes à l'invite :

   terraform apply

   En règle générale, vous appliquez l'ensemble de la configuration en une seule fois. Toutefois, vous pouvez également cibler une ressource spécifique. Exemple :

   terraform apply -target="google_eventarc_message_bus.default"

   Attendez que Terraform affiche le message "Apply completed!" (Application terminée).

Publier un message d'événement sur le bus en créant un workflow

Workflows est une plate-forme d'orchestration entièrement gérée qui exécute des services dans un ordre que vous définissez : un workflow. Créez un workflow pour générer un type d'événement compatible à partir d'une source Google.

1. Dans votre répertoire d'accueil, créez un fichier appelé myWorkflow.yaml.

2. Copiez le workflow suivant et collez-le dans le nouveau fichier, puis enregistrez-le :

   main:
       params: [input]
       steps:
       - checkSearchTermInInput:
           switch:
               - condition: '${"searchTerm" in input}'
                 assign:
                   - searchTerm: '${input.searchTerm}'
                 next: readWikipedia
       - getLocation:
           call: sys.get_env
           args:
               name: GOOGLE_CLOUD_LOCATION
           result: location
       - setFromCallResult:
           assign:
               - searchTerm: '${text.split(location, "-")[0]}'
       - readWikipedia:
           call: http.get
           args:
               url: 'https://en.wikipedia.org/w/api.php'
               query:
                   action: opensearch
                   search: '${searchTerm}'
           result: wikiResult
       - returnOutput:
               return: '${wikiResult.body[1]}'
   

   Ce workflow transmet la région dans laquelle le workflow est déployé à l' API Wikipédia et renvoie une liste d' articles Wikipédia associés.

3. Déployez le workflow à l'aide de la gcloud workflows deploy commande :

   gcloud workflows deploy example-workflow --source=myWorkflow.yaml \
       --service-account=eventarc-advanced-sa@PROJECT_ID.iam.gserviceaccount.com \
       --location=us-central1

Afficher les données d'événement dans les journaux Cloud Run

Après avoir publié un événement sur votre bus Eventarc Advanced, vous pouvez consulter les journaux de votre service Cloud Run pour vérifier que l'événement a été reçu comme prévu.

1. Filtrez les entrées de journal créées par votre service :

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.workflows.workflow.v1.created."'
   

2. Recherchez une entrée de journal semblable à ceci :

   message: 'Received event of type google.cloud.workflows.workflow.v1.created.
   Event data: {"@type":"type.googleapis.com/google.events.cloud.workflows.v1.WorkflowEventData","payload":{"name":"projects/PROJECT_ID/locations/us-central1/workflows/example-workflow","state":"ACTIVE"...
   

Remarque : Si aucune entrée de journal ne s'affiche, patientez quelques minutes, puis réessayez la commande gcloud logging read.

Vous avez créé un bus et un enregistrement Eventarc Advanced, activé la publication d'événements à partir de sources Google, créé un workflow pour générer un type d'événement compatible à partir d'un fournisseur Google, puis vérifié le résultat attendu dans les journaux du service récepteur d'événements.

Libérer de l'espace

Supprimez les ressources précédemment appliquées à votre configuration Terraform en exécutant la commande suivante et en saisissant yes à l'invite :

terraform destroy

Vous pouvez également supprimer votre Google Cloud projet pour éviter des frais. La suppression de votre Google Cloud projet arrête la facturation de toutes les ressources utilisées dans ce projet.

Attention : La suppression d'un projet a les effets suivants :
• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID du projet, telle qu'une appspot.com URL, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.
1. Dans la Google Cloud console, accédez à la page Gérer les ressources.

   Accéder à la page "Gérer les ressources"

2. Dans la liste des projets, sélectionnez celui que vous souhaitez supprimer, puis cliquez sur Supprimer.
3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez Arrêter pour supprimer le projet.

Étape suivante

• Publier des événements directement
• Transformer les événements reçus
• Mettre en forme les événements reçus