Publica y recibe eventos creando un bus y una inscripción (Terraform)

Publica y recibe eventos creando un bus y una inscripción (Terraform)

Avanzado

En esta guía de inicio rápido, se muestra cómo usar Terraform para crear un bus Eventarc Advanced y una inscripción en tu proyecto de Google Cloud para que puedas publicar y recibir mensajes de eventos.

• Un bus actúa como un enrutador central que recibe mensajes de fuentes de eventos o que publican los proveedores.

• Una inscripción enruta los mensajes que recibe el bus a uno o más destinos a través de una canalización de procesamiento.

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

1. Implementar un servicio de receptor de eventos en Cloud Run

2. Crea un bus de Eventarc Advanced.

3. Habilita los eventos de fuentes de Google.

4. Crea una canalización y una inscripción de Eventarc Advanced.

5. Crea un flujo de trabajo para publicar un mensaje de evento en el bus.

6. Visualizar los datos del evento en los registros de Cloud Run

Puedes completar la mayoría de los pasos de esta guía de inicio rápido con Terraform. Para completar todos los pasos con Google Cloud CLI, consulta Publica eventos desde una fuente de Google.

Para obtener más información sobre el uso de Terraform, consulta la documentación de Terraform en Google Cloud.

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 es la primera vez que usas 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.

In the Google Cloud console, on the project selector page, select or create 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 role (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.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create 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 role (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.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. En la consola de Google Cloud , activa Cloud Shell.

   Activa Cloud Shell

   En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

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

Roles obligatorios

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)
• Desarrollador de Eventarc (roles/eventarc.developer)
• Administrador de buses de mensajes de Eventarc (roles/eventarc.messageBusAdmin)
• Descriptor de acceso de vista de registros (roles/logging.viewAccessor)
• Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
• Administrador de cuenta de servicio (roles/iam.serviceAccountAdmin)
• Usuario de la cuenta de servicio (roles/iam.serviceAccountUser)
• Editor de flujos de trabajo (roles/workflows.editor)

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. En Cloud Shell, 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 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.

2. Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz). En Cloud Shell, 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

Usa el recurso de Terraform google_project_service para habilitar las APIs necesarias para aplicar la configuración de Terraform:

# Enable APIs
resource "google_project_service" "apis" {
  for_each = toset([
    "eventarc.googleapis.com",
    "eventarcpublishing.googleapis.com",
    "run.googleapis.com"
  ])
  service            = each.key
  disable_on_destroy = false
}

Crea una cuenta de servicio

Para realizar pruebas, crea una cuenta de servicio dedicada y otórgale roles de IAM específicos.

Usa los recursos de Terraform google_service_account y google_project_iam_member para crear la cuenta de servicio y otorgarle los roles necesarios para publicar y recibir eventos:

# Used to retrieve project information later
data "google_project" "project" {}

# Create a dedicated service account
resource "google_service_account" "default" {
  account_id   = "eventarc-advanced-sa"
  display_name = "Eventarc Advanced quickstart service account"
}

# Grant permission to receive Eventarc events
resource "google_project_iam_member" "eventreceiver" {
  project = data.google_project.project.id
  role    = "roles/eventarc.eventReceiver"
  member  = "serviceAccount:${google_service_account.default.email}"
}

# 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.default.email}"
}

Crea un destino de evento

Usa el recurso de Terraform google_cloud_run_v2_service para crear un servicio de Cloud Run como destino de eventos que registre el contenido de un evento:

# Deploy Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "example-service"
  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.default.email
  }

  depends_on = [google_project_service.apis]
}

Crea un bus de Eventarc Advanced

Un bus recibe mensajes de eventos de una fuente de mensajes o publicados por un proveedor, y actúa como un enrutador de mensajes. Para obtener más información, consulta Crea un bus para enrutar mensajes.

Nota: Puedes crear un bus por proyecto de Google Cloud porregión admitida.

Usa el recurso de Terraform google_eventarc_message_bus para crear un bus de Eventarc Advanced:

# Create an Eventarc Advanced bus
resource "google_eventarc_message_bus" "default" {
  location       = "us-central1"
  message_bus_id = "example-bus"
}

Habilita eventos de fuentes de Google

Para publicar eventos desde fuentes de Google, debes crear un recurso GoogleApiSource que represente una suscripción a los eventos de la API de Google para un bus de Eventarc Advanced en particular. Para obtener más información, consulta Publica eventos desde fuentes de Google.

Nota: Puedes crear un recurso GoogleApiSource por Google Cloudproyecto y por región admitida.

Usa el recurso de Terraform google_eventarc_google_api_source para habilitar eventos de fuentes de Google:

# Enable events from Google API sources
resource "google_eventarc_google_api_source" "default" {
  location             = "us-central1"
  google_api_source_id = "example-google-api-source"
  destination          = google_eventarc_message_bus.default.id
}

Todos los tipos de eventos de Google admitidos que se envían directamente desde una fuente de Google ahora se recopilan y publican en tu bus.

Crea una canalización de Eventarc Advanced

Una canalización te permite configurar un destino y también te brinda la opción de transformar los eventos coincidentes antes de entregarlos al destino.

Usa el recurso de Terraform google_eventarc_pipeline para crear una canalización:

# Create an Eventarc Advanced pipeline
resource "google_eventarc_pipeline" "default" {
  location    = "us-central1"
  pipeline_id = "example-pipeline"
  destinations {
    http_endpoint {
      uri = google_cloud_run_v2_service.default.uri
    }
    authentication_config {
      google_oidc {
        service_account = google_service_account.default.email
      }
    }
  }
}

El destino del evento es la URL completamente calificada de tu servicio de Cloud Run, por ejemplo, https://SERVICE_NAME-abcdef-uc.a.run.app. La dirección de correo electrónico de la cuenta de servicio se usa para generar un token de OIDC.

Nota: La creación de una canalización puede tardar varios minutos.

Crea un registro de Eventarc Advanced

Una inscripción determina qué mensajes se enrutan a un destino y también especifica la canalización que se usa para configurar un destino para los mensajes de eventos. Para obtener más información, consulta Crea un registro para recibir eventos.

Usa el recurso de Terraform google_eventarc_enrollment para crear una inscripción:

# Create an Eventarc Advanced enrollment
resource "google_eventarc_enrollment" "default" {
  location      = "us-central1"
  enrollment_id = "example-enrollment"
  message_bus   = google_eventarc_message_bus.default.id
  destination   = google_eventarc_pipeline.default.id
  cel_match     = "message.type == 'google.cloud.workflows.workflow.v1.created'"
}

La expresión de coincidencia para la inscripción usa Common Expression Language (CEL) para publicar mensajes de eventos cada vez que se crea un flujo de trabajo. En un paso posterior, crearás un flujo de trabajo.

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, ingresa yes cuando se te solicite:

   terraform apply

   Por lo general, aplicas toda la configuración de una vez. Sin embargo, también puedes segmentar tus anuncios para un recurso específico. Por ejemplo:

   terraform apply -target="google_eventarc_message_bus.default"

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

Publica un mensaje de evento en el bus creando un flujo de trabajo

Workflows es una plataforma de organización completamente administrada que ejecuta servicios en el orden que defines: un flujo de trabajo. Crea un flujo de trabajo para generar un tipo de evento compatible a partir de una fuente de Google.

1. En tu directorio principal, crea un archivo nuevo que se llame myWorkflow.yaml.

2. Copia y pega el siguiente flujo de trabajo en el archivo nuevo y, luego, guárdalo:

   main:
       params: [input]
       steps:
       - checkSearchTermInInput:
           switch:
               - condition: '${"searchTerm" in input}'
                 assign:
                   - searchTerm: '${input.searchTerm}'
                 next: readWikipedia
       - getLocation:
           call: sys.get_env
           args:
               name: GOOGLE_CLOUD_LOCATION
           result: location
       - setFromCallResult:
           assign:
               - searchTerm: '${text.split(location, "-")[0]}'
       - readWikipedia:
           call: http.get
           args:
               url: 'https://en.wikipedia.org/w/api.php'
               query:
                   action: opensearch
                   search: '${searchTerm}'
           result: wikiResult
       - returnOutput:
               return: '${wikiResult.body[1]}'
   

   Este flujo de trabajo pasa la región en la que se implementa el flujo de trabajo a la API de Wikipedia y muestra una lista de artículos de Wikipedia relacionados.

3. Implementa el flujo de trabajo con el comando gcloud workflows deploy:

   gcloud workflows deploy example-workflow --source=myWorkflow.yaml \
       --service-account=eventarc-advanced-sa@PROJECT_ID.iam.gserviceaccount.com \
       --location=us-central1

Visualiza los datos del evento en los registros de Cloud Run

Después de publicar un evento en tu bus de Eventarc Advanced, puedes verificar los registros de tu servicio de Cloud Run para confirmar que el evento se recibió según lo esperado.

1. Filtra las entradas de registro creadas por tu servicio:

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.workflows.workflow.v1.created."'
   

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

   message: 'Received event of type google.cloud.workflows.workflow.v1.created.
   Event data: {"@type":"type.googleapis.com/google.events.cloud.workflows.v1.WorkflowEventData","payload":{"name":"projects/PROJECT_ID/locations/us-central1/workflows/example-workflow","state":"ACTIVE"...
   

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

Creaste correctamente un bus y una inscripción de Eventarc Advanced, habilitaste la publicación de eventos desde fuentes de Google, creaste un flujo de trabajo para generar un tipo de evento compatible desde un proveedor de Google y, luego, verificaste el resultado esperado en los registros del servicio de receptor de eventos.

Realiza una limpieza

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

También puedes borrar tu proyecto Google Cloud para evitar que se apliquen cargos. Si borras tu Google Cloud proyecto, 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 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.
1. En la Google Cloud consola, ve a la página Administrar recursos.

   Ir a Administrar recursos

2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

• Publica eventos directamente
• Transforma los eventos recibidos
• Cómo dar formato a los eventos recibidos