Cloud Build puede notificarte sobre actualizaciones de compilación mediante el envío de notificaciones a los canales deseados, como Slack o tu servidor SMTP. En esta página, se explica cómo configurar las notificaciones con el notificador SMTP.
Antes de comenzar
-
Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.
- Instala Google Cloud CLI.
Configura las notificaciones de correo electrónico
Para enviar notificaciones por correo electrónico, necesitarás un servidor SMTP en ejecución y acceso a una cuenta en ese servidor, incluido el nombre de usuario y la contraseña de la cuenta que se usarán para enviar notificaciones. Puedes usar cualquier servidor SMTP existente, pero
necesitará acceso al nombre del servidor y al puerto. Por ejemplo, el nombre del servidor para
Gmail es smtp.gmail.com
y el puerto es 587
. Asegúrate de que la cuenta de SMTP
las cuotas de entrega de tu servidor
pueden manejar el volumen de correo electrónico que esperas generar.
En la siguiente sección, se explica cómo puedes configurar las notificaciones por correo electrónico de forma manual mediante el notificador SMTP. En cambio, si deseas automatizar la configuración, consulta Automatiza la configuración para las notificaciones.
Para configurar las notificaciones de correo electrónico, haz lo siguiente:
Almacena la contraseña de la cuenta de correo electrónico del remitente en Secret Manager. Ten en cuenta que, para Gmail, deberás usar la contraseña de la aplicación en lugar de la contraseña de acceso de la cuenta.
Abre la página de Secret Manager en la consola de Google Cloud:
Haz clic en Crear secreto.
Ingresa un nombre para tu secreto.
En Valor del secreto, agrega la contraseña de la cuenta de correo electrónico del remitente.
Para guardar el secreto, haz clic en Crear secreto.
Aunque tu cuenta de servicio de Cloud Run tenga Editor de tu proyecto, no el rol Editor suficientes para acceder a tu Secret en Secret Manager. Tendrás que darle que tu cuenta de servicio de Cloud Run acceda al secreto:
Ve a la página de IAM en la consola de Google Cloud:
Busca la cuenta de servicio predeterminada de Compute Engine asociada con tu proyecto:
La cuenta de servicio predeterminada de Compute Engine tendrá un aspecto similar al siguiente:
project-number-compute@developer.gserviceaccount.com
Anota tu cuenta de servicio predeterminada de Compute Engine.
Abre la página de Secret Manager en la consola de Google Cloud:
Haz clic en el nombre del secreto que contiene el secreto del remitente. la contraseña de la cuenta de correo electrónico.
En la pestaña Permisos, haz clic en Agregar miembro.
Agrega la cuenta de servicio predeterminada de Compute Engine asociada con tu proyecto como miembro.
Selecciona el permiso Administrador y descriptor de acceso a secretos como la función.
Haz clic en Guardar.
Otorga permiso de lectura a tu cuenta de servicio de Cloud Run Buckets de Cloud Storage:
Ve a la página de IAM en la consola de Google Cloud:
Busca la cuenta de servicio predeterminada de Compute Engine asociada con tu proyecto:
La cuenta de servicio predeterminada de Compute Engine tendrá un aspecto similar al siguiente:
project-number-compute@developer.gserviceaccount.com
Haz clic en el ícono de lápiz en la fila que contiene tu cuenta de servicio predeterminada de Compute Engine. Verás la pestaña Editar acceso.
Haz clic en Agregar otra función.
Agrega la siguiente función:
- Visualizador de objetos de almacenamiento
Haz clic en Guardar.
Escribe un archivo de configuración de notificador para configurar tu notificador SMTP y filtrar los eventos de compilación:
En el siguiente ejemplo de archivo de configuración del notificador, el campo
filter
usa Common Expression Language con la variable disponible,build
, para filtrar los eventos de compilación con un estadoSUCCESS
: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://example-gcs-bucket/smtp.html secrets: - name: smtp-password value: projects/project-id/secrets/secret-name/versions/latest
Aquí:
buildStatus
es un parámetro definido por el usuario. Este parámetro adquiere el valor de $(build.status), el estado de la compilación.server-host-name
es la dirección de tu servidor SMTP.port
es el puerto que manejará las solicitudes SMTP. Este valor se debe especificar como una string.sender-email
es la dirección de correo electrónico de la cuenta del remitente que ve el server-host-name especificado.from-email
es la dirección de correo electrónico que ven los destinatarios.recipient-email
es una lista de una o más 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 electrónico del remitente almacenada en el Administrador de secretos. El nombre de la variable que especifiques aquí debe coincidir con el camponame
debajo desecrets
.project-id
es el ID de tu proyecto de Google Cloud.secret-name
es el nombre del secreto que contiene la contraseña de la cuenta de correo electrónico del remitente.El campo
uri
hace referencia al archivosmtp.html
. Este archivo hace referencia a una plantilla HTML alojada en Cloud Storage y representa tu correo electrónico de notificación.
Para ver el ejemplo, consulta el archivo de configuración del notificador para el notificador SMTP.
Para ver campos adicionales por los que puedes filtrar, consulta el recurso Compilar. Si deseas ver ejemplos de filtrado adicionales, consulta Usa CEL para filtrar eventos de compilación.
Sube tu archivo de configuración de notificador a un bucket de Cloud Storage:
Si no tienes un bucket de Cloud Storage, ejecuta el siguiente comando para crea un bucket, en el que
bucket-name
es el nombre que quieres asignarle a tu bucket, sujeto a los requisitos de nomenclatura.gcloud storage buckets create gs://bucket-name/
Sube el archivo de configuración del notificador a tu bucket:
gcloud storage cp config-file-name gs://bucket-name/config-file-name
Aquí:
bucket-name
es el nombre de tu depósito.config-file-name
es el nombre de tu archivo de configuración.
Implementa tu notificador en Cloud Run.
gcloud run deploy service-name \ --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/smtp:latest \ --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
Aquí:
service-name
es el nombre del servicio de Cloud Run en el que se implementa la imagen.config-path
es la ruta al archivo de configuración del notificador para tu notificador SMTP,gs://bucket-name/config-file-name
.project-id
es el ID de tu proyecto de Google Cloud.
El comando
gcloud run deploy
extrae la última versión de la imagen alojada de Artifact Registry de Cloud Build. Cloud Build es compatible con imágenes de notificador durante nueve meses. Después de nueve meses, Cloud Build borra la versión con imágenes. Si deseas usar una versión con imágenes anterior, deberás especificar la versión semántica completa de la etiqueta de imagen en el atributoimage
de tu comandogcloud run deploy
. Puedes encontrar etiquetas y versiones con imágenes anteriores en Artifact Registry.Otorga permisos de Pub/Sub para crear tokens de autenticación en tu proyecto:
gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator
Aquí:
project-id
es el ID de tu proyecto de Google Cloud.project-number
es el número de proyecto de Google Cloud.
Crea una cuenta de servicio para representar tu identidad de 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 dentro de tu proyecto de Google Cloud.Otorga el permiso
Invoker
de Cloud Run a la cuenta de servicio decloud-run-pubsub-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
Aquí:
service-name
es el nombre del servicio de Cloud Run en el que se implementa la imagen.project-id
es el ID de tu proyecto de Google Cloud.
Crea el tema
cloud-builds
a fin de recibir mensajes de actualización de compilación para tu notificador:gcloud pubsub topics create cloud-builds
Crea un suscriptor de envío 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
Aquí:
subscriber-id
es el nombre que quieres darle a tu suscripción.service-url
es la URL generada por Cloud Run para tu nuevo servicio.project-id
es el ID de tu proyecto de Google Cloud.
Las notificaciones de tu proyecto de Cloud Build ya están configuradas. La próxima vez que invoques una compilación, los recipients
especificados recibirán un correo electrónico con una notificación si la compilación coincide con el filtro que configuraste.
Usa CEL para filtrar eventos de compilación
Cloud Build usa CEL con la variable, build
, en los campos enumerados en el recurso Build para acceder a los campos asociados con el evento de compilación, como el ID del activador, la lista de imágenes o los valores de sustitución. Puedes usar la string filter
para filtrar los eventos de compilación en tu archivo de configuración de compilación con cualquier campo enumerado en el recurso compilación. Para encontrar la sintaxis exacta asociada con tu campo, consulta la
cloudbuild.proto
.
Filtrado por ID de activador
Para filtrar por ID de activador, especifica ese valor en el campo filter
mediante build.build_trigger_id
, en el que trigger-id
es tu ID de activador como una string:
filter: build.build_trigger_id == trigger-id
Cómo filtrar por estado
Para filtrar por estado, especifica el estado de compilación que deseas filtrar en el campo filter
mediante build.status
.
En el siguiente ejemplo, se muestra cómo filtrar eventos de compilación con un estado SUCCESS
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 tengan un estado SUCCESS
, FAILURE
o TIMEOUT
mediante el campo filter
:
filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]
Para ver los valores de estado adicionales por los que puedes filtrar, consulta Estado en la referencia del recurso Compilar.
Filtrado por etiqueta
Para filtrar por etiqueta, especifica el valor de tu etiqueta en el campo filter
con build.tags
, en el que tag-name
es el nombre de tu etiqueta:
filter: tag-name in build.tags
Puedes filtrar según la cantidad de etiquetas especificadas en tu evento de compilación mediante size
. En el siguiente ejemplo, el campo filter
filtra los eventos de compilación que tienen exactamente dos etiquetas especificadas con una etiqueta especificada como v1
:
filter: size(build.tags) == 2 && "v1" in build.tags
Filtrado por imágenes
Para filtrar por imágenes, especifica su valor en el campo filter
con build.images
, donde image-name
es el nombre completo
de la imagen como se muestra 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
ya sea us-east1-docker.pkg.dev/my-project/docker-repo/image-one
o
us-east1-docker.pkg.dev/my-project/docker-repo/image-two
especificado como
Nombres de imágenes:
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
Filtrado por tiempo
Puedes filtrar eventos de compilación en función de la hora de creación, de inicio o de finalización de la compilación si especificas 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
con el fin de filtrar los eventos de compilación con un tiempo de solicitud para crear la compilación el 20 de julio de 2020 a las 6:00 a.m.
filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")
También puedes filtrar eventos de compilación por comparaciones de tiempo. En el siguiente ejemplo, el campo filter
usa timestamp
para filtrar los eventos de compilación con una hora de inicio entre el 20 de julio de 2020 a las 6:00 a.m. y el 30 de julio de 2020 a las 6:00 a.m.
filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")
Si deseas obtener más información sobre cómo se expresan las zonas horarias en CEL, consulta la definición del lenguaje para zonas horarias.
Para filtrar por duración de una compilación, puedes usar duration
a fin de comparar marcas de tiempo.
En el siguiente ejemplo, el campo filter
usa duration
para filtrar eventos de compilación con compilaciones que se ejecutan durante al menos cinco minutos:
filter: build.finish_time - build.start_time >= duration("5m")
Filtrado por sustituciones
Para filtrar por sustitución, especifica la variable de sustitución en el campo filter
mediante build.substitutions
. En el siguiente ejemplo, el campo filter
enumera las compilaciones que contienen la variable de reemplazo substitution-variable y verifica si substitution-variable coincide con el substitution-value especificado:
filter: build.substitutions[substitution-variable] == substitution-value
Aquí:
substitution-variable
es el nombre de tu variable de sustitución.substitution-value
es el nombre de tu valor de reemplazo.
También puedes filtrar por valores de variable de sustitución predeterminados. En el siguiente ejemplo, el campo filter
enumera las compilaciones que tienen el nombre de la rama master
y las compilaciones que tienen el nombre del repositorio github.com/user/my-example-repo
. Las variables de reemplazo predeterminadas BRANCH_NAME
y REPO_NAME
se pasan como claves a build.substitutions
:
filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"
Si deseas filtrar en strings mediante expresiones regulares, puedes usar la función integrada matches
. En el siguiente ejemplo, el campo filter
filtra las compilaciones con un estado de FAILURE o TIMEOUT, y que también tiene 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 valores de sustituciones predeterminadas, consulta Usa sustituciones predeterminadas.
¿Qué sigue?
- Obtén más información sobre los notificadores de Cloud Build.
- Obtén más información sobre cómo suscribirte a las notificaciones de compilación.
- Aprende a escribir un archivo de configuración de compilación de Cloud Build.