Configurar notificaciones HTTP

Cloud Build puede informarte de las actualizaciones de compilación enviándote notificaciones a los canales que elijas, como Slack o tu servidor SMTP. En esta página se explica cómo configurar las notificaciones mediante el notificador HTTP.

Antes de empezar

  • Enable the Cloud Build, Cloud Run, and Pub/Sub APIs.

    Enable the APIs

Configurar notificaciones HTTP

En la siguiente sección se explica cómo configurar manualmente las notificaciones HTTP mediante el notificador HTTP para enviar solicitudes POST a una URL de destinatario determinada. Si quieres automatizar la configuración, consulta Automatizar la configuración de las notificaciones.

Para configurar notificaciones HTTP, sigue estos pasos:

Para usar el notificador HTTP y enviar solicitudes POST a una URL de destinatario determinada, sigue estos pasos:

  1. Concede a tu cuenta de servicio de Cloud Run permiso para leer de los segmentos de Cloud Storage:

    1. Ve a la página Gestión de identidades y accesos de la Google Cloud consola:

      Abre la página Gestión de identidades y accesos.

    2. Busca la cuenta de servicio predeterminada de Compute Engine asociada a tu proyecto:

      Tu cuenta de servicio predeterminada de Compute Engine será similar a la siguiente:

      project-number-compute@developer.gserviceaccount.com

    3. Haz clic en el icono de lápiz de la fila que contiene tu cuenta de servicio predeterminada de Compute Engine. Verás la pestaña Editar acceso.

    4. Haz clic en Añadir otro rol.

    5. Añade el siguiente rol:

      • Lector de objetos de Storage

    6. Haz clic en Guardar.

  2. Escribe un archivo de configuración de notificador para configurar tu notificador HTTP y filtrar los eventos de compilación:

    En el siguiente archivo de configuración de notificador de ejemplo, el campo filter usa el lenguaje de expresiones comunes con la variable disponible build para filtrar eventos de compilación con el estado SUCCESS:

    apiVersion: cloud-build-notifiers/v1
kind: HTTPNotifier
metadata:
  name: example-http-notifier
spec:
  notification:
    filter: build.status == Build.Status.SUCCESS
    params:
      buildStatus: $(build.status)
    delivery:
      # The `http(s)://` protocol prefix is required.
      url: url
    template:
      type: golang
      uri: gs://bucket_name/http.json

    Donde:

    • buildStatus es un parámetro definido por el usuario. Este parámetro toma el valor de $(build.status), el estado de la compilación.
    • url es la variable de configuración que se usa en este ejemplo para especificar la URL de tu solicitud.
    • bucket-name es el nombre de tu segmento.
    • url es la URL que quieres especificar como servidor receptor.

    • El campo uri hace referencia al archivo http.json. Este archivo hace referencia a una plantilla JSON alojada en Cloud Storage y representa la carga útil JSON del endpoint del webhook.

      Para ver un ejemplo de un archivo de plantilla, consulta el archivo http.json en el repositorio cloud-build-notifiers.

    Para ver un ejemplo, consulta el archivo de configuración del notificador del notificador HTTP.

    Para ver los campos adicionales por los que puedes filtrar, consulta el recurso Build. Para ver más ejemplos de filtrado, consulta el artículo Usar CEL para filtrar eventos de compilaciones.

  3. Sube el archivo de configuración del notificador a un depósito de Cloud Storage:

    1. Si no tienes ningún segmento de Cloud Storage, ejecuta el siguiente comando para crear uno. Sustituye bucket-name por el nombre que quieras darle al segmento, que debe cumplir los requisitos de nomenclatura.

      gcloud storage buckets create gs://bucket-name/

    2. Sube el archivo de configuración del notificador a tu segmento:

      gcloud storage cp config-file-name gs://bucket-name/config-file-name

      Donde:

      • bucket-name es el nombre de tu segmento.
      • config-file-name es el nombre del archivo de configuración del notificador.

  4. Despliega tu notificador en Cloud Run:

     gcloud run deploy service-name \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/slack:latest \
   --no-allow-unauthenticated \
   --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id

    Donde:

    • service-name es el nombre del servicio de Cloud Run en el que vas a desplegar la imagen.
    • config-path es la ruta al archivo de configuración del notificador de Slack, gs://bucket-name/config-file-name.
    • project-id es el ID de tu Google Cloud proyecto.

    El comando gcloud run deploy extrae la versión más reciente de la imagen alojada del Artifact Registry propiedad de Cloud Build. Cloud Build admite imágenes de notificador durante nueve meses. Al cabo de nueve meses, Cloud Build elimina la versión de la imagen. Si quieres usar una versión anterior de la imagen, tendrás que especificar la versión semántica completa de la etiqueta de imagen en el atributo image del comando gcloud run deploy. Las versiones y etiquetas anteriores de las imágenes se pueden encontrar en Artifact Registry.

  5. Concede permisos de Pub/Sub para crear tokens de autenticación en tu Google Cloud proyecto:

     gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator

    Donde:

    • project-id es el ID de tu Google Cloud proyecto.
    • project-number es el número de tu proyecto Google Cloud .

  6. Crea una cuenta de servicio que represente la identidad de tu suscripción de Pub/Sub:

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"

    Puedes usar cloud-run-pubsub-invoker o un nombre único en tu proyecto. Google Cloud

  7. Concede a la cuenta de servicio cloud-run-pubsub-invoker el permiso Cloud Run Invoker:

    gcloud run services add-iam-policy-binding service-name \
   --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
   --role=roles/run.invoker

    Donde:

    • service-name es el nombre del servicio de Cloud Run en el que vas a desplegar la imagen.

    • project-id es el ID de tu Google Cloud proyecto.

  8. Crea el tema cloud-builds para recibir mensajes de actualización de compilación de tu notificador:

    gcloud pubsub topics create cloud-builds

    También puedes definir un nombre de tema personalizado en el archivo de configuración de compilación para que los mensajes se envíen al tema personalizado. En este caso, crearías un tema con el mismo nombre de tema personalizado:

    gcloud pubsub topics create topic-name

    Para obtener más información, consulta Temas de Pub/Sub para notificaciones de compilación.

  9. Crea un suscriptor de inserción de Pub/Sub para tu notificador:

     gcloud pubsub subscriptions create subscriber-id \
   --topic=cloud-builds \
   --push-endpoint=service-url \
   --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com

    Donde:

    • subscriber-id es el nombre que quieres dar a tu suscripción.
    • service-url es la URL generada por Cloud Run para tu nuevo servicio.
    • project-id es el ID de tu Google Cloud proyecto.

Las notificaciones de tu proyecto de Cloud Build ya están configuradas. La próxima vez que invoques una compilación, tu servidor HTTP receptor en la URL indicada recibirá cargas útiles JSON que coincidan con el recurso Build si la compilación coincide con el filtro que has configurado.

Usar CEL para filtrar eventos de compilaciones

Cloud Build usa CEL con la variable build en los campos que se indican en el recurso Build para acceder a los campos asociados a tu evento de compilación, como el ID del activador, la lista de imágenes o los valores de sustitución. Puedes usar la filtercadena para filtrar eventos de compilación en tu archivo de configuración de compilación usando cualquier campo que se indique en el recurso Build. Para encontrar la sintaxis exacta asociada a tu campo, consulta el archivo cloudbuild.proto.

Filtrar por ID de activador

Para filtrar por ID de activador, especifique el valor de su ID de activador en el campo filter con build.build_trigger_id, donde trigger-id es su ID de activador como cadena:

filter: build.build_trigger_id == trigger-id

Filtrar por estado

Para filtrar por estado, especifica el estado de compilación por el que quieres filtrar en el campo filter con build.status.

En el siguiente ejemplo se muestra cómo filtrar eventos de compilación con un SUCCESS status mediante el campo filter:

filter: build.status == Build.Status.SUCCESS

También puedes filtrar compilaciones con diferentes estados. En el siguiente ejemplo se muestra cómo filtrar eventos de compilación que tienen el estado SUCCESS, FAILURE o TIMEOUT mediante el campo filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Para ver otros valores de estado por los que puedes filtrar, consulta Estado en la referencia de recursos de compilación.

Filtrar por etiqueta

Para filtrar por etiqueta, especifica el valor de tu etiqueta en el campo filter con build.tags, donde tag-name es el nombre de tu etiqueta:

filter: tag-name in build.tags

Puede filtrar por el número de etiquetas especificadas en su evento de compilación con size. En el siguiente ejemplo, el campo filter filtra los eventos de compilación que tienen exactamente dos etiquetas especificadas, una de ellas como v1:

filter: size(build.tags) == 2 && "v1" in build.tags

Filtrar por imágenes

Para filtrar por imágenes, especifique el valor de su imagen en el campo filter con build.images, donde image-name es el nombre completo de su imagen tal como aparece en Artifact Registry, como us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

En el siguiente ejemplo, filter filtra los eventos de compilación que tienen us-east1-docker.pkg.dev/my-project/docker-repo/image-one o us-east1-docker.pkg.dev/my-project/docker-repo/image-two especificados como nombres de imagen:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images

Filtrar por hora

Puedes filtrar eventos de compilación en función de la hora de creación, la hora de inicio o la hora de finalización de una compilación. Para ello, especifica una de las siguientes opciones en el campo filter: build.create_time, build.start_time o build.finish_time.

En el siguiente ejemplo, el campo filter usa timestamp para filtrar eventos de compilación con una hora de solicitud para crear la compilación el 20 de julio del 2020 a las 6:00:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

También puede filtrar los eventos de compilación por comparaciones de tiempo. En el ejemplo siguiente, el campo filter usa timestamp para filtrar eventos de compilación con una hora de inicio entre las 6:00 del 20 de julio del 2020 y las 6:00 del 30 de julio del 2020.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Para obtener más información sobre cómo se expresan las zonas horarias en CEL, consulta la definición de zonas horarias.

Para filtrar por la duración de una compilación, puedes usar duration para comparar marcas de tiempo. En el siguiente ejemplo, el campo filter usa duration para filtrar los eventos de compilación con compilaciones que se ejecutan durante al menos cinco minutos:

filter: build.finish_time - build.start_time >= duration("5m")

Filtrar por sustitución

Para filtrar por sustitución, especifica la variable de sustitución en el campo filter con build.substitutions. En el ejemplo siguiente, el campo filter muestra las compilaciones que contienen la variable de sustitución substitution-variable y comprueba si substitution-variable coincide con el substitution-value especificado:

filter: build.substitutions[substitution-variable] == substitution-value

Donde:

  • substitution-variable es el nombre de la variable de sustitución.
  • substitution-value es el nombre del valor de sustitución.

También puede filtrar por los valores predeterminados de las variables de sustitución. En el siguiente ejemplo, el campo filter muestra las compilaciones que tienen el nombre de rama master y las compilaciones que tienen el nombre de repositorio github.com/user/my-example-repo. Las variables de sustitución predeterminadas BRANCH_NAME y REPO_NAME se transfieren como claves a build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Si quieres filtrar cadenas mediante expresiones regulares, puedes usar la función matches integrada. En el ejemplo siguiente, el campo filter filtra las compilaciones con el estado FAILURE o TIMEOUT y que también tienen una variable de sustitución de compilación TAG_NAME con un valor que coincide con la expresión regular v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")

Para ver una lista de los valores de sustitución predeterminados, consulta Usar sustituciones predeterminadas.

Siguientes pasos