Automatizar compilaciones en respuesta a eventos 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 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 escuchar cualquier tema de Pub/Sub.

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

Limitaciones

Los activadores de Pub/Sub de Cloud Build no son compatibles cuando se usan los Controles del servicio de VPC.

Antes de comenzar

  • Enable the Cloud Build API.

    Enable the 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 de esta página, instala Google Cloud CLI.

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

Puedes crear un activador de Pub/Sub que responda a 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ía una etiqueta nueva a una imagen existente. Si no estás familiarizado con Artifact Registry, consulta la descripción general de Artifact Registry.

Console

Para crear un activador que escuche una etiqueta nueva enviada a un imagen existente en Artifact Registry a través de la consola de Google Cloud:

  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.

    • Región: Selecciona la región para tu activador.

      • Si el archivo de configuración de compilación asociado con el activador especifica un grupo privado, Cloud Build usa el grupo privado para ejecutar la compilación. En este caso, la región que especifiques en el activador debe coincidir con la región en la que creaste tu grupo privado.
      • Si el archivo de configuración de compilación asociado con el activador no especifica un grupo privado, Cloud Build usa la configuración para ejecutar tu compilación en la misma región como detonante.

    • Descripción (opcional): Ingresa una descripción para el activador.

    • Evento: Selecciona Mensaje de Pub/Sub como el evento para invocar el activador.

    • Suscripción: Selecciona el tema de Pub/Sub al que te quieres suscribir como evento activador. Verás todos los temas existentes en tu proyecto en el menú desplegable.

    • Fuente: Selecciona la fuente que se compilará cuando se ejecute el activador de Pub/Sub. Puedes especificar 1ª generación o 2ª generación como fuente.

      • Repositorio: En la lista de repositorios disponibles, selecciona el que deseas.

      • Rama o Etiqueta: Especifica una expresión regular con la rama o el valor de la etiqueta que deben coincidir. Para obtener información acerca de la sintaxis de expresión regular aceptable, consulta Sintaxis RE2.

      • Control de comentarios: Si seleccionaste Solicitud de extracción (solo para la app de GitHub) como tu Evento, elige una de las siguientes opciones para controlar si el activador ejecutará una compilación de forma automática:

        • Es obligatorio excepto para los propietarios y colaboradores: Cuando un propietario o colaborador del repositorio crea o actualiza una solicitud de extracción, el activador ejecuta las compilaciones de forma automática. Si un colaborador externo inicia la acción, las compilaciones solo se ejecutarán después de que el propietario o colaborador comente /gcbrun en la solicitud de extracción.

        • Obligatorio: Cuando algún colaborador cree o actualice una solicitud de extracción, las compilaciones solo se ejecutarán después de que el propietario o el colaborador comente /gcbrun en la solicitud de extracción. Compilaciones se ejecutan cada vez que se realiza un cambio en una solicitud de extracción.

        • No obligatorio: Cuando cualquier colaborador crea o actualiza una solicitud de extracción, las compilaciones se ejecutan de forma automática con activadores.

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

      • Tipo: Selecciona el tipo de configuración que usarás para la 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.
        • Dockerfile: Usa Dockerfile para la configuración.
        • Paquetes de compilación: Usa paquetes de compilación para tu configuración.

      • Ubicación: Especifica la ubicación de tu configuración.

        • Repositorio: Si tu archivo de configuración se encuentra en tu repositorio remoto, proporciona la ubicación de tu archivo de configuración de compilación, el directorio Dockerfile o el directorio del paquete de compilación. Si el tipo de configuración de compilación es Dockerfile o un paquete de compilación, deberás proporcionar un nombre para la imagen resultante y, de forma opcional, un tiempo de espera para tu compilación. Cuando proporciones el Dockerfile o el nombre de la imagen del paquete de compilación, verás una vista previa del comando docker build o pack que ejecutará tu compilación.
        • Variables de entorno de paquete de compilación (opcional): Si seleccionaste buildpacks como el tipo de configuración, haz clic en Agregar variable de entorno del paquete para especificar las variables de entorno y los valores del paquete de compilación. Para obtener más información sobre las variables de entorno del paquete de compilación, consulta Variables de entorno.

        • En línea: Si seleccionaste Archivo de configuración de Cloud Build (YAML o JSON) como tu opción de configuración, puedes especificar tu configuración de la compilación de forma intercalada. Haz clic en Abrir editor para escribir tu archivo de configuración de compilación en la consola de Google Cloud con la sintaxis de YAML o JSON. Haz clic en Listo para guardar la configuración de tu compilación.

    • Sustituciones Si seleccionaste el archivo de configuración de compilación como tu opción de configuración de compilación, puedes definir Variables de sustitución de un activador específico mediante este campo.

      En el siguiente ejemplo, queremos obtener el nombre de la etiqueta de la 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 a PubSubMessage que publican los publicadores y que consumen los suscriptores. Para ver más ejemplos de la carga útil de notificaciones de Pub/Sub, consulta los ejemplos de notificaciones.

    • Filtros: 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 si especificas filtros en las variables de sustitución (opcional). La expresión de filtro debe evaluarse como true para que se ejecute una compilación.

      Recomendamos usar el filtrado cuando configures activadores de Pub/Sub en temas con varios mensajes. Los filtros se pueden usar 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 filtrar.

      En el siguiente ejemplo, queremos que el activador ejecute una compilación si un y la etiqueta nueva se envía 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 los siguientes elementos como filtros:

      • _IMAGE_TAG != ""
      • _ACTION == INSERT

      Los filtros de sintaxis en activadores de Pub/Sub usan Common Expression Language (CEL) para la evaluación de expresiones. Para obtener más información sobre CEL, consulta el repositorio de cel-spec.

  1. Haz clic en Crear para crear el activador.

gcloud

Para crear un activador que escuche una etiqueta nueva enviada a un imagen existente en Artifact Registry con los comandos gcloud:

  1. Abre una ventana de terminal.

  2. Ejecuta el comando gcloud para crear un activador de compilación en tu proyecto. En el siguiente ejemplo, el activador se configuró para responder a compilaciones con una coincidencia de etiquetas prod y una coincidencia de acción INSERT basada en la carga útil especificada según lo definido por la variable de sustitución, _IMAGE_TAG.

     gcloud builds triggers create pubsub \
   --region=REGION \
   --name=TRIGGER_NAME \
   --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_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)"' \
   --subscription-filter='_IMAGE_TAG != "" && _ACTION == "INSERT"' \
   --tag=TAG_NAME  # or --branch=BRANCH_NAME

Aquí:

  • REGION es la región del activador.
  • TRIGGER_NAME es el nombre del activador.
  • PROJECT_ID es el ID de tu proyecto de Cloud.
  • CONNECTION_NAME es el nombre de la conexión de host.
  • REPO_NAME es el nombre del repositorio.
  • 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 al archivo de configuración de compilación intercalado.
  • TAG_NAME es el nombre de tu etiqueta si deseas configurar tu activador para compilar en una etiqueta.
  • BRANCH_NAME es el nombre de la rama si deseas configurar el 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 puedes 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 a fin de obtener información para enviar y extraer imágenes con etiquetas.

Console

Para crear un activador que escuche el envío de una imagen en Container Registry y las coincidencias basadas en el nombre de una etiqueta con la consola de Google Cloud:

  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.

    • Región: Selecciona la región para el activador.

      • Si el archivo de configuración de compilación asociado con el activador especifica un grupo privado, Cloud Build usa el grupo privado para ejecutar la compilación. En este caso, la región que especifiques en el activador debe coincidir con la región en la que creaste el grupo privado.
      • Si el archivo de configuración de compilación asociado con el activador no especifica un grupo privado, Cloud Build usa la configuración para ejecutar tu compilación en la misma región como detonante.

    • Descripción (opcional): Ingresa una descripción para el activador.

    • Evento: Selecciona Mensaje de Pub/Sub como el evento para invocar el activador.

    • Suscripción: Selecciona el tema de Pub/Sub al que te quieres suscribir como evento activador. Verás todos los temas existentes en tu proyecto en el menú desplegable.

    • Fuente: Selecciona la fuente que se compilará cuando se ejecute el activador de Pub/Sub. Puedes especificar 1ª generación o 2ª generación como fuente.

      • Repositorio: En la lista de repositorios disponibles, selecciona el que deseas.

      • Rama o Etiqueta: Especifica una expresión regular con la rama o el valor de la etiqueta que deben coincidir. Para obtener información acerca de la sintaxis de expresión regular aceptable, consulta Sintaxis RE2.

      • Control de comentarios: Si seleccionaste Solicitud de extracción (solo para la app de GitHub) como tu Evento, elige una de las siguientes opciones para controlar si el activador ejecutará una compilación de forma automática:

        • Es obligatorio excepto para los propietarios y colaboradores: Cuando un propietario o colaborador del repositorio crea o actualiza una solicitud de extracción, el activador ejecuta las compilaciones de forma automática. Si un colaborador externo inicia la acción, las compilaciones solo se ejecutarán después de que el propietario o colaborador comente /gcbrun en la solicitud de extracción.

        • Obligatorio: Cuando algún colaborador cree o actualice una solicitud de extracción, las compilaciones solo se ejecutarán después de que el propietario o el colaborador comente /gcbrun en la solicitud de extracción. Compilaciones se ejecutan cada vez que se realiza un cambio en una solicitud de extracción.

        • No obligatorio: Cuando cualquier colaborador crea o actualiza una solicitud de extracción, las compilaciones se ejecutan de forma automática con activadores.

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

      • Tipo: Selecciona el tipo de configuración que usarás para la 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.
        • Dockerfile: Usa Dockerfile para la configuración.
        • Paquetes de compilación: Usa paquetes de compilación para tu configuración.

      • Ubicación: Especifica la ubicación de tu configuración.

        • Repositorio: Si el archivo de configuración se encuentra en tu repositorio remoto, proporciona la ubicación de tu archivo de configuración de compilación, el Dockerfile de compilación o el directorio de paquetes de compilación. Si el tipo de configuración de compilación es Dockerfile o un paquete de compilación, deberás proporcionar un nombre para la imagen resultante y, de forma opcional, un tiempo de espera para tu compilación. Cuando proporciones el Dockerfile o el nombre de la imagen del paquete de compilación, verás una vista previa del comando docker build o pack que ejecutará tu compilación.
        • Variables de entorno de paquete de compilación (opcional): Si seleccionaste buildpacks como el tipo de configuración, haz clic en Agregar variable de entorno del paquete para especificar las variables de entorno y los valores del paquete de compilación. Para obtener más información sobre las variables de entorno del paquete de compilación, consulta Variables de entorno.

        • En línea: Si seleccionaste Archivo de configuración de Cloud Build (YAML o JSON) como tu opción de configuración, puedes especificar tu configuración de la compilación de forma intercalada. Haz clic en Open Editor para escribir tu archivo de configuración de compilación en la consola de Google Cloud con sintaxis YAML o JSON. Haz clic en Listo para guardar la configuración de tu compilación.

    • Sustituciones Si seleccionaste el archivo de configuración de compilación como tu opción de configuración de compilación, puedes definir Variables de sustitución de un activador específico mediante este campo.

      En el siguiente ejemplo, queremos obtener el nombre de la etiqueta de la 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 a PubSubMessage que publican los publicadores y que consumen los suscriptores. Para ver más ejemplos de la carga útil de notificaciones de Pub/Sub, consulta los ejemplos de notificaciones.

    • Filtros: 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 si especificas filtros en las variables de sustitución (opcional). La expresión de filtro debe evaluarse como true para que se ejecute una compilación.

      Recomendamos usar el filtrado cuando configures activadores de Pub/Sub en temas con varios mensajes. Los filtros se pueden usar 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 filtrar.

      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. Puedes especificar tu operador de condición de filtro como "==" para una coincidencia 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 los siguientes elementos como filtros:

      • _IMAGE_TAG.matches(prod)
      • _ACTION.matches(INSERT)

      Los filtros de sintaxis en activadores de Pub/Sub usan Common Expression Language (CEL) para la evaluación de expresiones. Para obtener más información sobre CEL, consulta el repositorio de cel-spec. Si deseas ver más ejemplos de sintaxis para filtrar que puedes aplicar a tus activadores de Pub/Sub, consulta Filtra compilaciones.

  1. Haz clic en Crear para crear el activador.

gcloud

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

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

Console

Para crear un activador que escuche eventos de Cloud Storage con la consola de Google Cloud, haz lo siguiente:

  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.

    • Región: Selecciona la región para tu activador.

      • Si el archivo de configuración de compilación asociado con el activador especifica un grupo privado, Cloud Build usa el grupo privado para ejecutar tu compilación. En este caso, la región que especifiques en el activador debe coincidir con la región en la que creaste tu grupo privado.
      • Si el archivo de configuración de compilación asociado con el activador no especifica un grupo privado, Cloud Build usa la configuración para ejecutar tu compilación en la misma región como detonante.

    • Descripción (opcional): Ingresa una descripción para el activador.

    • Evento: Selecciona Mensaje de Pub/Sub como el evento para invocar el activador.

    • Suscripción: Selecciona el tema de Pub/Sub al que te quieres suscribir como evento activador. Verás todos los temas existentes en tu proyecto en el menú desplegable.

    • Fuente: Selecciona la fuente que se compilará cuando se ejecute el activador de Pub/Sub. Puedes especificar 1a generación o 2a generación como fuente.

      • Repositorio: En la lista de repositorios disponibles, selecciona el que deseas.

      • Rama o Etiqueta: Especifica una expresión regular con la rama o el valor de la etiqueta que deben coincidir. Para obtener información acerca de la sintaxis de expresión regular aceptable, consulta Sintaxis RE2.

      • Control de comentarios: Si seleccionaste Solicitud de extracción (solo para la app de GitHub) como tu Evento, elige una de las siguientes opciones para controlar si el activador ejecutará una compilación de forma automática:

        • Es obligatorio excepto para los propietarios y colaboradores: Cuando un propietario o colaborador del repositorio crea o actualiza una solicitud de extracción, el activador ejecuta las compilaciones de forma automática. Si un colaborador externo inicia la acción, las compilaciones solo se ejecutarán después de que el propietario o colaborador comente /gcbrun en la solicitud de extracción.

        • Obligatorio: Cuando algún colaborador cree o actualice una solicitud de extracción, las compilaciones solo se ejecutarán después de que el propietario o el colaborador comente /gcbrun en la solicitud de extracción. Compilaciones se ejecutan cada vez que se realiza un cambio en una solicitud de extracción.

        • No obligatorio: Cuando cualquier colaborador crea o actualiza una solicitud de extracción, las compilaciones se ejecutan de forma automática con activadores.

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

      • Tipo: Selecciona el tipo de configuración que usarás para la 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.
        • Dockerfile: Usa Dockerfile para la configuración.
        • Paquetes de compilación: Usa paquetes de compilación para tu configuración.

      • Ubicación: Especifica la ubicación de tu configuración.

        • Repositorio: Si el archivo de configuración se encuentra en tu repositorio remoto, proporciona la ubicación de tu archivo de configuración de compilación, el Dockerfile de compilación o el directorio de paquetes de compilación. Si el tipo de configuración de compilación es Dockerfile o un paquete de compilación, deberás proporcionar un nombre para la imagen resultante y, de forma opcional, un tiempo de espera para tu compilación. Cuando proporciones el Dockerfile o el nombre de la imagen del paquete de compilación, verás una vista previa del comando docker build o pack que ejecutará tu compilación.
        • Variables de entorno de paquete de compilación (opcional): Si seleccionaste buildpacks como el tipo de configuración, haz clic en Agregar variable de entorno del paquete para especificar las variables de entorno y los valores del paquete de compilación. Para obtener más información sobre las variables de entorno del paquete de compilación, consulta Variables de entorno.

        • En línea: Si seleccionaste Archivo de configuración de Cloud Build (YAML o JSON) como tu opción de configuración, puedes especificar tu configuración de la compilación de forma intercalada. Haz clic en Abrir editor para escribir tu archivo de configuración de compilación en la consola de Google Cloud con la sintaxis de YAML o JSON. Haz clic en Listo para guardar la configuración de tu compilación.

    • Sustituciones Si seleccionaste el archivo de configuración de compilación como tu opción de configuración de compilación, puedes definir Variables de sustitución de un activador específico mediante este campo.

      En este ejemplo, queremos observar la implementación de un objeto binario nuevo cuando se sube a un bucket. 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 a PubSubMessage que publican los publicadores y que consumen los suscriptores. Para ver más ejemplos de la carga útil de notificaciones de Pub/Sub, consulta los ejemplos de notificaciones.

    • Filtros: 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 si especificas filtros en las variables de sustitución (opcional). La expresión de filtro debe evaluarse como true para que se ejecute una compilación.

      Recomendamos usar el filtrado cuando configures activadores de Pub/Sub en temas con varios mensajes. Los filtros se pueden usar 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 filtrar.

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

      Especifica los siguientes elementos como 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.
    2. .

gcloud

Riesgos asociados con un activador sin filtrar

Si no configuraste filtros en el activador de Pub/Sub, el activador podría invocar una cantidad infinita de compilaciones si modifica un objeto o artefacto que publica un mensaje de manera involuntaria en el tema un tema que escucha. Por ejemplo, tu activador puede invocar una cantidad infinita de compilaciones si tu activador:

  • Apunta a un tema gcr.
  • Crea cualquier imagen o etiqueta en gcr.
  • Apunta a un tema gcs para un objeto específico en tu bucket 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 incurrir en cargos adicionales por cada compilación que invoques.

¿Qué sigue?