Configura notificaciones de BigQuery

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 mediante el notificador de BigQuery.

El notificador de BigQuery te brinda funcionalidad para especificar filtros en las compilaciones que deseas almacenar en tu base de datos. Por ejemplo, puedes agrupar compilaciones por ID de activación, 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 de inmediato en el objeto Build, como el tamaño de la imagen o la duración de la ejecución. Si deseas obtener información para exportar entradas de registro a BigQuery o a otro destino, consulta Exporta registros con Google Cloud Console.

Antes de comenzar

  • Habilita las API de Cloud Build, Cloud Run, Pub/Sub, and BigQuery.

    Habilita las API

Notificadores de Cloud Build

Cloud Build envía todas las actualizaciones de eventos de compilación, junto con los metadatos de compilación, a Pub/Sub en el tema cloud-builds. Los notificadores de Cloud Build pueden configurarse para escuchar ese tema, filtrar los mensajes que reciben y enviar mensajes a tu servicio.

Los notificadores de Cloud Build son imágenes de Docker que se pueden ejecutar como contenedores en Cloud Run. Cuando los sondea una aplicación de suscriptor, los notificadores de Cloud Build usan suscripciones de extracción para entregar mensajes al servicio configurado. Todos los notificadores usan una especificación YAML común para la configuración, almacenada en Cloud Storage.

Cloud Build proporciona y mantiene imágenes implementables del notificador en el repositorio cloud-build-notifiers. En la siguiente tabla, se enumeran los notificadores disponibles:

Notificador Descripción
bigquery Escribe datos de compilación en una tabla de BigQuery
http envía una carga útil JSON a otro extremo HTTP
slack usa un webhook de Slack para publicar mensajes en un canal de Slack
smtp envía correos electrónicos a través de un servidor SMTP

Configura notificaciones de BigQuery

En la siguiente sección, se explica cómo puedes configurar las notificaciones HTTP de forma manual con el notificador de BigQuery. En cambio, si deseas automatizar la configuración, consulta Automatiza la configuración para las notificaciones.

Para configurar las notificaciones de BigQuery, haz lo siguiente:

  1. Otorga permiso a tu cuenta de servicio de Cloud Run para crear y escribir tablas de BigQuery, permiso a fin de recuperar datos de Artifact Registry relacionados con tu compilación y acceso de lectura y escritura a los buckets de Cloud Storage:

    1. Ve a la página de IAM en Google Cloud Console:

      Abrir la página IAM

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

    4. Haz clic en Agregar otra función.

    5. Agrega las siguientes funciones:

      • Lector de Artifact Registry
      • Editor de datos de BigQuery
      • Visualizador de objetos de almacenamiento

      La función Lector de Artifact Registry te permite recuperar datos para tus imágenes. El editor de datos de BigQuery te brinda acceso de lectura y escritura a los datos. El Visualizador de objetos de Storage te brinda acceso de lectura y escritura a los objetos de Cloud Storage.

    6. Haga clic en Save.

  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 notificación, el campo filter usa Common Expression Language con la variable build para filtrar los 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"
        delivery:
          table: projects/project-id/datasets/dataset-name/tables/table-name
    

    Aquí:

    • project-id es el ID de tu proyecto de Cloud.
    • dataset-name es el nombre que deseas darle a tu conjunto de datos.
    • table-name es el nombre que deseas darle a tu tabla.

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

    • una tabla inexistente
    • una tabla vacía sin un esquema
    • una tabla existente con un esquema que coincida con las especificaciones del esquema en el notificador de BigQuery

    Te recomendamos que especifiques el ID del activador de compilación como tu filtro, ya que especificarlo te permite correlacionar datos de compilación para tus activadores. También puedes especificar varios ID de activador en una lista: build.build_trigger_id in ["example-id-123", "example-id-456"].

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

    Los activadores de la versión beta de gcloud describen trigger-name

    El comando enumerará los campos asociados con tu activador, incluido tu ID de activador.

    Si deseas ver el ejemplo, consulta el archivo de configuración de notificación para el notificador de BigQuery.

    Para ver campos adicionales por los que puedes filtrar, consulta el recurso Compilar. Para ver ejemplos adicionales de filtrado, consulta Cómo usar CEL para filtrar eventos de compilación.

  3. Sube tu archivo de configuración de notificador a un bucket de Cloud Storage:

    1. Si no tienes un depósito de Cloud Storage, ejecuta el siguiente comando para crear un depósito, en el que bucket-name es el nombre que deseas asignar a tu depósito, sujeto a los requisitos de nombres.

      gsutil mb gs://bucket-name/
      
    2. Sube el archivo de configuración del notificador a tu bucket:

      gsutil 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 de notificador.
  4. Implementa tu notificador en Cloud Run.

     gcloud run deploy service-name \
       --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/bigquery:latest \
       --no-allow-unauthenticated \
       --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 de tu notificador de BigQuery, gs://bucket-name/config-file-name.
    • project-id es el ID de tu proyecto de Cloud.

    El comando gcloud run deploy extrae la versión más reciente de tu imagen compilada de Artifact Registry. 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 atributo image de tu comando gcloud run deploy. Puedes encontrar etiquetas y versiones con imágenes anteriores en Artifact Registry.

  5. 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 Cloud.
    • project-number es el número de proyecto de Cloud.
  6. 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.

  7. Otorga el permiso Invoker de Cloud Run a la cuenta de servicio de cloud-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 Cloud.
  8. Después de habilitar la API de Pub/Sub, deberías ver el tema cloud-builds que se creó de forma automática en la página Temas de Pub/Sub. Si no ves el tema cloud-builds, ejecuta el siguiente comando para crear de forma manual el tema a fin de recibir mensajes sobre la actualización de la compilación para tu notificador:

    gcloud pubsub topics create cloud-builds
    
  9. 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 Cloud.

Las notificaciones de tu proyecto de Cloud Build ya están configuradas.

La próxima vez que invoques una compilación, tu tabla se actualizará con los datos más recientes que coincidan con el filtro que configuraste en el notificador de BigQuery.

Visualiza datos de compilación

Para ver los datos de compilación en BigQuery, haz lo siguiente:

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

    Abrir la página de BigQuery

  2. En Recursos, haz clic en el ID del proyecto que usas para configurar tu notificador de BigQuery.

  3. Haz clic en el nombre de tu conjunto de datos.

  4. Haz clic en el nombre de tu tabla.

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

Accede a los datos de compilación

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

CLI

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

bq query sql-query

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

bq query sql-query --nouse_legacy_sql

Console

Para consultar datos en tu tabla mediante Consola de BigQuery, haz lo siguiente:

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

    Abrir la página de BigQuery

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

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

Usa consultas para acceder a datos de compilación

En las siguientes consultas de ejemplo, se muestra cómo puedes acceder a los datos de compilación de tu evento de compilación según la configuración del notificador de BigQuery:

Historial de compilación general

SELECT * FROM `projectID.datasetName.tableName`

Recuentos de compilaciones agrupados por estado

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

Frecuencia de implementación diaria para la semana actual

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 consultas de ejemplo, consulta el archivo README del notificador de BigQuery Cloud Build en el repositorio cloud-build-notifiers en GitHub. Si deseas obtener más información para consultar datos con BigQuery, lee Consulta y visualiza datos.

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 Build. Para encontrar la sintaxis exacta asociada con tu campo, consulta el archivo 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 el valor de la imagen en el campo filter mediante build.images, en el que image-name es el nombre completo de tu imagen, como se muestra en Container Registry, como gcr.io/example/image-one:

filter: image-name in build.images

En el siguiente ejemplo, filter filtra en los eventos de compilación en los que se especificaron gcr.io/example/image-one o gcr.io/example/image-two como nombres de imagen:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" 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?