Configurar notificaciones SMTP

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

Antes de empezar

  • Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

    Enable the APIs

Configurar notificaciones por correo electrónico

Para enviar notificaciones por correo electrónico, necesitarás un servidor SMTP en funcionamiento y acceso a una cuenta de ese servidor, incluido el nombre de usuario y la contraseña de la cuenta que se utilizarán para enviar las notificaciones. Puedes usar cualquier servidor SMTP, pero necesitarás acceso al nombre y al puerto del servidor. Por ejemplo, el nombre del servidor de Gmail es smtp.gmail.com y el puerto es 587. Asegúrate de que las cuotas de entrega del servidor SMTP puedan gestionar el volumen de correos que esperas generar.

En la siguiente sección se explica cómo configurar manualmente las notificaciones por correo mediante el notificador SMTP. Si quieres automatizar la configuración, consulta Automatizar la configuración de las notificaciones.

Para configurar las notificaciones por correo electrónico, sigue estos pasos:

  1. Almacena la contraseña de la cuenta de correo del remitente en Secret Manager. Ten en cuenta que, en el caso de Gmail, tendrás que usar la contraseña de la aplicación en lugar de la contraseña de inicio de sesión de la cuenta.

    1. Abre la página Secret Manager en la Google Cloud consola:

      Abre la página Secret Manager.

    2. Haz clic en Crear secreto.

    3. Introduce un nombre para el secreto.

    4. En Valor secreto, añade la contraseña de la cuenta de correo del remitente.

    5. Para guardar el secreto, haz clic en Crear secreto.

  2. Aunque la cuenta de servicio de Cloud Run puede tener el rol Editor en tu proyecto, este rol no es suficiente para acceder a tu secreto en Secret Manager. Para dar acceso a tu secreto a la cuenta de servicio de Cloud Run, haz lo siguiente:

    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

      Anota la cuenta de servicio predeterminada de Compute Engine.

    3. Abre la página Secret Manager en la Google Cloud consola:

      Abre la página Secret Manager.

    4. Haz clic en el nombre del secreto que contiene la contraseña de la cuenta de correo del remitente.

    5. En la pestaña Permisos, haz clic en Añadir miembro.

    6. Añada como miembro la cuenta de servicio predeterminada de Compute Engine asociada a su proyecto.

    7. Selecciona el permiso Permiso para acceder a los recursos de Secret Manager como rol.

    8. Haz clic en Guardar.

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

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

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

    apiVersion: cloud-build-notifiers/v1
kind: SMTPNotifier
metadata:
  name: example-smtp-notifier
spec:
  notification:
    filter: build.status == Build.Status.SUCCESS
    params:
      buildStatus: $(build.status)
    delivery:
      server: server-host-name
      port: "port"
      sender: sender-email
      from: from-email
      recipients:
        - recipient-email
        # optional: more emails here
      password:
        secretRef: smtp-password
    template:
      type: golang
      uri: gs://bucket_name/smtp.html
  secrets:
  - name: smtp-password
    value: projects/project-id/secrets/secret-name/versions/latest

    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.
    • bucket-name es el nombre de tu segmento.
    • server-host-name es la dirección de tu servidor SMTP.
    • port es el puerto que gestionará las solicitudes SMTP. Este valor debe especificarse como una cadena.
    • sender-email es la dirección de correo de la cuenta del remitente que ve el server-host-name especificado.
    • from-email es la dirección de correo que ven los destinatarios.
    • recipient-email es una lista de una o varias direcciones de correo electrónico para recibir mensajes del remitente.
    • smtp-password es la variable de configuración que se usa en este ejemplo para hacer referencia a la contraseña de la cuenta de correo del remitente almacenada en Secret Manager. El nombre de la variable que especifiques aquí debe coincidir con el campo name de secrets.
    • project-id es el ID de tu Google Cloud proyecto.
    • secret-name es el nombre de tu secreto que contiene la contraseña de la cuenta de correo del remitente.

    • El campo uri hace referencia al archivo smtp.html. Este archivo hace referencia a una plantilla HTML alojada en Cloud Storage y representa tu correo de notificación.

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

    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.

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

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

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

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

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

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

  11. 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, el recipients especificado recibirá un correo con una notificación 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