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 y otórgale los roles necesarios de Identity and Access Management (IAM).
   3. Implementa un servicio en Cloud Run como destino del evento.
   4. Crea un tema de Pub/Sub como proveedor de eventos.
   5. Crear un activador de Eventarc.

3. Aplica tu configuración de Terraform.

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

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 Google Cloud restringido.

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 usas un proveedor de identidad externo (IdP), primero debes acceder a gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

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:

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 usas un proveedor de identidad externo (IdP), primero debes acceder a gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

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:

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 eres el creador del proyecto, se te otorga el rol de propietario básico (roles/owner). De forma predeterminada, este rol de Identity and Access Management (IAM) incluye los permisos necesarios para obtener acceso completo a la mayoría de los recursos de Google Cloud y puedes omitir este paso.

   Si no eres el creador del proyecto, se deben otorgar los permisos necesarios en el proyecto a la principal correspondiente. Por ejemplo, una principal puede ser una Cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de procesamiento). Para obtener más información, consulta la página Roles y permisos para el destino del evento.

   Permisos necesarios

   Para 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)
   • Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin)

   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

Prepara la implementación 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 con la sintaxis de Terraform.

1. Si usas una shell local, instala y configura 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 instalarlo.

2. En Cloud Shell o en tu shell local, establece el proyecto Google Cloud predeterminado en el que deseas aplicar tus configuraciones 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.

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

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, se hace referencia al archivo como main.tf.

Define tu configuración de Terraform

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

Habilita las APIs

Por lo general, las muestras de Terraform suponen que las APIs necesarias están habilitadas en tu proyecto deGoogle Cloud . 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
}

Crea una cuenta de servicio y configura su acceso

Cada activador de Eventarc se asocia a una cuenta de servicio de IAM. Para completar esta guía de inicio rápido, debes otorgar a una cuenta de servicio administrada por el usuario los siguientes roles de IAM:

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

Usa el siguiente fragmento de código para crear una cuenta de servicio dedicada y otorgarle roles de IAM específicos para administrar 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 de 2021 o antes de esa fecha, otórgale 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"
}

Implementa un receptor de eventos en Cloud Run

Crea un servicio de Cloud Run como destino del evento para el activador de Eventarc con 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]
}

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

Crea un activador de Eventarc

Crea un activador de Eventarc para detectar los 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 tu activador se creará de inmediato, puede tardar hasta dos minutos para que los activadores funcionen por completo.

Aplica Terraform

Usa la CLI de Terraform para aprovisionar la infraestructura según el archivo de configuración.

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los 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 de una 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 y 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. 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 que creó 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 lo siguiente:

   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. El activador puede tardar hasta dos minutos después de la creación en comenzar a filtrar eventos.

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.

Limpia

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 tu 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 en el proyecto. 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 del proyecto personalizado 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.

Delete a Google Cloud project:

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