Configurar notificaciones de BigQuery

Cloud Build puede enviarte notificaciones sobre las actualizaciones de compilación a canales específicos, como Slack o tu servidor SMTP. En esta página se explica cómo configurar notificaciones con el notificador de BigQuery.

El notificador de BigQuery te permite especificar filtros para las compilaciones que quieras almacenar en tu base de datos. Por ejemplo, puedes agrupar compilaciones por ID de activador, etiquetas o valores de sustitución. El notificador de BigQuery también escribe datos en BigQuery en un formato estandarizado que incluye campos calculados a los que no se puede acceder inmediatamente en el objeto Build, como el tamaño de la imagen o la duración de la ejecución. Si quiere saber cómo exportar entradas de registro a BigQuery u otro destino, consulte Exportar registros con la consola Google Cloud .

Antes de empezar

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

    Enable the APIs

Configurar notificaciones de BigQuery

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

Para configurar las notificaciones de BigQuery, siga estos pasos:

  1. Da permiso a tu cuenta de servicio de Cloud Run para crear y escribir tablas de BigQuery, para obtener datos de Artifact Registry relacionados con tu compilación y para leer y escribir en 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 los siguientes roles:

      • Lector de Artifact Registry
      • Editor de datos de BigQuery
      • Lector de objetos de Storage

      El rol Lector de Artifact Registry te permite obtener datos de tus imágenes. El rol Editor de datos de BigQuery le permite leer y escribir datos. El rol Visor de objetos de Storage te da acceso de lectura a los objetos de Cloud Storage.

    6. Haz clic en Guardar.

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

    En el siguiente ejemplo de archivo de configuración de notificador, el campo filter usa Common Expression Language con la variable build para filtrar eventos de compilación con un ID de activador especificado:

    apiVersion: cloud-build-notifiers/v1
kind: BigQueryNotifier
metadata:
  name: example-bigquery-notifier
spec:
  notification:
    filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000"
    params:
      buildStatus: $(build.status)
    delivery:
      table: projects/project-id/datasets/dataset-name/tables/table-name
    template:
      type: golang
      uri: gs://bucket_name/bq.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.
    • bucket-name es el nombre de tu segmento.
    • project-id es el ID de tu Google Cloud proyecto.
    • dataset-name es el nombre que quieres dar al conjunto de datos.
    • table-name es el nombre que quieres dar a la tabla.

    • El campo uri hace referencia al archivo bq.json. Este archivo hace referencia a una plantilla JSON alojada en Cloud Storage y representa la información que se va a insertar en tu tabla de BigQuery.

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

    El table-name de tu archivo de configuración de notificaciones puede hacer referencia a lo siguiente:

    • una tabla que no existe
    • una tabla vacía sin esquema

    • una tabla que ya exista con un esquema que coincida con las especificaciones del esquema del notificador de BigQuery

    Le recomendamos que especifique el ID del activador de compilación como filtro, ya que así podrá correlacionar los datos de compilación de sus activadores. También puede especificar varios IDs de activador en una lista: build.build_trigger_id in ["example-id-123", "example-id-456"].

    Para obtener el ID de tu activador, ejecuta el siguiente comando, donde trigger-name es el nombre de tu activador:

    gcloud builds triggers describe trigger-name

    El comando mostrará los campos asociados a tu activador, incluido su ID.

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

    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, la tabla se actualizará con los datos más recientes que coincidan con el filtro que hayas configurado para tu notificador de BigQuery.

Ver datos de compilación

Para ver los datos de compilación en BigQuery, sigue estos pasos:

  1. Abre la página de la consola de BigQuery:

    Abre la página de BigQuery

  2. En Recursos, haga clic en el ID de proyecto que usa para configurar su notificador de BigQuery.

  3. Haga clic en el nombre del conjunto de datos.

  4. Haz clic en el nombre de la tabla.

Ahora puedes ver información relacionada con tu tabla, incluido su esquema, y una vista previa de los datos de compilación tal como se muestran en la tabla.

Acceder a los datos de compilación

Puedes consultar los datos de tu tabla con la herramienta de línea de comandos bq o la consola de BigQuery.

CLI

Para consultar datos de tu tabla con la herramienta de línea de comandos bq, ejecuta el siguiente comando en tu terminal, donde sql-query es tu consulta:

bq query sql-query

Si tienes pensado usar los ejemplos de consulta de esta página, asegúrate de especificar la marca --nouse_legacy_sql en tu comando. La herramienta de línea de comandos bq usa SQL antiguo, mientras que las consultas de ejemplo no. Ejecuta el siguiente comando en tu terminal para consultar datos sin usar SQL antiguo:

bq query sql-query --nouse_legacy_sql

Consola

Para consultar datos de tu tabla mediante la consola de BigQuery, sigue estos pasos:

  1. Abre la página de la consola de BigQuery:

    Abre la página de BigQuery

  2. En Recursos, haz clic en el nombre de la tabla que quieras consultar.

  3. Escribe tu consulta de SQL en el editor de consultas.

Usar consultas para acceder a los datos de compilación

Las siguientes consultas de ejemplo muestran cómo puede acceder a los datos de compilación de su evento de compilación después de configurar el notificador de BigQuery:

Historial de compilación general

SELECT * FROM `projectID.datasetName.tableName`

Número de compilaciones agrupadas por estado

SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS

Frecuencia de despliegue diaria de la semana en curso

SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
      DATETIME_TRUNC(CreateTime, DAY) AS DAY,
      STATUS
      FROM `projectID.datasetName.tableName`
      WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY

Para ver más ejemplos de consultas, consulta el archivo README de Cloud Build BigQuery Notifier en el repositorio cloud-build-notifiers de GitHub. Para obtener más información sobre cómo consultar datos con BigQuery, consulte el artículo Consultar y ver datos.

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