Recevoir des événements à l'aide de messages Pub/Sub (Terraform)

Ce guide de démarrage rapide explique comment utiliser Terraform pour créer un déclencheur Eventarc qui reçoit des événements directs de Pub/Sub et les achemine vers un service Cloud Run. Pour en savoir plus sur l'utilisation de Terraform pour créer des déclencheurs Eventarc, consultez Créer un déclencheur à l'aide de Terraform.

Dans ce guide de démarrage rapide, vous allez :

  1. Préparez-vous à déployer Terraform.

  2. Définissez une configuration Terraform qui effectue les opérations suivantes :

    1. Activer des API
    2. Créez un compte de service et attribuez-lui les rôles IAM (Identity and Access Management) nécessaires.
    3. Déployez un service sur Cloud Run en tant que destination d'événement.
    4. Créez un sujet Pub/Sub en tant que fournisseur d'événements.
    5. Créer un déclencheur Eventarc.
  3. Appliquez votre configuration Terraform.

  4. Publier un message dans un sujet Pub/Sub pour générer un événement et l'afficher dans les journaux Cloud Run.

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

  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. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante :

    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. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  11. Pour initialiser la gcloud CLI, exécutez la commande suivante :

    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. Si vous êtes le créateur du projet, vous disposez du rôle de base Propriétaire (roles/owner). Par défaut, ce rôle Identity and Access Management (IAM) inclut les autorisations nécessaires pour accéder à la plupart des ressources Google Cloud. Vous pouvez ignorer cette étape.

    Si vous n'êtes pas le créateur du projet, les autorisations requises doivent être accordées au compte principal approprié sur le projet. Par exemple, un compte principal peut être un compte Google (pour les utilisateurs finaux) ou un compte de service (pour les applications et les charges de travail de calcul). Pour en savoir plus, consultez la page Rôles et autorisations pour la destination de votre événement.

    Autorisations requises

    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 :

    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 avec des rôles personnalisés ou d'autres rôles prédéfinis.

  17. Préparer le déploiement de Terraform

    Préparez-vous à déployer des ressources Terraform en créant 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. Si vous utilisez un shell local, installez et configurez Terraform.

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

    2. Dans Cloud Shell ou votre shell local, définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform. Vous n'avez besoin d'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 projet Google Cloud .

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

    Préparer le répertoire

    Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine). Créez un répertoire et un nouveau fichier dans ce répertoire :

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

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

    Définir votre configuration Terraform

    Copiez les extraits de code Terraform suivants dans le fichier main.tf que vous venez de créer. Vous pouvez également copier le code depuis GitHub. (En haut à droite de l'extrait de code, cliquez sur > Afficher sur GitHub.)

    Activer les API

    Les exemples Terraform partent généralement du principe que les API requises sont activées dans votre projetGoogle Cloud . Utilisez l'extrait de code suivant pour activer les API nécessaires pour ce guide de démarrage rapide :

    # 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
    }

    Créer un compte de service et configurer son accès

    Chaque déclencheur Eventarc est associé à un compte de service IAM. Pour suivre ce guide de démarrage rapide, vous devez attribuer les rôles IAM suivants à un compte de service géré par l'utilisateur :

    Utilisez l'extrait de code suivant pour créer un compte de service dédié et lui attribuer des rôles IAM spécifiques pour gérer les événements :

    # 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"
    }

    Si vous avez activé l'agent de service Pub/Sub le 8 avril 2021 ou avant cette date, attribuez le rôle de créateur de jetons de compte de service (roles/iam.serviceAccountTokenCreator) à l'agent de service.

    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"
    }

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

    Créez un service Cloud Run en tant que destination d'événement pour le déclencheur Eventarc à l'aide de la ressource Terraform 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]
    }

    Créer un sujet Pub/Sub en tant que fournisseur d'événements

    Créez un sujet Pub/Sub à l'aide de la ressource Terraform google_pubsub_topic :

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

    Créer un déclencheur Eventarc

    Créez un déclencheur Eventarc pour écouter les messages Pub/Sub à l'aide de la ressource Terraform 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_project_iam_member.pubsubpublisher
      ]
    }

    Appliquer Terraform

    Utilisez la CLI Terraform pour provisionner l'infrastructure en fonction du fichier de configuration.

    Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base.

    1. Initialisez Terraform. Cette opération n'est à effectuer 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 les modifications de la configuration si nécessaire.

    3. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité :

      terraform apply

      En général, vous appliquez l'intégralité de la configuration en une seule fois. Cependant, vous pouvez également cibler une ressource spécifique. Exemple :

      terraform apply -target="google_eventarc_trigger.default"

      Après avoir activé les API, il peut s'écouler quelques minutes avant que l'action ne se propage et que vous puissiez déployer d'autres ressources. Si vous rencontrez un problème, réessayez d'appliquer la configuration Terraform.

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

    Vérifier la création des ressources

    1. Vérifiez que le service Cloud Run a été créé :

      gcloud run services list --region us-central1
      

      La sortie devrait ressembler à ce qui suit :

      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. Vérifiez que le déclencheur Eventarc a bien été créé :

      gcloud eventarc triggers list --location us-central1
      

      La sortie devrait ressembler à ce qui suit :

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

    Générer et afficher un événement de type sujet Pub/Sub.

    Vous pouvez générer un événement en publiant un message dans le sujet Pub/Sub. Le déclencheur Eventarc achemine le message vers le service récepteur d'événements déployé sur Cloud Run, et le service consigne le message d'événement.

    1. Recherchez et définissez le sujet Pub/Sub en tant que variable d'environnement :

      gcloud config set eventarc/location us-central1
      export RUN_TOPIC=$(gcloud eventarc triggers describe trigger-pubsub-cloudrun-tf \
          --format='value(transport.pubsub.topic)')
      
    2. Envoyer un message au sujet Pub/Sub pour générer un événement :

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

      L'événement est envoyé au service Cloud Run, qui consigne le message d'événement.

    3. Pour afficher les entrées de journal liées aux événements et créées par votre service, exécutez la commande suivante :

      gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.pubsub.topic.v1.messagePublished"'
      
    4. Recherchez une entrée de journal semblable à ceci :

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

    Vous avez utilisé Terraform pour déployer un service de récepteur d'événements sur Cloud Run et créer un déclencheur Eventarc. Après avoir généré un événement à partir de Pub/Sub, vous pouvez l'afficher dans les journaux Cloud Run.

    Effectuer un nettoyage

    Une fois que vous avez terminé les tâches décrites dans ce guide de démarrage rapide, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées.

    Supprimez les ressources précédemment appliquées à votre configuration Terraform en exécutant la commande suivante et en saisissant yes à la requête :

    terraform destroy

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

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

    Si vous envisagez d'explorer plusieurs tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

    Étapes suivantes