Configurazione delle notifiche di BigQuery

Cloud Build può inviarti notifiche in merito agli aggiornamenti delle build inviando le notifiche ai canali desiderati, come Slack o il server SMTP. In questa pagina viene spiegato come configurare le notifiche utilizzando il rilevatore BigQuery.

Il notificatore BigQuery consente di specificare i filtri sulle build da archiviare nel database. Ad esempio, puoi raggruppare le build per ID trigger, tag o valori di sostituzione. Il notificatore BigQuery scrive i dati in BigQuery in un formato standardizzato che include campi calcolati non immediatamente accessibili nell'oggetto Build, come la dimensione dell'immagine o la durata dell'esecuzione. Per informazioni su come esportare le voci di log in BigQuery o in un'altra destinazione, consulta Esportazione dei log con Google Cloud Console.

Prima di iniziare

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

    Abilita le API

Configurazione delle notifiche di BigQuery

La sezione seguente spiega come configurare manualmente le notifiche HTTP utilizzando il notatore BigQuery. Se invece vuoi automatizzare la configurazione, consulta l'articolo sull'automazione della configurazione per le notifiche.

Per configurare le notifiche BigQuery:

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

    1. Vai alla pagina IAM in Google Cloud Console:

      Apri la pagina IAM

    2. Individua l'account di servizio predefinito di Compute Engine associato al progetto:

      Il tuo account di servizio predefinito di Compute Engine sarà simile al seguente:

      project-number-compute@developer.gserviceaccount.com
      
    3. Fai clic sull'icona a forma di matita nella riga contenente il tuo account di servizio predefinito di Compute Engine. Viene visualizzata la scheda Modifica autorizzazioni.

    4. Fai clic su Aggiungi un altro ruolo.

    5. Aggiungi i seguenti ruoli:

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

      Il ruolo Lettore Artifact Registry ti consente di recuperare i dati delle tue immagini. L'editor di dati di BigQuery ti consente di accedere in lettura e scrittura ai dati. Il 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 abilitatore per configurare il tuo strumento di notifica BigQuery e filtrare i dati in eventi di build:

    Nel seguente file di configurazione del rilevatore di esempio, il campo filter utilizza il 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"
        delivery:
          table: projects/project-id/datasets/dataset-name/tables/table-name
    

    Dove:

    • project-id è l'ID del tuo progetto Cloud.
    • dataset-name è il nome che vuoi assegnare al tuo set di dati.
    • table-name è il nome che vuoi assegnare al tuo tavolo.

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

    • una tabella inesistente
    • una tabella vuota senza uno schema
    • una tabella esistente con uno schema che corrisponde alle specifiche dello strumento di notifica di BigQuery

    Ti consigliamo di specificare l'ID del trigger di build come filtro, poiché specificare il relativo ID ti consente di correlare i dati della build ai tuoi trigger. Puoi anche specificare più ID attivatore 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 tuo trigger:

    Gli attivatori delle build beta di gcloud descrivono trigger-name

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

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

    Per ulteriori campi in base ai quali è possibile applicare un filtro, consulta la risorsa Build. Per altri esempi di filtro, consulta la sezione Utilizzare la CEL per filtrare gli eventi di build.

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

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

      gsutil mb gs://bucket-name/
      
    2. Carica il file di configurazione del notificatore nel bucket:

      gsutil cp config-file-name gs://bucket-name/config-file-name
      

      Dove:

      • bucket-name è il nome del tuo bucket.
      • config-file-name è il nome del file di configurazione del notificatore.
  4. Esegui il deployment del tuo 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 a cui esegui il deployment dell'immagine.
    • config-path è il percorso del file di configurazione del tuo abilitatore BigQuery, gs://bucket-name/config-file-name.
    • project-id è l'ID del tuo progetto Cloud.

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

  5. Concedi le autorizzazioni Pub/Sub per creare token di autenticazione nel tuo 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 progetto Cloud.
    • project-number è il tuo numero di progetto Cloud.
  6. Crea un account di servizio per rappresentare la tua identità di abbonamento 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 utilizzare un nome univoco nel tuo progetto Google Cloud.

  7. Concedi all'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 a cui esegui il deployment dell'immagine.
    • project-id è l'ID del tuo progetto Cloud.
  8. Dopo aver attivato l'API Pub/Sub, dovresti vedere l'argomento cloud-builds creato automaticamente per te nella pagina Pub/Sub Argomenti. Se non vedi l'argomento cloud-builds, esegui il comando seguente per creare manualmente l'argomento per ricevere i messaggi di aggiornamento della build per la notifica.

    gcloud pubsub topics create cloud-builds
    
  9. Crea un sottoscrittore push Pub/Sub per il tuo strumento di notifica:

     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 a cui vuoi assegnare il tuo abbonamento.
    • service-url è l'URL generato da Cloud Run per il tuo nuovo servizio.
    • project-id è l'ID del tuo progetto Cloud.

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 corrispondenti al filtro configurato per l'autenticatore BigQuery.

Visualizzazione dei dati della build

Per visualizzare i dati della 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 tuo set di dati.

  4. Fai clic sul nome della tabella.

Ora puoi visualizzare informazioni relative alla tabella, compreso lo schema e un'anteprima dei dati di build, come elencato nella tabella.

Accesso ai dati della build

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

interfaccia a riga di comando

Per eseguire query sui dati nella tabella utilizzando lo strumento a riga di comando bq, esegui il comando seguente 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 da allora il flag --nouse_legacy_sql nel comando. Lo strumento a riga di comando bq utilizza il linguaggio SQL precedente, a differenza delle query di esempio. Esegui il comando seguente nel terminale per eseguire una query sui dati senza SQL precedente:

bq query sql-query --nouse_legacy_sql

console

Per eseguire una query sui dati della 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 una query.

  3. Scrivi la query SQL nell'editor Query.

Utilizzo delle query per accedere ai dati della build

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

Cronologia build complessiva

SELECT * FROM `projectID.datasetName.tableName`

Conteggio 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 altre query di esempio, vedi il documento Cloud Build BigQuery Envoy README nel repository cloud-build-notifiers su GitHub. Per scoprire di più su come eseguire query sui dati utilizzando BigQuery, consulta la sezione Eseguire query e visualizzare dati.

Utilizzo di CEL per filtrare gli eventi di build

Cloud Build utilizza CEL con la variabile build sui 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 stringa filter per filtrare gli eventi di build nel file di configurazione di compilazione utilizzando qualsiasi campo elencato nella risorsa Build. Per trovare la sintassi esatta associata al tuo campo, consulta il file cloudbuild.proto.

Filtrare per ID attivatore

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

filter: build.build_trigger_id == trigger-id

Filtrare per stato

Per filtrare in base allo stato, specifica nel campo filter lo stato della build in base a cui vuoi applicare l'applicazione build.status.

L'esempio seguente mostra come filtrare gli eventi di build con uno 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 dello stato in base ai quali puoi applicare il filtro, consulta la sezione Stato sotto il riferimento alla 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 riportato di seguito, i filtri del campo filter creano eventi con esattamente due tag specificati con un tag specificato come v1:

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

Filtrare tramite immagini

Per filtrare in base alle immagini, specifica il valore dell'immagine nel campo filter utilizzando build.images, dove image-name rappresenta il nome completo dell'immagine, come elencato in Container Registry, come gcr.io/example/image-one:

filter: image-name in build.images

Nell'esempio seguente, il filtro filter mostra gli eventi di build in cui gcr.io/example/image-one o gcr.io/example/image-two sono specificati come nomi di immagini:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Applicazione di filtri in base all'ora

Puoi filtrare gli eventi di build in base a un'ora di creazione, un'ora di inizio o una fine della build specificando una delle seguenti opzioni nel tuo 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 della richiesta per creare la build alle 06:00 del 20 luglio 2020:

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

Puoi anche filtrare gli eventi di compilazione in base a confronti in base all'ora. Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con un'ora di inizio tra le 06:00 del 20 luglio 2020 e delle ore 06:00 del 30 luglio 2020.

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

Per ulteriori informazioni su come i fusi orari vengono espressi in CEL, consulta la definizione della lingua dei 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 una build eseguita per almeno cinque minuti:

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

Filtrare in base alla 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 valore substitution-value specificato:

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 predefiniti. Nel seguente esempio, il campo filter elenca le build con il nome della filiale master e quelle che hanno il nome del repository github.com/user/my-example-repo. Le variabili di sostituzione predefinite BRANCH_NAME e REPO_NAME vengono trasmesse 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 espressioni regolari, puoi utilizzare la funzione matches integrata. Nell'esempio riportato di seguito, il campo filter filtra in base alle build con uno stato FAILURE o TIMEOUT, che hanno anche una variabile di sostituzione 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 Utilizzo di sostituzioni predefinite.

Passaggi successivi