Recibe eventos mediante mensajes de Pub/Sub (Terraform)

Recibe 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 enrute los eventos a un servicio de Cloud Run. Si deseas obtener más información para usar Terraform y crear activadores de Eventarc, 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 de Identity and Access Management (IAM) necesarios.
   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.

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. To initialize the gcloud CLI, run the following command:

   gcloud init

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

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Cloud Resource Manager and IAM APIs:

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

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

8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

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

11. Make sure that billing is enabled for your Google Cloud project.

12. Enable the Cloud Resource Manager and IAM APIs:

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

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

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

    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)
    • 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 mediante roles personalizados o cualquier otro rol predefinido.

Prepárate para implementar Terraform

Crea un archivo de configuración de Terraform para prepararte para implementar los recursos de Terraform. Un archivo de configuración de Terraform te permite definir el estado final preferido de 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 tu shell local, establece el proyecto predeterminado de Google Cloud 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 proyecto de Google Cloud .

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, el archivo se denomina main.tf.

Define tu configuración de Terraform

Copia los siguientes fragmentos de código de Terraform en el archivo main.tf que creaste. 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 invocador de Cloud Run (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, 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"
}

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 google_cloud_run_v2_service de Terraform:

# 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 google_pubsub_topic de Terraform:

# 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 en estar completamente operativo.

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, aplicas toda la configuración de una sola 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 un problema, intenta aplicar la configuración de Terraform nuevamente.

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

Verifica la creación de recursos

1. Confirma que se creó 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 de 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 usen en ese proyecto.

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 ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar 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 Terraform en Google Cloud