Activa flujos de trabajo mediante mensajes de Pub/Sub (CLI de gcloud)

Activa flujos de trabajo mediante mensajes de Pub/Sub (CLI de gcloud)

Estándar

En esta guía de inicio rápido, se muestra cómo ejecutar un flujo de trabajo con un activador de Eventarc que recibe eventos usando Pub/Sub. El activador ejecuta el flujo de trabajo cuando pasa eventos entregados a través de Pub/Sub como argumentos del entorno de ejecución a un flujo de trabajo de destino.

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

1. Usa Workflows para crear y, luego, implementar un flujo de trabajo que decodifica y devuelve mensajes de Pub/Sub.
2. Crea un activador de Eventarc que conecte un tema de Pub/Sub con un receptor de eventos de Workflows.
3. Publicar un mensaje en el tema de Pub/Sub para generar un evento. Este evento se pasa como un argumento de entorno de ejecución al flujo de trabajo de destino.
4. Visualiza el mensaje de Pub/Sub como resultado de la ejecución del flujo de trabajo.

Antes de comenzar

Asegúrate de tener acceso a esta función. Para ello, solicita que se agregue tu proyecto a las versiones preliminares privadas de Google Cloud Workflows.

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. Install the Google Cloud CLI.

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

   gcloud init

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

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

10. Actualiza los componentes de gcloud:

    gcloud components update

11. Habilita las APIs de Compute Engine, Eventarc, Pub/Sub y Workflows.

    gcloud services enable \
    compute.googleapis.com \
    eventarc.googleapis.com \
    pubsub.googleapis.com \
    workflows.googleapis.com \
    workflowexecutions.googleapis.com

12. Establece las variables de configuración que se usan en este instructivo:

    export WORKFLOW_LOCATION=us-central1
    export TRIGGER_LOCATION=us-central1
    export PROJECT_ID=PROJECT_ID
    gcloud config set project ${PROJECT_ID}
    gcloud config set workflows/location ${WORKFLOW_LOCATION}
    gcloud config set eventarc/location ${TRIGGER_LOCATION}

13. 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, pero 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 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)
    • Administrador de flujos de trabajo (roles/workflows.admin)

    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.

14. Toma nota del recurso Compute Engine predeterminada, ya que la conectarás a un activador de Eventarc para representar la identidad del activador con fines de prueba. Esta cuenta de servicio se crea automáticamente después de habilitar o usar un servicio de Google Cloud que use Compute Engine, y con la siguiente formato de correo electrónico:

    [e-mail]

    Reemplaza PROJECT_NUMBER por el número de proyecto de Google Cloud. Para encontrar el número del proyecto, ve a la página de bienvenida de la consola de Google Cloud o ejecuta el siguiente comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Para entornos de producción, recomendamos crear una cuenta de servicio nueva y otorgarle una o más funciones de IAM que contengan los permisos mínimos requeridos y seguir el principio de privilegio mínimo.

    Nota:

    La restricción de la política de la organización iam.automaticIamGrantsForDefaultServiceAccounts evita que el rol Editor se otorgue de forma automática a las cuentas de servicio predeterminadas. Si creaste tu organización después del 3 de mayo de 2024, esta restricción se aplica de forma predeterminada.

    Recomendamos que apliques esta restricción para inhabilitar la concesión automática de roles. Si inhabilitas la concesión automática de roles, debes decidir qué roles se deben otorgar a las cuentas de servicio predeterminadas y, luego, otorgar estos roles a ti mismo.

    Si la cuenta de servicio predeterminada ya tiene el rol de editor, te recomendamos que reemplaces el rol de editor por roles menos permisivos.Para modificar de forma segura los roles de la cuenta de servicio, usa Policy Simulator para ver el impacto del cambio y, luego, otorga y revoca los roles adecuados.

15. Otorga el rol de invocador de Workflows (roles/workflows.invoker) del proyecto a la cuenta de servicio predeterminada de Compute Engine para que la cuenta tenga permiso para activar la ejecución de tu flujo de trabajo.

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/workflows.invoker

16. Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril de 2021 o antes de esa fecha, para admitir las solicitudes de envío de Pub/Sub autenticadas, otorga el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio. De lo contrario, este rol se otorga de forma predeterminada:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/iam.serviceAccountTokenCreator

Crea e implementa un flujo de trabajo

Crea y, luego, implementa un flujo de trabajo que se ejecute cuando un mensaje publicado en un tema de Pub/Sub active un flujo de trabajo con una solicitud HTTP.

1. Abre una terminal o Cloud Shell.
2. En tu directorio principal, crea un archivo nuevo que se llame myFirstWorkflow.yaml o myFirstWorkflow.json.
3. Copia y pega lo siguiente en el archivo nuevo y guárdalo:

   YAML

   main:
     params: [event]
     steps:
       - decode_pubsub_message:
           assign:
              - base64: ${base64.decode(event.data.message.data)}
              - message: ${text.decode(base64)}
       - return_pubsub_message:
           return: ${message}

   JSON

   {
     "main": {
       "params": [
         "event"
       ],
       "steps": [
         {
           "decode_pubsub_message": {
             "assign": [
               {
                 "base64": "${base64.decode(event.data.message.data)}"
               },
               {
                 "message": "${text.decode(base64)}"
               }
             ]
           }
         },
         {
           "return_pubsub_message": {
             "return": "${message}"
           }
         }
       ]
     }
   }

4. Implementa el flujo de trabajo:

   export MY_WORKFLOW=myFirstWorkflow
   gcloud workflows deploy ${MY_WORKFLOW} --source=myFirstWorkflow.yaml

   Reemplaza .yaml por .json si copiaste la versión JSON del flujo de trabajo de ejemplo.

Crea un activador de Eventarc

Cuando se publica un mensaje en el tema de Pub/Sub, el evento activa el flujo de trabajo.

1. Crea un activador para detectar los mensajes de Pub/Sub:

   Nuevo tema Pub/Sub

   gcloud eventarc triggers create events-pubsub-trigger \
       --destination-workflow=${MY_WORKFLOW} \
       --destination-workflow-location=${WORKFLOW_LOCATION} \
       --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
       --service-account="[e-mail]"

   Esto crea un nuevo tema de Pub/Sub y un activador llamado events-pubsub-trigger.

   Tema de Pub/Sub existente

   gcloud eventarc triggers create events-pubsub-trigger \
       --destination-workflow=${MY_WORKFLOW} \
       --destination-workflow-location=${WORKFLOW_LOCATION} \
       --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
       --service-account="[e-mail]" \
       --transport-topic=TOPIC_ID

   Reemplaza TOPIC_ID por el ID del tema de Pub/Sub existente.

   Esto crea un activador llamado events-pubsub-trigger para el tema de Pub/Sub existente.

   Nota: De forma predeterminada, las suscripciones a Pub/Sub creadas para Eventarc persisten, sin importar la actividad, y no vencen. Para cambiar la duración de la inactividad, consulta Propiedades de la suscripción.

   Ten en cuenta que, cuando creas un activador de Eventarc por primera vez en un proyecto de Google Cloud, es posible que haya un retraso en el aprovisionamiento del agente de servicio de Eventarc. Por lo general, este problema se puede resolver si intentas crear el activador de nuevo. Para obtener más información, consulta Errores de permiso denegado.

2. Confirma que el activador se haya creado correctamente:

   gcloud eventarc triggers describe events-pubsub-trigger --location=${TRIGGER_LOCATION}

   El resultado debería ser similar al siguiente ejemplo de la hora de creación y la ubicación del activador:

   createTime: '2021-10-14T15:15:43.872360951Z'
   [...]
   name: projects/PROJECT_ID/locations/us-central1/triggers/events-pubsub-trigger

Genera y visualiza un evento

Publica un mensaje en el tema de Pub/Sub para generar un evento y activar el flujo de trabajo. El evento generado se pasa como un argumento de entorno de ejecución al flujo de trabajo que devuelve el mensaje de Pub/Sub como resultado de la ejecución del flujo de trabajo. Asegúrate de que el tamaño de los eventos que pases al flujo de trabajo no supere los 512 KB.

1. Si creaste un activador para un tema nuevo de Pub/Sub, busca y establece el tema de Pub/Sub creado como una variable de entorno:

   export TOPIC_ID=$(basename $(gcloud eventarc triggers describe events-pubsub-trigger --format='value(transport.pubsub.topic)'))

2. Para activar el flujo de trabajo, envía un mensaje al tema de Pub/Sub:

   gcloud pubsub topics publish $TOPIC_ID --message "Hello there"

   El evento generado se pasa como un argumento de entorno de ejecución al flujo de trabajo que muestra el mensaje “¡Hola!”.

3. Para verificar que se activó una ejecución de flujo de trabajo, enumera las últimas cinco ejecuciones:

   gcloud workflows executions list ${MY_WORKFLOW} --limit=5

   El resultado debería ser similar al siguiente, con NAME y STATE igual a SUCCEEDED para cada ejecución del flujo de trabajo:

   NAME: projects/606789101455/locations/us-central1/workflows/myFirstWorkflow/executions/8c02b8f1-8836-4a6d-99d9-fc321eb9668f
   STATE: SUCCEEDED
   START_TIME: 2021-09-13T19:15:10.275677049Z
   END_TIME: 2021-09-13T19:15:10.963136883Z
   NAME: projects/606789101455/locations/us-central1/workflows/myFirstWorkflow/executions/a6319d9d-36a6-4117-904e-3d1118bdc90a
   STATE: SUCCEEDED
   START_TIME: 2021-09-13T17:28:51.492864252Z
   END_TIME: 2021-09-13T17:28:52.227212414Z
   

   Ten en cuenta que en el campo NAME del ejemplo anterior, a6319d9d-36a6-4117-904e-3d1118bdc90a es el ID de la ejecución del flujo de trabajo. Copia tu ID de ejecución para usarlo en el siguiente paso.

4. Para ver el estado de ejecución, ejecuta el siguiente comando:

   gcloud workflows executions describe WORKFLOW_EXECUTION_ID --workflow=${MY_WORKFLOW}

   Reemplaza WORKFLOW_EXECUTION_ID por el ID de la ejecución del flujo de trabajo que corresponde a la hora de publicación del tema de Pub/Sub. El resultado es similar al siguiente:

   argument: [...]
   endTime: '2021-09-13T17:28:47.301012152Z'
   name: projects/1234567/locations/us-central1/workflows/myFirstWorkflow/executions/f72bc6d4-5ea0-4dfb-bb14-2dae82303120
   result: 'Hello there'
   startTime: '2021-09-13T17:28:51.492864252Z'
   state: SUCCEEDED

5. Verifica que el publish_time en el que se publicó el mensaje de Pub/Sub y el startTime de la ejecución del flujo de trabajo correspondan entre sí.

Felicitaciones, generaste con éxito un evento usando un tema de Pub/Sub que activó un receptor de eventos de Workflows con Eventarc.

Realiza una limpieza

1. Borra el flujo de trabajo que creaste:

   gcloud workflows delete ${MY_WORKFLOW}

   Cuando se te pregunte si deseas continuar, ingresa y.
2. Borra el activador que creaste:

   gcloud eventarc triggers delete events-pubsub-trigger

3. Como alternativa, puedes borrar el proyecto de Google Cloud para evitar que se generen cargos. Si borras tu proyecto de Google Cloud, se dejan de facturar todos los recursos que usaste 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

¿Qué sigue?

• Controla el orden de ejecución en un flujo de trabajo

• Crea un activador para enrutar eventos de Pub/Sub a Workflows