Creazione di un notifier personalizzato

Cloud Build può inviarti notifiche sugli aggiornamenti dello stato della build inviandoti notifiche ai canali che preferisci. Oltre a notifier gestiti da Cloud Build come Slack o SMTP puoi anche utilizzare la libreria fornita notifiche-cloud-build per creare un avviso personalizzato.

In questa pagina viene spiegato come creare notifiche personalizzate.

Prima di iniziare

  • Enable the Cloud Build, Cloud Run, Pub/Sub, and Secret Manager APIs.

    Enable the APIs

  • Installa il linguaggio di programmazione Go.

  • Installa Google Cloud CLI.

Configurazione

  1. Apri una finestra del terminale sulla tua macchina.

  2. Clona e vai al 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 notifier e accedivi, 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

    A questo punto dovresti vedere un file go.mod nella directory.

  5. Aggiungi la seguente riga al file go.mod per assicurarti di utilizzare la versione più recente dei notificatori:

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

Le dipendenze sono state configurate e puoi creare il tuo notifier.

Creazione di un notifier personalizzato

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

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

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

  2. In main.go, importa il framework della libreria di 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 il notificatore. In questo esempio, logger è il nome dell'avviso:

    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 configurare i file binari del notifier.

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

    type logger struct {
	filter notifiers.EventFilter
}

Successivamente, aggiungerai la funzionalità di notifica. L'interfaccia di notifica viene definita con due metodi:

  • SetUp: il metodo SetUp accetta una configurazione, recupera i secret, estrae i filtri specificati dalla configurazione e li memorizza come predicato del linguaggio Common Expression che può essere utilizzato per inviare notifiche. A Scopri di più su CEL, consulta il repository cel-spec.

  • SendNotification: il metodo SendNotification è quello che viene utilizzato Inviare notifiche al canale o al servizio desiderato.

    La definizione dell'autore della notifica è disponibile in notifier.go e nella documentazione di Go.

    Nell'esempio seguente, l'interfaccia del notificatore è definita utilizzando il metodo SetUp e SendNotification per stampare i log di compilazione, con logger come nome del notificatore:

    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 main.go finale dovrebbe avere il seguente aspetto. In questo esempio, logger viene utilizzato come nome del notificatore.

    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 il notificatore, puoi seguire la procedura riportata di seguito per configurarlo.

Configurazione delle notifiche

  1. Scrivi un file di configurazione dell'autore delle notifiche per configurare quest'ultimo e applicare un filtro creare eventi:

    Nel seguente esempio di file di configurazione del notifier, il campo filter utilizza CEL con la variabile disponibile build per filtrare gli eventi di compilazione con uno 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 altri campi 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 del notifier 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, rispettando i requisiti di denominazione.

      gcloud storage buckets create gs://BUCKET_NAME/

    2. Carica il file di configurazione del notifier 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.

  3. Crea ed esegui il deployment del notifier:

    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 dell'autore della notifica, ad esempio gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

    Per eseguire cloudbuild.yaml, passa il percorso del programma di notifica come variabile di sostituzione.

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

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

  5. Crea un account di servizio per rappresentare l'identità della tua 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 a cui stai eseguendo il deployment dell'immagine.
    • PROJECT_ID è l'ID del tuo progetto Google Cloud.

  7. Crea l'argomento cloud-builds per ricevere i messaggi di aggiornamento della compilazione per il tuo notifier:

    gcloud pubsub topics create cloud-builds

  8. Crea un abbonato push Pub/Sub per il tuo notifier:

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

Le notifiche per il tuo progetto Cloud Build sono state configurate. La volta successiva che esegui una compilazione, riceverai una notifica sul tuo canale se la compilazione corrisponde al filtro che hai configurato.

Notifiche di test

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

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

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

Dove success.yaml è:

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

Nell'esempio seguente, specifichiamo failure.yaml come percorso di configurazione. L'esecuzione di questo comando dovrebbe comportare un errore di build. Invece di un output dei log di build, vedrai un output che informa che non esisteva 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 avviso configurato per eseguire un'altra attività oltre al logging dell'output nei log di servizio Cloud Run, puoi anche eseguire il comando gcloud builds submit per testare le notifiche funzionalità. Per esaminare gli errori associati alla build, controlla i log di Cloud Run per il tuo servizio. Per saperne di più, vedi Visualizzazione dei log in Cloud Run.

Passaggi successivi