Crea activadores de Pub/Sub

Los activadores de Pub/Sub de Cloud Build te permiten ejecutar compilaciones en respuesta a los eventos de Google Cloud publicados en Pub/Sub. Puedes usar la información de un evento de Pub/Sub para parametrizar tu compilación y decidir si una compilación debe ejecutarse en respuesta al evento. Los activadores de Pub/Sub se pueden configurar para detectar cualquier tema de Pub/Sub.

En esta página, se explica cómo puedes crear un activador de Pub/Sub para invocar compilaciones en respuesta a eventos en Artifact Registry, Container Registry y Cloud Storage.

Antes de comenzar

  • Habilita la API Cloud Build.

    Habilita la API

  • Asegúrate de que tu código fuente contenga un archivo de configuración de compilación o un Dockerfile en el repositorio.
  • Para usar los comandos de gcloud en esta página, instala el SDK de Cloud.

Crea un activador de compilación que responda a los eventos de Artifact Registry

Puedes crear un activador de Pub/Sub que responda a los eventos de Artifact Registry, como cuando se envían, etiquetan o borran imágenes. En esta sección, se explica cómo puedes crear un activador de Pub/Sub que invoque una compilación cuando se envíe una etiqueta nueva a una imagen existente. Si no estás familiarizado con Artifact Registry, consulta la descripción general de la administración de artefactos.

Console

Para crear un activador que escuche una etiqueta nueva que se envió a una imagen existente en Artifact Registry con Google Cloud Console, sigue estos pasos:

  1. Abrir la página Activadores:

    Abrir la página Activadores

  2. Selecciona el proyecto en la parte superior de la página y haz clic en Abrir.

  3. Haz clic en Crear activador.

  4. Ingresa las siguientes opciones de configuración del activador:

    • Nombre: Ingresa un nombre para el activador.
    • Descripción (opcional): Ingresa una descripción para el activador.
    • Evento: Selecciona el Mensaje de Pub/Sub como el evento para invocar el activador.
    • Suscripción: selecciona el tema de Pub/Sub al que deseas suscribirte como evento del activador. Verás todos los temas existentes en tu proyecto en el menú desplegable.

    • Fuente: selecciona el repositorio para compilar cuando se ejecuta el activador.

    • Revisión: Selecciona la rama o etiqueta para compilar cuando se ejecute el activador.

      • Rama: Ingresa el nombre de la rama en la que se invocará tu compilación.
      • Etiqueta: Ingresa el nombre de la etiqueta para invocar tu compilación.
    • Configuración: Selecciona el archivo de configuración de compilación (ubicado en tu repositorio remoto) o crea un archivo de configuración de compilación intercalado para usarlo en tu compilación.

      • Archivo de configuración de Cloud Build (yaml o json): usa un archivo de configuración de compilación para la configuración. Deberás proporcionar la ubicación de tu archivo de configuración de compilación y, opcionalmente, las variables de sustitución que deseas usar.

      • Dockerfile: usa un Dockerfile para la configuración. Deberás especificar el directorio Dockerfile y un nombre para la imagen resultante. De manera opcional, también puedes proporcionar un tiempo de espera para la compilación. Cuando hayas proporcionado el Dockerfile y el nombre de la imagen, verás una vista previa del comando docker build que se ejecutará en la compilación.

      • Intercalada: usa una configuración de compilación intercalada para la configuración. Haz clic en Abrir editor para abrir tu archivo de configuración de compilación en Google Cloud Console con la sintaxis YAML o JSON. Haz clic en Listo para guardar la configuración de compilación.

    • Sustituciones Si seleccionaste el archivo de configuración de compilación como tu opción de configuración de compilación (opcional), puedes elegir definir un activador específico para el activador.variables de sustitución con este campo.

      En el siguiente ejemplo, queremos obtener el nombre de la etiqueta de imagen de la carga útil y la acción asociada con el evento gcr. Para hacerlo, crea variables de sustitución con vinculaciones de carga útil.

      Especifica las siguientes variables y valores a continuación:

      Nombre de la variable Valor de la variable
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message hace referencia al PubSubMessage publicado por los publicadores y lo consumen los suscriptores. Para ver más ejemplos de la carga útil de notificación de Pub/Sub, consulta Ejemplos de notificaciones.

    • Filtros (opcional): Puedes crear filtros dentro de un activador que determinen si tu activador ejecutará o no una compilación en respuesta a la carga útil entrante mediante la especificación de filtros en variables de sustitución. La expresión de filtro debe evaluarse como true para que se ejecute una compilación.

      Recomendamos que uses filtros cuando configures activadores de Pub/Sub en temas con varios mensajes. Se pueden usar filtros para controlar con precisión las compilaciones que se ejecutan en respuesta a los mensajes entrantes de Pub/Sub. Para obtener información sobre los riesgos asociados con la configuración de un activador sin filtros, consulta Riesgos asociados con un activador sin filtro.

      En el siguiente ejemplo, queremos que el activador ejecute una compilación si se envía una etiqueta nueva a una imagen existente. Usamos operadores de condición de filtro para verificar si la variable _IMAGE_TAG coincide con un nombre de etiqueta existente y si la variable _ACTION coincide con INSERT para buscar datos agregados recientemente.

      Especifica lo siguiente como tus filtros:

      • _IMAGE_TAG != ""
      • _ACTION == INSERT

      La sintaxis de filtrado en activadores de Pub/Sub usa el lenguaje de expresión común (CEL) para la evaluación de expresiones. Para obtener más información sobre CEL, consulta el repositorio cel-spec. Para ver más sintaxis de ejemplo de filtrado que puedes aplicar a tus activadores de Pub/Sub, consulta Filtra compilaciones.

  1. Haz clic en Crear para crear el activador de compilación.
  2. de Google Cloud Platform.

gcloud

Para crear un activador que escuche una etiqueta nueva que se envió a una imagen existente en Artifact Registry, usa los comandos gcloud:

  1. Abre una ventana de terminal.
  2. Ejecuta el comando gcloud alpha para crear un activador de compilación en tu proyecto. En el siguiente ejemplo, el activador está configurado para responder a las compilaciones con una coincidencia de etiquetas.prod y la coincidencia de accionesINSERT en función de la carga útil especificada según lo definido por la variable de sustitución_IMAGE_TAG las rutas "a GCP".

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --substitutions=\
         _IMAGE_TAG_='$(body.message.data.tag)'
         _ACTION='$(body.message.data.action)'
       --filter='_IMAGE_TAG == "" && _ACTION == "INSERT"'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    Aquí:

    • TRIGGER_NAME es el nombre del activador.
    • PROJECT_ID es el ID de tu proyecto de Cloud.
    • TOPIC_NAME es el nombre del tema de Pub/Sub al que te suscribiste.
    • BUILD_CONFIG es la ruta de acceso al archivo de configuración de compilación.
    • INLINE_BUILD_CONFIG es la ruta de acceso a tu archivo de configuración de compilación intercalado.
    • REPO_NAME es el nombre del repositorio de origen en el que se invoca la compilación.
    • TAG_NAME es el nombre de tu etiqueta si deseas que tu activador se compile en una etiqueta.
    • BRANCH_NAME es el nombre de tu rama si deseas configurar tu activador para que se compile en una rama.

Crea un activador de compilación que responda a los eventos de Container Registry

Puedes crear un activador de Pub/Sub que responda a los eventos de Container Registry, como cuando se envían, etiquetan o borran imágenes. En esta sección, se explica cómo crear un activador de Pub/Sub que invoque una compilación cuando una imagen coincida con una etiqueta configurada por un filtro personalizado. Si no estás familiarizado con Container Registry, consulta la guía de inicio rápido para Container Registry para aprender a enviar y extraer imágenes con etiquetas.

Console

Para crear un activador que escuche una imagen de envío en Container Registry y coincida con el nombre de una etiqueta con Google Cloud Console, sigue estos pasos:

  1. Abrir la página Activadores:

    Abrir la página Activadores

  2. Selecciona el proyecto en la parte superior de la página y haz clic en Abrir.

  3. Haz clic en Crear activador.

  4. Ingresa las siguientes opciones de configuración del activador:

    • Nombre: Ingresa un nombre para el activador.
    • Descripción (opcional): Ingresa una descripción para el activador.
    • Evento: Selecciona el Mensaje de Pub/Sub como el evento para invocar el activador.
    • Suscripción: selecciona el tema de Pub/Sub al que deseas suscribirte como evento del activador. Verás todos los temas existentes en tu proyecto en el menú desplegable.

    • Fuente: selecciona el repositorio para compilar cuando se ejecuta el activador.

    • Revisión: Selecciona la rama o etiqueta para compilar cuando se ejecute el activador.

      • Rama: Ingresa el nombre de la rama en la que se invocará tu compilación.
      • Etiqueta: Ingresa el nombre de la etiqueta para invocar tu compilación.
    • Configuración: Selecciona el archivo de configuración de compilación (ubicado en tu repositorio remoto) o crea un archivo de configuración de compilación intercalado para usarlo en tu compilación.

      • Archivo de configuración de Cloud Build (yaml o json): usa un archivo de configuración de compilación para la configuración. Deberás proporcionar la ubicación de tu archivo de configuración de compilación y, opcionalmente, las variables de sustitución que deseas usar.

      • Dockerfile: usa un Dockerfile para la configuración. Deberás especificar el directorio Dockerfile y un nombre para la imagen resultante. De manera opcional, también puedes proporcionar un tiempo de espera para la compilación. Cuando hayas proporcionado el Dockerfile y el nombre de la imagen, verás una vista previa del comando docker build que se ejecutará en la compilación.

      • Intercalada: usa una configuración de compilación intercalada para la configuración. Haz clic en Abrir editor para abrir tu archivo de configuración de compilación en Google Cloud Console con la sintaxis YAML o JSON. Haz clic en Listo para guardar la configuración de compilación.

    • Sustituciones Si seleccionaste el archivo de configuración de compilación como tu opción de configuración de compilación (opcional), puedes elegir definir un activador específico para el activador.variables de sustitución con este campo.

      En el siguiente ejemplo, queremos obtener el nombre de la etiqueta de imagen de la carga útil y la acción asociada con el evento gcr. Para hacerlo, crea variables de sustitución con vinculaciones de carga útil.

      Especifica las siguientes variables y valores a continuación:

      Nombre de la variable Valor de la variable
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message hace referencia al PubSubMessage publicado por los publicadores y lo consumen los suscriptores. Para ver más ejemplos de la carga útil de notificación de Pub/Sub, consulta Ejemplos de notificaciones.

    • Filtros (opcional): Puedes crear filtros dentro de un activador que determinen si tu activador ejecutará o no una compilación en respuesta a la carga útil entrante mediante la especificación de filtros en variables de sustitución. La expresión de filtro debe evaluarse como true para que se ejecute una compilación.

      Recomendamos que uses filtros cuando configures activadores de Pub/Sub en temas con varios mensajes. Se pueden usar filtros para controlar con precisión las compilaciones que se ejecutan en respuesta a los mensajes entrantes de Pub/Sub. Para obtener información sobre los riesgos asociados con la configuración de un activador sin filtros, consulta Riesgos asociados con un activador sin filtro.

      En el siguiente ejemplo, queremos que el activador ejecute una compilación si el nombre de la variable de etiqueta _IMAGE_TAG coincide con un nombre de etiqueta específico, como prod. Puede especificar su operador de condición de filtro como "==" para la concordancia exacta. También puedes verificar la acción asociada con tu evento gcr. Por ejemplo, es posible que desees especificar _ACTION es INSERT para buscar datos recién agregados.

      Especifica lo siguiente como tus filtros:

      • _IMAGE_TAG == prod
      • _ACTION == INSERT

      La sintaxis de filtrado en activadores de Pub/Sub usa el lenguaje de expresión común (CEL) para la evaluación de expresiones. Para obtener más información sobre CEL, consulta el repositorio cel-spec. Para ver más sintaxis de ejemplo de filtrado que puedes aplicar a tus activadores de Pub/Sub, consulta Filtra compilaciones.

  1. Haz clic en Crear para crear el activador de compilación.
  2. de Google Cloud Platform.

gcloud

Para crear un activador que escuche una imagen de envío en Container Registry y coincida con el nombre de una etiqueta mediante los comandos de gcloud, haz lo siguiente:

  1. Abre una ventana de terminal.
  2. Ejecuta el comando gcloud alpha para crear un activador de compilación en tu proyecto. En el siguiente ejemplo, el activador está configurado para responder a las compilaciones con una coincidencia de etiquetas.prod y la coincidencia de accionesINSERT en función de la carga útil especificada según lo definido por la variable de sustitución_IMAGE_TAG las rutas "a GCP".

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --substitutions=\
         _IMAGE_TAG_='$(body.message.data.tag)'
         _ACTION='$(body.message.data.action)'
       --filter='_IMAGE_TAG == "prod" && _ACTION == "INSERT"'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    Aquí:

    • TRIGGER_NAME es el nombre del activador.
    • PROJECT_ID es el ID de tu proyecto de Cloud.
    • TOPIC_NAME es el nombre del tema de Pub/Sub al que te suscribiste.
    • BUILD_CONFIG es la ruta de acceso al archivo de configuración de compilación.
    • INLINE_BUILD_CONFIG es la ruta de acceso a tu archivo de configuración de compilación intercalado.
    • REPO_NAME es el nombre del repositorio de origen en el que se invoca la compilación.
    • TAG_NAME es el nombre de tu etiqueta si deseas que tu activador se compile en una etiqueta.
    • BRANCH_NAME es el nombre de tu rama si deseas configurar tu activador para que se compile en una rama.

Crea un activador de compilación que responda a los eventos de Cloud Storage

Puedes crear un activador de Pub/Sub que responda a los eventos de Cloud Storage, como cuando se envía un objeto binario nuevo a un depósito de almacenamiento existente. En esta sección, se explica cómo crear un activador de Pub/Sub que responda con una compilación cuando se implementa un objeto binario nuevo en un depósito subido. Si no estás familiarizado con Cloud Storage, consulta las Guías de inicio rápido.

Console

Para crear un activador que escuche los eventos de Cloud Storage con Google Cloud Console, sigue estos pasos:

  1. Abrir la página Activadores:

    Abrir la página Activadores

  2. Selecciona el proyecto en la parte superior de la página y haz clic en Abrir.

  3. Haz clic en Crear activador.

  4. Ingresa las siguientes opciones de configuración del activador:

    • Nombre: Ingresa un nombre para el activador.
    • Descripción (opcional): Ingresa una descripción para el activador.
    • Evento: Selecciona el Mensaje de Pub/Sub como el evento para invocar el activador.
    • Suscripción: selecciona el tema de Pub/Sub al que deseas suscribirte como evento del activador. Verás todos los temas existentes en tu proyecto en el menú desplegable.

    • Fuente: selecciona el repositorio para compilar cuando se ejecuta el activador.

    • Revisión: Selecciona la rama o etiqueta para compilar cuando se ejecute el activador.

      • Rama: Ingresa el nombre de la rama en la que se invocará tu compilación.
      • Etiqueta: Ingresa el nombre de la etiqueta para invocar tu compilación.
    • Configuración: Selecciona el archivo de configuración de compilación (ubicado en tu repositorio remoto) o crea un archivo de configuración de compilación intercalado para usarlo en tu compilación.

      • Archivo de configuración de Cloud Build (yaml o json): usa un archivo de configuración de compilación para la configuración. Deberás proporcionar la ubicación de tu archivo de configuración de compilación y, opcionalmente, las variables de sustitución que deseas usar.

      • Dockerfile: usa un Dockerfile para la configuración. Deberás especificar el directorio Dockerfile y un nombre para la imagen resultante. De manera opcional, también puedes proporcionar un tiempo de espera para la compilación. Cuando hayas proporcionado el Dockerfile y el nombre de la imagen, verás una vista previa del comando docker build que se ejecutará en la compilación.

      • Intercalada: usa una configuración de compilación intercalada para la configuración. Haz clic en Abrir editor para abrir tu archivo de configuración de compilación en Google Cloud Console con la sintaxis YAML o JSON. Haz clic en Listo para guardar la configuración de compilación.

    • Sustituciones Si seleccionaste el archivo de configuración de compilación como tu opción de configuración de compilación (opcional), puedes elegir definir un activador específico.variables de sustitución con este campo.

      En este ejemplo, queremos ver la implementación de un objeto binario nuevo cuando se sube a un depósito. Para obtener estos datos, podemos crear variables de sustitución con vinculaciones de carga útil.

      Especifica las siguientes variables y valores a continuación:

      Nombre de la variable Valor de la variable
      _EVENT_TYPE $(body.message.attributes.eventType)
      _BUCKET_ID $(body.message.attributes.bucketId)
      _OBJECT_ID $(body.message.attributes.objectId)

      body.message hace referencia al PubSubMessage publicado por los publicadores y lo consumen los suscriptores. Para ver más ejemplos de la carga útil de notificación de Pub/Sub, consulta Ejemplos de notificaciones.

    • Filtros (opcional): Puedes crear filtros dentro de un activador que determinen si tu activador ejecutará o no una compilación en respuesta a la carga útil entrante mediante la especificación de filtros en variables de sustitución. La expresión de filtro debe evaluarse como true para que se ejecute una compilación.

      Recomendamos que uses filtros cuando configures activadores de Pub/Sub en temas con varios mensajes. Se pueden usar filtros para controlar con precisión las compilaciones que se ejecutan en respuesta a los mensajes entrantes de Pub/Sub. Para obtener información sobre los riesgos asociados con la configuración de un activador sin filtros, consulta Riesgos asociados con un activador sin filtro.

      Como queremos que el activador ejecute una compilación si el objeto binario nuevo se implementó en un depósito específico, podemos usar el operador "==" para verificar las coincidencias exactas. También puedes usar la palabra clave “coincidencias” si deseas hacer coincidir una expresión regular.

      Especifica lo siguiente como tus filtros:

      • _EVENT_TYPE == OBJECT_FINALIZE
      • _OBJECT_ID coincide con ^<object-id>$
      • _BUCKET_ID coincide con ^<bucket-id>$
  1. Haz clic en Crear para crear el activador de compilación.
  2. de Google Cloud Platform.

gcloud

Para crear un activador de compilación que escuche los eventos de compilación con un tipo de evento específico en Cloud Storage, haz lo siguiente:

  1. Abre una ventana de terminal.
  2. Ejecuta el comando gcloud alpha para crear un activador de compilación en tu proyecto. En el siguiente ejemplo, el activador está configurado para responder a compilaciones con un evento de Cloud Storage asociado con un nuevo objeto binario enviado a un depósito de almacenamiento existente:

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --subtitutions=\
         _EVENT_TYPE='$(body.message.attributes.eventType)'
         _BUCKET_ID='$(body.message.attributes.bucketId)'
         _OBJECT_ID='$(body.message.attributes.objectId)'
       --filter='_EVENT_TYPE == "OBJECT_FINALIZE" && _OBJECT_ID.matches("<object-id>") && _BUCKET_ID.matches("<bucket-id>")'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    Aquí:

    • TRIGGER_NAME es el nombre del activador.
    • PROJECT_ID es el ID de tu proyecto de Cloud.
    • TOPIC_NAME es el nombre del tema de Pub/Sub al que te suscribiste.
    • BUILD_CONFIG es la ruta de acceso al archivo de configuración de compilación.
    • INLINE_BUILD_CONFIG es la ruta de acceso a tu archivo de configuración de compilación intercalado.
    • REPO_NAME es el nombre del repositorio de origen en el que se invoca la compilación.
    • TAG_NAME es el nombre de tu etiqueta si deseas que tu activador se compile en una etiqueta.
    • BRANCH_NAME es el nombre de tu rama si deseas configurar tu activador para que se compile en una rama.

Riesgos asociados con un activador sin filtrar

Si no configuraste los filtros en tu activador de Pub/Sub, es posible que el activador invoque una cantidad infinita de compilaciones si el activador modifica un artefacto o un objeto que publica de forma involuntaria un mensaje nuevo en el tema. para que los escuche. Por ejemplo, tu activador puede invocar una cantidad infinita de compilaciones si el activador:

  • Hace referencia a un tema gcr.
  • Crea cualquier imagen o etiqueta en gcr.
  • Hace referencia a un tema gcs para un objeto específico de tu depósito y lo modifica.

Si encuentras un bucle infinito, puedes borrar tu activador o actualizarlo para que apunte a un tema separado a fin de evitar que se generen cargos adicionales por cada compilación que invoques.

¿Qué sigue?