Recibir eventos mediante mensajes de Pub/Sub (Terraform)

Recibir eventos mediante mensajes de Pub/Sub (Terraform)

Estándar

En esta guía de inicio rápido se muestra cómo usar Terraform para crear un activador de Eventarc que reciba eventos directos de Pub/Sub y que dirija los eventos a un servicio de Cloud Run. Para obtener más información sobre cómo usar Terraform para crear activadores de Eventarc, consulta el artículo Crear un activador con Terraform.

En esta guía de inicio rápido, harás lo siguiente:

1. Prepárate para desplegar Terraform.

2. Define una configuración de Terraform que haga lo siguiente:

   1. Habilita las APIs.
   2. Crea una cuenta de servicio y concédele los roles de Gestión de Identidades y Accesos (IAM) necesarios.
   3. Despliega un servicio en Cloud Run como destino de eventos.
   4. Crea un tema de Pub/Sub como proveedor de eventos.
   5. Crea un activador de Eventarc.

3. Aplica la configuración de Terraform.

4. Publica un mensaje en un tema de Pub/Sub para generar un evento y verlo en los registros de Cloud Run.

Antes de empezar

Es posible que las restricciones de seguridad definidas por tu organización te impidan completar los siguientes pasos. Para obtener información sobre cómo solucionar problemas, consulta el artículo Desarrollar aplicaciones en un entorno limitado Google Cloud .

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.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select 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 (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.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and IAM APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

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.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select 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 (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.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and IAM APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

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.

1. Si has creado el proyecto, se te asignará el rol básico Propietario (roles/owner). De forma predeterminada, este rol de gestión de identidades y accesos (IAM) incluye los permisos necesarios para acceder por completo a la mayoría de los recursos Google Cloud, por lo que puedes saltarte este paso.

   Si no eres el creador del proyecto, debes conceder los permisos necesarios al principal correspondiente. Por ejemplo, una entidad principal puede ser una cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de computación). Para obtener más información, consulta la página Roles y permisos de tu destino de evento.

   Permisos obligatorios

   Para obtener los permisos que necesitas para completar esta guía de inicio rápido, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

   • Administrador de Cloud Run (roles/run.admin)
   • Administrador de Eventarc (roles/eventarc.admin)
   • Usuario con permiso para ver registros (roles/logging.viewAccessor)
   • Administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin)
   • Editor de Pub/Sub (roles/pubsub.publisher)
   • Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin)
   • Usuario de cuenta de servicio (roles/iam.serviceAccountUser)
   • Administrador de Uso de Servicio (roles/serviceusage.serviceUsageAdmin)

   Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

   También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Prepararse para desplegar Terraform

Prepara el despliegue de recursos de Terraform creando un archivo de configuración de Terraform. Un archivo de configuración de Terraform te permite definir el estado final que prefieras para tu infraestructura mediante la sintaxis de Terraform.

1. Si usas un shell local, instala y configura Terraform.

   Terraform ya está integrado en el entorno de Cloud Shell y puedes usar Cloud Shell para desplegar tus recursos de Terraform sin tener que instalar Terraform.

2. En Cloud Shell o en tu shell local, define el proyecto Google Cloud predeterminado en el que quieras aplicar las configuraciones de Terraform. Solo tienes que ejecutar este comando una vez por proyecto y puedes hacerlo en cualquier directorio:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Sustituye PROJECT_ID por el ID de tu Google Cloud proyecto.

Ten en cuenta que las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz). Crea un directorio y un archivo en él:

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

El nombre del archivo debe tener la extensión .tf. Por ejemplo, en esta guía de inicio rápido, el archivo se denomina main.tf.

Definir la configuración de Terraform

Copia los siguientes fragmentos de código de Terraform en el archivo main.tf que acabas de crear. También puedes copiar el código de GitHub. En la esquina superior derecha del fragmento de código, haz clic en > Ver en GitHub.

Habilitar APIs

Los ejemplos de Terraform suelen presuponer que las APIs necesarias están habilitadas en tuGoogle Cloud proyecto. Usa el siguiente fragmento de código para habilitar las APIs necesarias para esta guía de inicio rápido:

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

Crear una cuenta de servicio y configurar su acceso

Cada activador de Eventarc está asociado a una cuenta de servicio de IAM. Para completar esta guía de inicio rápido, debes conceder los siguientes roles de gestión de identidades y accesos a una cuenta de servicio gestionada por el usuario:

• Rol de invocador de Cloud Run (roles/run.invoker)
• Rol de editor de Pub/Sub (roles/pubsub.publisher)

Usa el siguiente fragmento de código para crear una cuenta de servicio específica y asignarle roles de gestión de identidades y accesos concretos para gestionar eventos:

# 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 habilitaste el agente de servicio de Pub/Sub el 8 de abril del 2021 o antes, asigna el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio.

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

Desplegar un receptor de eventos en Cloud Run

Crea un servicio de Cloud Run como destino de eventos del activador de Eventarc mediante el recurso de 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]
}

Crear un tema de Pub/Sub como proveedor de eventos

Crea un tema de Pub/Sub con el recurso de Terraform google_pubsub_topic:

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

Crear un activador de Eventarc

Crea un activador de Eventarc para escuchar mensajes de Pub/Sub con el recurso de 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
  ]
}

Nota: Aunque el activador se crea inmediatamente, puede tardar hasta dos minutos en estar totalmente operativo.

Aplicar Terraform

Usa la CLI de Terraform para aprovisionar la infraestructura en función del archivo de configuración.

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de Terraform.

1. Inicializa Terraform. Solo tienes que hacerlo una vez por directorio.

   terraform init

   Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade:

   terraform init -upgrade

2. Revisa la configuración y comprueba que los recursos que Terraform va a crear o actualizar se ajustan a tus expectativas:

   terraform plan

   Haga las correcciones necesarias en la configuración.

3. Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición:

   terraform apply

   Normalmente, se aplica toda la configuración a la vez. Sin embargo, también puedes orientar a un recurso específico. Por ejemplo:

   terraform apply -target="google_eventarc_trigger.default"

   Después de habilitar las APIs, la acción puede tardar unos minutos en propagarse y en que puedas implementar más recursos. Si tienes algún problema, prueba a aplicar de nuevo la configuración de Terraform.

   Espera hasta que Terraform muestre el mensaje "Apply complete!".

Verificar la creación de recursos

1. Comprueba que se haya creado el servicio de Cloud Run:

   gcloud run services list --region us-central1
   

   La salida debería ser similar a la siguiente:

   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. Confirma que se ha creado el activador de Eventarc:

   gcloud eventarc triggers list --location us-central1
   

   La salida debería ser similar a la siguiente:

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

Generar y ver un evento de tema de Pub/Sub

Puedes generar un evento publicando un mensaje en el tema de Pub/Sub. El activador de Eventarc enruta el mensaje al servicio receptor de eventos desplegado en Cloud Run y el servicio registra el mensaje de evento.

1. Busca y define el tema de Pub/Sub como variable de entorno:

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

2. Publica un mensaje en el tema de Pub/Sub para generar un evento:

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

   El evento se enruta al servicio de Cloud Run, que registra el mensaje del evento.

3. Para ver las entradas de registro relacionadas con eventos creadas por tu servicio, ejecuta el siguiente comando:

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

4. Busca una entrada de registro similar a la siguiente:

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

   Nota: Si no ves ninguna entrada de registro, espera unos minutos y vuelve a ejecutar el comando gcloud logging read. El activador puede tardar hasta dos minutos en empezar a filtrar eventos después de crearse.

Has usado correctamente Terraform para desplegar un servicio de receptor de eventos en Cloud Run y crear un activador de Eventarc. Después de generar un evento desde Pub/Sub, puedes verlo en los registros de Cloud Run.

Limpieza

Cuando termines las tareas descritas en esta guía de inicio rápido, puedes evitar que se te siga facturando eliminando los recursos que has creado.

Para quitar los recursos que se hayan aplicado anteriormente con tu configuración de Terraform, ejecuta el siguiente comando e introduce yes en la petición:

terraform destroy

También puedes eliminar tu Google Cloud proyecto para evitar que se te apliquen cargos. Al eliminar tu Google Cloud proyecto, se detendrá la facturación de todos los recursos utilizados en él.

Precaución: Eliminar un proyecto tiene los siguientes efectos:

• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Si tienes previsto consultar varios tutoriales y guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

Siguientes pasos

• Desarrollar servicios para Cloud Run
• Documentación sobre Google Cloud Terraform