Configurare le notifiche SMTP

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Cloud Build può inviarti notifiche sugli aggiornamenti della build inviando le notifiche ai canali desiderati, ad esempio Slack o il tuo server SMTP. Questa pagina spiega come configurare le notifiche utilizzando il rilevatore SMTP.

Prima di iniziare

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

    Abilita le API

Configurazione delle notifiche via email

Per inviare notifiche email, è necessario un server SMTP in esecuzione e l'accesso a un account su tale server, inclusi il nome utente e la password dell'account che verranno utilizzati per l'invio delle notifiche. Puoi utilizzare qualsiasi server SMTP esistente, ma devi 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 consegna del server SMTP possano gestire il volume di email che prevedi di generare.

La sezione che segue spiega come configurare manualmente le notifiche email utilizzando il rilevatore SMTP. Se invece vuoi automatizzare la configurazione, consulta l'articolo su come automatizzare la configurazione per le notifiche.

Per configurare le notifiche via email:

  1. Memorizza la password dell'account email del mittente in Secret Manager:

    1. Apri la pagina Secret Manager in Google Cloud Console:

      Apri la pagina di Secret Manager

    2. Fai clic su Crea secret.

    3. Inserisci un nome per il secret.

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

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

  2. Anche se il tuo account di servizio Cloud Run può avere il ruolo di Editor per il progetto, il ruolo di Editor non è sufficiente per accedere al secret in Secret Manager. Dovrai consentire al tuo account di servizio Cloud Run di accedere al secret:

    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
      

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

    3. Apri la pagina Secret Manager in Google Cloud Console:

      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 progetto come membro.

    7. Seleziona l'autorizzazione Secret Manager Secret Accessor come ruolo.

    8. Fai clic su Salva.

  3. Concedi al tuo account di servizio Cloud Run l'autorizzazione di lettura dai 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. Vedrai la scheda Accesso in modifica.

    4. Fai clic su Aggiungi un altro ruolo.

    5. Aggiungi il ruolo seguente:

      • Visualizzatore oggetti Storage
    6. Fai clic su Salva.

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

    Nel seguente file di configurazione del generatore di esempi, il campo filter utilizza il linguaggio di espressione comune con la variabile disponibile build per filtrare gli eventi di build con uno stato SUCCESS:

    apiVersion: cloud-build-notifiers/v1
    kind: SMTPNotifier
    metadata:
      name: example-smtp-notifier
    spec:
      notification:
        filter: build.status == Build.Status.SUCCESS
        delivery:
          server: server-host-name
          port: "port"
          sender: sender-email
          from: from-email
          recipients:
            - recipient-email
            # optional: more emails here
          password:
            secretRef: smtp-password
      secrets:
      - name: smtp-password
        value: projects/project-id/secrets/secret-name/versions/latest
    

    Dove:

    • 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 per ricevere i messaggi dal 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 Cloud.
    • secret-name è il nome del secret che contiene la password dell'account email del mittente.

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

    Per ulteriori campi in base ai quali puoi applicare un filtro, consulta la risorsa Build. Per altri esempi di filtro, consulta la pagina relativa all'utilizzo di CEL per filtrare gli eventi della build.

  5. Carica il file di configurazione del notificatore 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 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.
  6. Esegui il deployment del tuo 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 tuo notificatore SMTP gs://bucket-name/config-file-name.
    • project-id è l'ID del tuo progetto Cloud.

    Il comando gcloud run deploy estrae la versione più recente dell'immagine ospitata da Artifact Registry di proprietà di Cloud Build. Cloud Build supporta le immagini del notificatore 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.

  7. Concedi le autorizzazioni Pub/Sub per creare i 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.
  8. Crea un account di servizio che rappresenti l'identità dell'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 all'interno del 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 Cloud.
  10. Crea l'argomento cloud-builds per ricevere i messaggi di aggiornamento della build relativi alla tua notifica:

    gcloud pubsub topics create cloud-builds
    
  11. Crea un sottoscrittore push Pub/Sub per il notificante:

     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 dare all'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, il valore specificato recipients riceverà un'email con una notifica se la build corrisponde al filtro configurato.

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 al tuo evento di build, come il tuo 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 l'esatta sintassi associata al tuo campo, consulta il file cloudbuild.proto.

Filtrare per ID trigger

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

Applicazione dei filtri 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 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 uno 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 aggiuntivi di stato in base ai quali puoi applicare un filtro, consulta la sezione Stato sotto il riferimento alle risorse Build.

Applicazione di filtri in base al tag

Per filtrare in base al tag, specifica il valore del tag nel campo filter utilizzando build.tags, dove tag-name corrisponde al 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, il campo filter filtra i filtri per creare gli eventi con esattamente due tag specificati con un tag specificato come v1:

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

Filtrare in base alle 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 Container Registry, ad esempio gcr.io/example/image-one:

filter: image-name in build.images

Nel seguente esempio, filter filtra gli eventi di build con gcr.io/example/image-one o gcr.io/example/image-two specificati come nomi di immagini:

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

Filtrare in base all'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 della richiesta di creazione della build al 20 luglio 2020 alle 6:00:

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

Puoi anche filtrare gli eventi di build 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 il 20 e le 6:00 del 20 luglio 2020.

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 nel 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")

Filtrare 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 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. Nell'esempio seguente, il campo filter elenca le build che hanno il nome del ramo 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 passate come chiavi in 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 seguente, il campo filter filtra per le build con stato FAILURE o TIMEOUT e 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 di sostituzioni predefinite, vedi Utilizzare le sostituzioni predefinite.

Passaggi successivi