Creazione di un notifier personalizzato

Cloud Build può inviarti notifiche sugli aggiornamenti allo stato della build inviandoti notifiche ai canali desiderati. Oltre ai notifiche gestiti da Cloud Build come Slack o SMTP, puoi anche utilizzare la libreria fornita nel repository cloud-build-notifiers per creare il tuo notificatore.

In questa pagina viene spiegato come creare un sistema di notifica personalizzato.

Prima di iniziare

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

  Abilita le API

• Installa il linguaggio di programmazione Go.

  Nota: i notificatori di Cloud Build sono scritti in Go. Per creare il tuo notificatore utilizzando la libreria fornita dal repository cloud-build-notifiers, devi installare Go sulla tua macchina.

• Installa Google Cloud CLI.

Configurazione in corso…

1. Apri una finestra del terminale sul computer.

2. Clona ed entra nel repository cloud-build-notifiers:

     git clone https://github.com/GoogleCloudPlatform/cloud-build-notifiers.git && cd cloud-build-notifiers
   

3. Aggiungi una directory per il tuo notificante e accedi a questa directory, dove DIRECTORY_NAME è il nome della directory:

     mkdir DIRECTORY_NAME && cd DIRECTORY_NAME
   

4. Inizializza i moduli Go nella nuova directory, dove DIRECTORY_NAME è il nome della nuova directory:

     go mod init github.com/GoogleCloudPlatform/cloud-build-notifiers/DIRECTORY_NAME
   

   Ora dovresti vedere un file go.mod nella tua directory.

5. Aggiungi la seguente riga al file go.mod per assicurarti di utilizzare la versione più recente degli strumenti di notifica:

    replace github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers => ../
   

Ora le dipendenze sono configurate ed è tutto pronto per creare il tuo notificatore.

Creazione di un notifier personalizzato

cloud-build-notifiers contiene una directory lib/notifiers. Nella directory lib/notifiers vedrai un file denominato notifier.go. Questo file contiene il framework che puoi utilizzare per creare il tuo sistema di notifica.

Dovrai definire due metodi per creare un notificatore nel file principale.

1. Nella nuova directory, crea un file denominato main.go.

2. In main.go, importa il framework della libreria delle notifiche e qualsiasi altra dipendenza:

   package main
   
   import (
   	"context"
   	"fmt"
   
   	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
   	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
   	log "github.com/golang/glog"
   	"google.golang.org/protobuf/encoding/prototext"
   )
   

3. Definisci un metodo principale per l'autore delle notifiche. In questo esempio, logger è il nome dell'autore delle notifiche:

   func main() {
   	if err := notifiers.Main(new(logger)); err != nil {
   		log.Fatalf("fatal error: %v", err)
   	}
   }
   

   Il metodo main utilizza il metodo Main definito nel file notifier.go, che viene utilizzato per impostare i programmi binari delle notifiche.

4. Definisci uno struct per il notificatore, in cui definire le variabili per l'interfaccia. In questo esempio, logger è il nome dell'autore delle notifiche. Ad es.

   type logger struct {
   	filter notifiers.EventFilter
   }
   

Successivamente, aggiungerai la funzionalità di notifica. L'interfaccia del notificatore è definita in due modi:

• SetUp: il metodo SetUp accetta una configurazione, recupera i secret ed estrae i filtri specificati dalla configurazione e li archivia come predicato Common Expression Language che può essere utilizzato per inviare notifiche. Per scoprire di più sul CEL, consulta il repository cel-spec.

• SendNotification: il metodo SendNotification viene utilizzato per inviare notifiche al canale o servizio desiderato.

  La definizione del notificante è disponibile in notifier.go e nella documentazione di Go.

  Nell'esempio riportato di seguito, l'interfaccia del notificante viene definita utilizzando i metodi SetUp e SendNotification per stampare i log di build, con logger come nome del notificante:

  func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
  	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
  	if err != nil {
  		return fmt.Errorf("failed to create CELPredicate: %w", err)
  	}
  	h.filter = prd
  	return nil
  }
  
  func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
  	// Include custom functionality here.
  	// This example logs the build.
  	if h.filter.Apply(ctx, build) {
  		log.V(1).Infof("printing build\n%s", prototext.Format(build))
  	} else {
  		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
  	}
  
  	return nil
  }
  

  Il file finale main.go dovrebbe avere un aspetto simile al seguente. In questo esempio, logger viene utilizzato come nome dell'autore delle notifiche.

  package main
  
  import (
  	"context"
  	"fmt"
  
  	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
  	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
  	log "github.com/golang/glog"
  	"google.golang.org/protobuf/encoding/prototext"
  )
  
  func main() {
  	if err := notifiers.Main(new(logger)); err != nil {
  		log.Fatalf("fatal error: %v", err)
  	}
  }
  
  type logger struct {
  	filter notifiers.EventFilter
  }
  
  func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
  	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
  	if err != nil {
  		return fmt.Errorf("failed to create CELPredicate: %w", err)
  	}
  	h.filter = prd
  	return nil
  }
  
  func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
  	// Include custom functionality here.
  	// This example logs the build.
  	if h.filter.Apply(ctx, build) {
  		log.V(1).Infof("printing build\n%s", prototext.Format(build))
  	} else {
  		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
  	}
  
  	return nil
  }
  

  Ora che hai definito l'autore delle notifiche, segui i passaggi riportati di seguito per configurarlo.

Configurazione delle notifiche

1. Scrivi un file di configurazione di notifica per configurare il notificatore e filtrare in base agli eventi di build:

   Nel file di configurazione delle notifiche di notifica di esempio riportato di seguito, il campo filter utilizza CEL con la variabile disponibile, build, per filtrare gli eventi di build con stato SUCCESS:

   apiVersion: cloud-build-notifiers/v1
   kind: YourNotifier
   metadata:
     name: logging-sample
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS

   Dove:

   • logging-sample è il nome dell'autore della notifica.

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

2. Carica il file di configurazione delle notifiche 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 delle notifiche 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.

3. Crea ed esegui il deployment del notificante:

   1. Crea un Dockerfile per logging-sample:

      
      FROM golang AS build-env
      COPY . /go-src/
      WORKDIR /go-src/
      RUN go build -o /go-app .
      
      # From the Cloud Run docs:
      # https://cloud.google.com/run/docs/tutorials/pubsub#looking_at_the_code
      # Use the official Debian slim image for a lean production container.
      # https://hub.docker.com/_/debian
      # https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
      FROM debian:buster-slim
      RUN set -x && apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y \
          ca-certificates && \
          rm -rf /var/lib/apt/lists/*
      
      FROM gcr.io/distroless/base
      COPY --from=build-env /go-app /
      ENTRYPOINT ["/go-app", "--v=1", "--alsologtostderr"]
      

   2. Crea ed esegui il deployment del notificatore utilizzando il seguente file cloudbuild.yaml.

      steps:
      - # Build the binary and put it into the builder image.
        name: gcr.io/cloud-builders/docker
        args: ['build', '--tag=gcr.io/$PROJECT_ID/logging-sample', '.']
      
      - # Push the container image to Container Registry
        name: gcr.io/cloud-builders/docker
        args: ['push', 'gcr.io/$PROJECT_ID/logging-sample']
      
      - # Deploy to Cloud Run
        name: google/cloud-sdk
        args:
          - gcloud
          - run
          - deploy
          - logging-sample-notifier
          - --platform=managed
          - --region=us-central1
          - --image=gcr.io/$PROJECT_ID/logging-sample
          - --no-allow-unauthenticated
          - --update-env-vars=CONFIG_PATH=${_CONFIG_PATH}
      
      # Push the image with tags.
      images:
      - gcr.io/$PROJECT_ID/logging-sample

      Dove:

      • _CONFIG_PATH è il percorso della configurazione del notificatore, ad esempio gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

   Per eseguire cloudbuild.yaml, trasmetti il percorso del notificante come variabile di sostituzione.

    gcloud builds submit .  --substitutions=_CONFIG_PATH=gs://BUCKET_NAME/CONFIG_FILE_NAME
   

   Nota: Cloud Build ospita immagini di notifica esistenti in Artifact Registry. Poiché stai creando un notificatore invece di utilizzare un host Cloud Build, devi creare il tuo notificatore per creare un'immagine di notifica. Per un esempio di file cloudbuild.yaml per un altro tipo di notifica, ad esempio il notificatore slack, vai alla pagina buildtest.cloudbuild.yaml. Per visualizzare un esempio di Dockerfile utilizzato nel file buildtest.cloudbuild.yaml, consulta Dockerfile.

4. Concedi le autorizzazioni Pub/Sub per creare token di autenticazione nel progetto:

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:[e-mail] \
      --role=roles/iam.serviceAccountTokenCreator
   

   Dove:

   • PROJECT_ID è l'ID del tuo progetto Google Cloud.
   • PROJECT_NUMBER è il numero di progetto Google Cloud.

5. Crea un account di servizio per rappresentare la tua identità di 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.

6. 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.

7. Crea l'argomento cloud-builds per ricevere messaggi di aggiornamento della build per il dispositivo di notifica:

   gcloud pubsub topics create cloud-builds
   

8. Crea un sottoscrittore push di Pub/Sub per il tuo soggetto di notifica:

    gcloud pubsub subscriptions create subscriber-id \
      --topic=cloud-builds \
      --push-endpoint=service-url \
      --push-auth-service-account=[e-mail]
   

   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 ora configurate. La prossima volta che richiami una build, riceverai una notifica nel tuo canale se la build corrisponde al filtro che hai configurato.

Test delle notifiche

Per testare la funzionalità di notifica per l'esempio utilizzato in questa guida, puoi richiamare una build eseguendo il comando gcloud builds submit.

Nell'esempio seguente, specifichiamo success.yaml come percorso di configurazione. L'esecuzione di questo comando dovrebbe comportare una build minima riuscita. Dovresti anche essere in grado di visualizzare un output dei log di build.

 gcloud builds submit --no-source --config=success.yaml

Dove si trova success.yaml:

 steps:
 - name: busybox
   args: ["true"]

Nell'esempio seguente, specifichiamo failure.yaml come percorso di configurazione. L'esecuzione di questo comando dovrebbe comportare una build non riuscita. Invece di visualizzare un output dei log di build, vedrai un output che indica che non è stata trovata una corrispondenza per i filtri CEL specificati nell'origine.

gcloud builds submit --no-source --config=failure.yaml

Dove si trova failure.yaml:

 steps:
 - name: busybox
   args: ["false"]

Se hai creato un notificatore configurato per eseguire un'altra attività diversa dal logging dell'output nei log di servizio di Cloud Run, puoi anche eseguire il comando gcloud builds submit per testare la funzionalità di notifica. Per esaminare gli errori associati alla tua build, controlla i log di Cloud Run per il tuo servizio. Per saperne di più, consulta Visualizzazione dei log in Cloud Run.

Passaggi successivi

• Scopri di più sui notifiche di Cloud Build.
• Scopri come iscriverti per ricevere notifiche relative alla build.