Configurare le notifiche SMTP

Cloud Build può inviarti notifiche sugli aggiornamenti delle build inviando notifiche ai canali desiderati, ad esempio Slack o al server SMTP. In questa pagina viene spiegato come configurare le notifiche utilizzando lo strumento di notifica SMTP.

Prima di iniziare

  • Abilita le API Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager.

    Abilita le API

Configurazione delle notifiche email

Per inviare notifiche via email, devi disporre di un server SMTP in esecuzione e dell'accesso a un account su tale server, inclusi nome utente e password dell'account che verranno utilizzati per inviare notifiche. Puoi utilizzare qualsiasi server SMTP esistente, ma devi poter accedere al nome e alla porta del server. Ad esempio, il nome del server di Gmail è smtp.gmail.com e la porta è 587. Assicurati che le quote di recapito del server SMTP siano in grado di gestire il volume di email che prevedi di generare.

La seguente sezione spiega come configurare manualmente le notifiche email utilizzando il notifier SMTP. Se invece vuoi automatizzare la configurazione, consulta Automazione della configurazione per le notifiche.

Per configurare le notifiche via email:

  1. Archivia la password dell'account email del mittente in Secret Manager. Tieni presente che per Gmail dovrai utilizzare la password per l'app anziché la password di accesso dell'account.

    1. Apri la pagina di Secret Manager nella console Google Cloud:

      Apri la pagina di Secret Manager

    2. Fai clic su Crea secret.

    3. Inserisci un nome per il secret.

    4. In Valore secret, aggiungi la password dell'account email del mittente.

    5. Per salvare il secret, fai clic su Crea secret.

  2. Sebbene il tuo account di servizio Cloud Run possa avere il ruolo Editor per il progetto, il ruolo Editor non è sufficiente per accedere al secret in Secret Manager. Dovrai concedere al tuo account di servizio Cloud Run l'accesso al secret:

    1. Vai alla pagina IAM nella console Google Cloud:

      Apri la pagina IAM

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

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

      project-number-compute@developer.gserviceaccount.com
      

      Prendi nota del tuo account di servizio predefinito di Compute Engine.

    3. Apri la pagina di Secret Manager nella console Google Cloud:

      Apri la pagina di Secret Manager

    4. Fai clic sul nome del secret che contiene il secret per la password dell'account email del mittente.

    5. Nella scheda Autorizzazioni, fai clic su Aggiungi membro.

    6. Aggiungi l'account di servizio predefinito di Compute Engine associato al tuo progetto come membro.

    7. Seleziona l'autorizzazione Accessore ai secret di Secret Manager come ruolo.

    8. Fai clic su Salva.

  3. Autorizza il tuo account di servizio Cloud Run a leggere dai bucket Cloud Storage:

    1. Vai alla pagina IAM nella console Google Cloud:

      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 l'account di servizio predefinito di Compute Engine. Visualizzerai la scheda Modifica accesso.

    4. Fai clic su Aggiungi un altro ruolo.

    5. Aggiungi il seguente ruolo:

      • Visualizzatore oggetti Storage
    6. Fai clic su Salva.

  4. Scrivi un file di configurazione del notificante per configurare il notificatore SMTP e filtrare gli eventi di build:

    Nel file di configurazione del notificatore di esempio riportato di seguito, il campo filter utilizza il Common Expression Language con la variabile disponibile, build, per filtrare gli eventi di build con stato SUCCESS:

    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
    

    Dove:

    • buildStatus è un parametro definito dall'utente. Questo parametro assume il valore $(build.status), lo stato della build.
    • server-host-name è l'indirizzo del server SMTP.
    • port è la porta che gestirà le richieste SMTP. Questo valore deve essere specificato come stringa.
    • sender-email è l'indirizzo email dell'account del mittente visualizzato dal server-host-name specificato.
    • from-email è l'indirizzo email visualizzato dai destinatari.
    • recipient-email è un elenco di uno o più indirizzi email a cui ricevere i messaggi del mittente.
    • smtp-password è la variabile di configurazione utilizzata in questo esempio per fare riferimento alla password dell'account email del mittente archiviata in Secret Manager. Il nome della variabile specificato qui deve corrispondere al campo name in secrets.
    • project-id è l'ID del tuo progetto Google Cloud.
    • secret-name è il nome del secret che contiene la password dell'account email del mittente.
    • Il campo uri fa riferimento al file smtp.html. Questo file fa riferimento a un modello HTML ospitato su Cloud Storage e rappresenta la tua email di notifica.

    Per visualizzare l'esempio, vedi il file di configurazione del notificatore per il servizio di notifica SMTP.

    Per i campi aggiuntivi in base ai quali puoi filtrare, consulta la risorsa Crea. Per ulteriori esempi di filtro, consulta la sezione Utilizzare CEL per filtrare gli eventi di build.

  5. Carica il file di configurazione del notificante in un bucket Cloud Storage:

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

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

      gsutil 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.
  6. Esegui il deployment del notificante in 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
    

    Dove:

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

    • config-path è il percorso del file di configurazione del notificatore per il notificatore SMTP, gs://bucket-name/config-file-name.

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

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

  7. 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 Google Cloud.
    • project-number è il numero del tuo progetto Google Cloud.
  8. 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.

  9. 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 in cui esegui il deployment dell'immagine.
    • project-id è l'ID del tuo progetto Google Cloud.
  10. Crea l'argomento cloud-builds per ricevere messaggi di aggiornamento della build per l'autore delle notifiche:

    gcloud pubsub topics create cloud-builds
    
  11. Crea un sottoscrittore push Pub/Sub per l'autore delle notifiche:

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

Le notifiche per il tuo progetto Cloud Build sono state configurate. La prossima volta che richiami una build, l'elemento recipients specificato riceverà un'email con una notifica se la build corrisponde al filtro che hai configurato.

Utilizzo di 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 al tuo evento di build, come l'ID trigger, l'elenco di immagini o i valori di sostituzione. Puoi utilizzare la stringa filter per filtrare gli eventi di build nel file di configurazione della build utilizzando qualsiasi campo elencato nella risorsa Crea. Per trovare l'esatta sintassi associata al campo, consulta il file cloudbuild.proto.

Filtro per ID attivatore

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

filter: build.build_trigger_id == trigger-id

Filtro per stato

Per filtrare in base allo stato, specifica lo stato della build in base a cui vuoi applicare il filtro nel campo filter utilizzando 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 i valori di stato aggiuntivi in base ai quali puoi filtrare, consulta Stato nel riferimento della risorsa build.

Filtro 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 specificato 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

Filtro 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 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, filter filtra in base agli 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 di 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

Filtro per data/ora

Puoi filtrare gli eventi build in base all'ora di creazione, all'ora di inizio o 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 l'ora della 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 in base agli 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 scoprire di più su come i fusi orari sono espressi in CEL, consulta la definizione della lingua 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 una build eseguita per almeno cinque minuti:

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

Filtro per sostituzione

Puoi filtrare in base alla 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 verifica se substitution-variable corrisponde al 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 predefiniti della variabile di sostituzione. Nell'esempio seguente, il campo filter elenca le build che hanno il nome del ramo master e quelle che hanno il nome repository github.com/user/my-example-repo. Le variabili di sostituzione predefinite BRANCH_NAME e REPO_NAME vengono passate come chiavi al build.substitutions:

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

Se vuoi filtrare in base alle stringhe utilizzando espressioni regolari, puoi utilizzare la funzione matches integrata. Nell'esempio riportato di seguito, il campo filter filtra le build con stato ERRORE o TIMEOUT e che hanno anche una variabile di sostituzione della build TAG_NAME con un valore corrispondente 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 la sezione Utilizzare le sostituzioni predefinite.

Passaggi successivi