Recibe eventos con mensajes de Pub/Sub (Terraform)

Recibe eventos con 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 recibe eventos directos de Pub/Sub y los enruta a un servicio de Cloud Run. Si deseas obtener más información para crear activadores de Eventarc con Terraform, consulta Crea un activador con Terraform.

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

1. Prepárate para implementar Terraform.

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

   1. Habilitar las API
   2. Crea una cuenta de servicio.
   3. Crea un tema de Pub/Sub como proveedor de eventos.
   4. Implementa un servicio en Cloud Run como destino del evento.
   5. Crear un activador de Eventarc.

3. Aplica tu configuración de Terraform.

Esto te permite generar un evento si publicas un mensaje en el tema de Pub/Sub. El activador de Eventarc enruta el mensaje al servicio de receptor de eventos implementado en Cloud Run, y el servicio registra el mensaje del evento, lo que te proporciona un ejemplo sencillo de una arquitectura basada en eventos.

Antes de comenzar

Es posible que las restricciones de seguridad que define tu organización no te permitan completar los siguientes pasos. Para obtener información sobre la solución de problemas, consulta Desarrolla aplicaciones en un entorno de Google Cloud restringido.

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un Google Cloud proyecto:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de Cloud Resource Manager y de Identity and Access Management (IAM):

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

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

Si usas un shell local, crea credenciales de autenticación locales para tu cuenta de usuario:

gcloud auth application-default login

No es necesario que lo hagas si usas Cloud Shell.

Si se devuelve un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un Google Cloud proyecto:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de Cloud Resource Manager y de Identity and Access Management (IAM):

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

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

Si usas un shell local, crea credenciales de autenticación locales para tu cuenta de usuario:

gcloud auth application-default login

No es necesario que lo hagas si usas Cloud Shell.

Si se devuelve un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.

1. Si usas un proyecto existente en esta guía, verifica que tengas los permisos necesarios para completarla. Si creaste un proyecto nuevo, ya tienes los permisos necesarios.

   Permisos necesarios

   Si quieres obtener los permisos que necesitas para completar esta guía de inicio rápido, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

   • Administrador de Cloud Run (roles/run.admin)
   • Administrador de Eventarc (roles/eventarc.admin)
   • Descriptor de acceso de vista de registros (roles/logging.viewAccessor)
   • Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
   • Publicador de Pub/Sub (roles/pubsub.publisher)
   • Administrador de cuenta de servicio (roles/iam.serviceAccountAdmin)
   • Usuario de cuenta de servicio (roles/iam.serviceAccountUser)

   Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

   También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Preparación para implementar Terraform

Antes de implementar cualquier recurso de Terraform, debes crear 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 con la sintaxis de Terraform.

1. Si usas una shell local, instala Terraform.

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

2. En Cloud Shell o en tu shell local, establece el proyecto Google Cloud predeterminado en el que deseas aplicar tu configuración de Terraform. Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Reemplaza PROJECT_ID por el ID de tu Google Cloud proyecto.

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

3. 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 nuevo dentro de ese directorio:

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

   Reemplaza DIRECTORY por el nombre de tu directorio de Terraform.

   El nombre del archivo debe tener la extensión .tf, por ejemplo, en este inicio rápido, el archivo de configuración es main.tf.

Define tu configuración de Terraform

Copia los siguientes fragmentos de código de Terraform en tu archivo main.tf. O bien, para copiar toda la muestra de código de GitHub, en la esquina superior derecha de un fragmento de código, haz clic en > Ver en GitHub.

Habilita las APIs

Para habilitar las APIs necesarias para aplicar la configuración de Terraform, usa el recurso de Terraform 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
}

Crea una cuenta de servicio

Cada activador de Eventarc se asocia a una cuenta de servicio de IAM. Para crear una cuenta de servicio dedicada con fines de prueba, usa el recurso de Terraform google_service_account:

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

Si habilitaste el agente de servicio de Pub/Sub el 8 de abril de 2021 o antes de esa fecha, otorga el rol de 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"
}

Crea un tema de Pub/Sub como proveedor de eventos

Para crear un tema de Pub/Sub, usa el recurso de Terraform google_pubsub_topic. Para otorgar a tu cuenta de servicio el rol de Publicador de Pub/Sub (roles/pubsub.publisher) a nivel del tema, usa el recurso de Terraform 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]
}

Implementa un receptor de eventos en Cloud Run

Para crear un servicio de Cloud Run como destino del evento, usa el recurso de Terraform google_cloud_run_v2_service. Para otorgar a tu cuenta de servicio el rol de Invocador de Cloud Run (roles/run.invoker) a nivel del servicio, usa el recurso de Terraform 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]
}

Crea un activador de Eventarc

Para crear un activador de Eventarc que detecte mensajes de Pub/Sub, usa 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_pubsub_topic_iam_member.pubsubpublisher
  ]
}

Nota: Aunque tu activador se creará de inmediato, puede tardar hasta dos minutos para que los activadores funcionen por completo.

Aplica la configuración de Terraform

Usa la CLI de Terraform para aprovisionar la infraestructura según el archivo de configuración. Para obtener más información, consulta Comandos básicos de Terraform.

1. Inicializa Terraform. Solo debes hacerlo una vez por directorio.

   terraform init

   De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:

   terraform init -upgrade

2. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:

   terraform plan

   Corrige la configuración según sea necesario.

3. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:

   terraform apply

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

   terraform apply -target="google_eventarc_trigger.default"

   Después de habilitar las APIs, es posible que la acción tarde unos minutos en propagarse antes de que puedas implementar más recursos. Si tienes algún problema, vuelve a aplicar la configuración de Terraform.

   Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

Verifica la creación de recursos

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

   gcloud run services list --region us-central1
   

   El resultado debería ser similar al siguiente ejemplo:

   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 haya creado el activador de Eventarc:

   gcloud eventarc triggers list --location us-central1
   

   El resultado debería ser similar al siguiente ejemplo:

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

Genera y visualiza un evento de tema de Pub/Sub

Puedes generar un evento si publicas un mensaje en el tema de Pub/Sub. El activador de Eventarc enruta el mensaje al servicio del receptor de eventos implementado en Cloud Run, y el servicio registra el mensaje del evento.

1. Busca y establece el tema Pub/Sub como una 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. Para generar un evento, publica un mensaje en el tema de Pub/Sub:

   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. Filtra las entradas de registro creadas por tu servicio:

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

4. Busca una entrada de registro similar a la que se muestra a continuación:

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

   Nota: Si no ves una entrada de registro, espera unos minutos y vuelve a ejecutar el comando gcloud logging read.

Usaste Terraform correctamente para implementar 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.

Realiza una limpieza

Cuando finalices las tareas que se describen en esta guía de inicio rápido, puedes borrar los recursos que creaste para evitar que continúe la facturación.

Quita los recursos que se aplicaron antes con tu configuración de Terraform a través de la ejecución del siguiente comando y, luego, ingresa yes cuando se te solicite:

terraform destroy

Como alternativa, puedes borrar el proyecto Google Cloud para evitar que se generen cargos. Si borras tu proyecto de Google Cloud , se detendrá la facturación de todos los recursos que se usaron en él.

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Borra un Google Cloud proyecto:

gcloud projects delete PROJECT_ID

Si planeas explorar varios instructivos y guías de inicio rápido, la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

¿Qué sigue?

• Desarrolla servicios para Cloud Run
• Documentación de Google Cloud Terraform