Configurare le notifiche di BigQuery

Cloud Build può inviarti notifiche sugli aggiornamenti delle build a canali specifici, come Slack o il tuo server SMTP. Questa pagina spiega come configurare le notifiche utilizzando il notificatore BigQuery.

Il notificatore BigQuery ti consente di specificare i filtri per le build che vuoi archiviare nel database. Ad esempio, puoi raggruppare le build per ID trigger, tag o valori di sostituzione. Il notificatore BigQuery scrive anche i dati in BigQuery in un formato standardizzato che include campi calcolati non immediatamente accessibili nell'oggetto Build, come le dimensioni dell'immagine o la durata dell'esecuzione. Se vuoi scoprire come esportare le voci di log in BigQuery o in un'altra destinazione, consulta Esportare i log con la Google Cloud console.

Prima di iniziare

  • Abilita le API Cloud Build, Cloud Run, Pub/Sub e BigQuery.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

Configurazione delle notifiche di BigQuery

La sezione seguente spiega come configurare manualmente le notifiche HTTP utilizzando il notificatore BigQuery. Se preferisci automatizzare la configurazione, consulta Automatizzare la configurazione per le notifiche.

Per configurare le notifiche di BigQuery:

  1. Concedi al account di servizio di Cloud Run l'autorizzazione per creare e scrivere tabelle BigQuery, l'autorizzazione per recuperare i dati di Artifact Registry relativi alla build e l'accesso in lettura e scrittura ai bucket Cloud Storage:

    1. Vai alla pagina IAM nella Google Cloud console:

      Apri la pagina IAM

    2. Individua il service account predefinito di Compute Engine associato al tuo progetto:

      Il service account predefinito di Compute Engine avrà un aspetto simile al seguente:

      project-number-compute@developer.gserviceaccount.com

    3. Fai clic sull'icona a forma di matita nella riga contenente il service account predefinito di Compute Engine. Verrà visualizzata la scheda Accesso in modifica.

    4. Fai clic su Aggiungi un altro ruolo.

    5. Aggiungi i seguenti ruoli:

      • Lettore di Artifact Registry
      • Editor dati BigQuery
      • Visualizzatore oggetti Storage

      Il ruolo Lettore di Artifact Registry ti consente di recuperare i dati per le immagini. Il ruolo Editor dati BigQuery ti consente di accedere in lettura e scrittura ai tuoi dati. Il ruolo Visualizzatore oggetti Storage ti consente di accedere in lettura agli oggetti Cloud Storage.

    6. Fai clic su Salva.

  2. Scrivi un file di configurazione del notificatore per configurare il notificatore BigQuery e filtrare gli eventi di build:

    Nel seguente file di configurazione del notificatore di esempio, il campo filter utilizza Common Expression Language con la variabile build per filtrare gli eventi di build con un ID trigger specificato:

    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

    Dove:

    • buildStatus è un parametro definito dall'utente. Questo parametro assume il valore di ${build.status}, lo stato della build.
    • bucket-name è il nome del bucket.
    • project-id è l'ID del tuo Google Cloud progetto.
    • dataset-name è il nome che vuoi assegnare al set di dati.
    • table-name è il nome che vuoi assegnare alla tabella.

    • Il campo uri fa riferimento al file bq.json. Questo file fa riferimento a un modello JSON ospitato in Cloud Storage e rappresenta le informazioni da inserire nella tabella BigQuery.

    Per visualizzare un esempio di file modello, consulta il bq.json file nel repository cloud-build-notifiers-repository.

    Il table-name nel file di configurazione del notificatore può fare riferimento a:

    • Una tabella inesistente
    • Una tabella vuota senza schema

    • Una tabella esistente con uno schema che corrisponde alle specifiche dello schema nel notificatore BigQuery

    Ti consigliamo di specificare l'ID trigger di build come filtro, perché ti consente di correlare i dati di build per i trigger. Puoi anche specificare più ID trigger in un elenco: build.build_trigger_id in ["example-id-123", "example-id-456"].

    Per ottenere l'ID trigger, esegui il seguente comando, dove trigger-name è il nome del trigger:

    gcloud builds triggers describe trigger-name

    Il comando elencherà i campi associati al trigger, incluso l'ID trigger.

    Per visualizzare l'esempio, consulta il file di configurazione del notificatore per il notificatore BigQuery.

    Per altri campi in base ai quali puoi filtrare, consulta la risorsa Build. Per altri esempi di filtro, consulta Utilizzare CEL per filtrare gli eventi di build.

  3. Carica il file di configurazione del notificatore in un bucket Cloud Storage:

    1. Se non hai un bucket Cloud Storage, esegui il seguente comando per crearne uno, dove bucket-name è il nome che vuoi assegnare al bucket, soggetto ai requisiti di denominazione.

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

    2. Carica il file di configurazione del notificatore nel bucket:

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

      Dove:

      • bucket-name è il nome del bucket.
      • config-file-name è il nome del file di configurazione del notificatore.

  4. Esegui il deployment del notificatore in 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

    Dove:

    • service-name è il nome del servizio Cloud Run in cui stai eseguendo il deployment dell'immagine.
    • config-path è il percorso del file di configurazione del notificatore per il notificatore BigQuery, gs://bucket-name/config-file-name.
    • project-id è l'ID del tuo Google Cloud progetto.

    Il comando gcloud run deploy esegue il pull dell'ultima versione dell'immagine ospitata da Artifact Registry di proprietà di Cloud Build. Cloud Build supporta le immagini dei notificatori per nove mesi. Dopo nove mesi, Cloud Build elimina la versione dell'immagine. Se vuoi utilizzare una versione precedente dell'immagine, devi specificare la versione semantica completa del tag dell'immagine nell'attributo image del comando gcloud run deploy. Le versioni e i tag delle immagini precedenti sono disponibili in Artifact Registry.

  5. Concedi le autorizzazioni Pub/Sub per creare token di autenticazione nel tuo Google Cloud progetto:

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

    Dove:

    • project-id è l'ID del tuo Google Cloud progetto.
    • project-number è il numero del tuo Google Cloud progetto.

  6. Crea un account di servizio per rappresentare l'identità della sottoscrizione Pub/Sub:

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

    Puoi utilizzare cloud-run-pubsub-invoker o un nome univoco all'interno del tuo progetto Google Cloud .

  7. Concedi al account di servizio cloud-run-pubsub-invoker l'autorizzazione Invoker di Cloud Run:

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

    Dove:

    • service-name è il nome del servizio Cloud Run in cui stai eseguendo il deployment dell'immagine.

    • project-id è l'ID del tuo Google Cloud progetto.

  8. Crea l'argomento cloud-builds per ricevere i messaggi di aggiornamento della build per il notificatore:

    gcloud pubsub topics create cloud-builds

    Puoi anche definire un nome argomento personalizzato nel file di configurazione della build in modo che i messaggi vengano inviati all'argomento personalizzato. In questo caso, devi creare un argomento con lo stesso nome argomento personalizzato:

    gcloud pubsub topics create topic-name

    Per saperne di più, consulta Argomenti Pub/Sub per le notifiche di build.

  9. Crea un sottoscrittore push Pub/Sub per il notificatore:

     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

    Dove:

    • subscriber-id è il nome che vuoi assegnare alla sottoscrizione.
    • service-url è l'URL generato da Cloud Run per il nuovo servizio.
    • project-id è l'ID del tuo Google Cloud progetto.

Le notifiche per il tuo progetto Cloud Build sono ora configurate.

La prossima volta che richiami una build, la tabella verrà aggiornata con i dati più recenti che corrispondono al filtro configurato per il notificatore BigQuery.

Visualizzare i dati di build

Per visualizzare i dati di build in BigQuery:

  1. Apri la pagina della console BigQuery:

    Apri la pagina BigQuery

  2. In Risorse, fai clic sull'ID progetto che utilizzi per configurare il tuo notificatore BigQuery.

  3. Fai clic sul nome del set di dati.

  4. Fai clic sul nome della tabella.

Ora puoi visualizzare le informazioni relative alla tabella, incluso lo schema e un'anteprima dei dati di build elencati nella tabella.

Accedere ai dati di build

Puoi eseguire query sui dati nella tabella utilizzando lo strumento a riga di comando bq o la console BigQuery.

CLI

Per eseguire query sui dati nella tabella utilizzando lo strumento a riga di comando bq, esegui il seguente comando nel terminale, dove sql-query è la query:

bq query sql-query

Se prevedi di utilizzare gli esempi di query in questa pagina, assicurati di specificare il --nouse_legacy_sql flag nel comando. Lo strumento a riga di comando bq utilizza SQL precedente, mentre le query di esempio no. Esegui il seguente comando nel terminale per eseguire query sui dati senza SQL precedente:

bq query sql-query --nouse_legacy_sql

Console

Per eseguire query sui dati nella tabella utilizzando la console BigQuery:

  1. Apri la pagina della console BigQuery:

    Apri la pagina BigQuery

  2. In Risorse, fai clic sul nome della tabella su cui vuoi eseguire la query.

  3. Scrivi la query SQL nell'editor di query.

Utilizzare le query per accedere ai dati di build

Le seguenti query di esempio mostrano come accedere ai dati di build per l'evento di build, dopo la configurazione del notificatore BigQuery:

Cronologia generale delle build

SELECT * FROM `projectID.datasetName.tableName`

Conteggio delle build raggruppate per stato

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

Frequenza di deployment giornaliera per la settimana corrente

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

Per visualizzare altri esempi di query, consulta il file README del notificatore BigQuery di Cloud Build nel repository cloud-build-notifiers su GitHub. Per saperne di più su come eseguire query sui dati utilizzando BigQuery, consulta Eseguire query e visualizzare i dati.

Utilizzare CEL per filtrare gli eventi di build

Cloud Build utilizza CEL con la variabile build nei campi elencati nella risorsa Build per accedere ai campi associati all'evento di build, come l'ID trigger, l'elenco delle immagini o i valori di sostituzione. Puoi utilizzare la filter stringa per filtrare gli eventi di build nel file di configurazione della build utilizzando qualsiasi campo elencato nella risorsa Build. Per trovare la sintassi esatta associata al campo, consulta il cloudbuild.proto file.

Filtrare per ID trigger

Per filtrare in base all'ID trigger, specifica il valore dell'ID trigger nel campo filter utilizzando build.build_trigger_id, dove trigger-id è l'ID trigger come stringa:

filter: build.build_trigger_id == trigger-id

Filtrare per stato

Per filtrare in base allo stato, specifica lo stato della build in base al quale vuoi filtrare nel campo filter utilizzando build.status.

L'esempio seguente mostra come filtrare gli eventi di build con stato SUCCESS utilizzando il campo filter:

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

Puoi anche filtrare le build con stati diversi. L'esempio seguente mostra come filtrare gli eventi di build con stato SUCCESS, FAILURE o TIMEOUT utilizzando il campo filter:

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

Per visualizzare altri valori di stato in base ai quali puoi filtrare, consulta Stato nella documentazione di riferimento della risorsa Build.

Filtrare per tag

Per filtrare in base al tag, specifica il valore del tag nel campo filter utilizzando build.tags, dove tag-name è il nome del tag:

filter: tag-name in build.tags

Puoi filtrare in base al numero di tag specificati nell'evento di build utilizzando size. Nell'esempio seguente, il campo filter filtra gli eventi di build che hanno esattamente due tag specificati, con un tag specificato come v1:

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

Filtrare per immagini

Per filtrare in base alle immagini, specifica il valore dell'immagine nel campo filter utilizzando build.images, dove image-name è il nome completo dell'immagine come elencato in Artifact Registry, ad esempio us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Nell'esempio seguente, il campo filter filtra gli eventi di build che hanno us-east1-docker.pkg.dev/my-project/docker-repo/image-one o us-east1-docker.pkg.dev/my-project/docker-repo/image-two specificati come nomi delle immagini:

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

Filtrare per ora

Puoi filtrare gli eventi di build in base all'ora di creazione, all'ora di inizio o all'ora di fine di una build specificando una delle seguenti opzioni nel campo filter: build.create_time, build.start_time o build.finish_time.

Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con un'ora di richiesta per creare la build il 20 luglio 2020 alle 06:00:

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

Puoi anche filtrare gli eventi di build in base ai confronti temporali. Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con un'ora di inizio compresa tra il 20 luglio 2020 alle 06:00 e il 30 luglio 2020 alle 06:00.

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

Per saperne di più su come vengono espressi i fusi orari in CEL, consulta la definizione del linguaggio per i fusi orari.

Per filtrare in base alla durata di una build, puoi utilizzare duration per confrontare i timestamp. Nell'esempio seguente, il campo filter utilizza duration per filtrare gli eventi di build con build che vengono eseguite per almeno cinque minuti:

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

Filtrare per sostituzione

Puoi filtrare per sostituzione specificando la variabile di sostituzione nel campo filter utilizzando build.substitutions. Nell'esempio seguente, il campo filter elenca le build che contengono la variabile di sostituzione substitution-variable e controlla se substitution-variable corrisponde al substitution-value:

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

Dove:

  • substitution-variable è il nome della variabile di sostituzione.
  • substitution-value è il nome del valore di sostituzione.

Puoi anche filtrare in base ai valori delle variabili di sostituzione predefinite. Nell'esempio seguente, il campo filter elenca le build con il nome del ramo master e le build con il nome del repository github.com/user/my-example-repo. Le variabili di sostituzione predefinite BRANCH_NAME e REPO_NAME vengono passate come chiavi a build.substitutions:

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

Se vuoi filtrare le stringhe utilizzando le espressioni regolari, puoi utilizzare la funzione integrata matches. Nell'esempio seguente, il campo filter filtra le build con stato FAILURE o TIMEOUT e che hanno anche una variabile di sostituzione della build TAG_NAME con un valore che corrisponde all'espressione regolare 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}$")

Per visualizzare un elenco dei valori di sostituzione predefiniti, consulta Utilizzare le sostituzioni predefinite.

Passaggi successivi