Creazione di un notifier personalizzato

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

In questa pagina viene spiegato come creare notifiche personalizzate.

Prima di iniziare

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

    Abilita le API

  • Installa il linguaggio di programmazione Go.

  • Installa Google Cloud CLI.

Configurazione

  1. Apri una finestra del terminale sul computer.

  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 aprila, 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 tua 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 il l'ultima versione delle notifiche:

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

Le dipendenze sono ora configurate e puoi creare un avviso personalizzato.

Creazione di un notifier personalizzato

cloud-build-notifiers contiene una directory lib/notifiers. Nella Directory lib/notifiers, vedrai un file denominato notifier.go. Questo contiene il framework che puoi usare per creare un avviso personalizzato.

Dovrai definire due metodi per creare un avviso 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'autore della notifica:

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

    Il metodo main usa il metodo Main definita nel file notifier.go, utilizzato per impostare i file binari delle notifiche.

  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 archivia come Predicato Expression Language 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 riportato di seguito, l'interfaccia di notifica viene definita utilizzando SetUp e il metodo SendNotification per stampare i log di build, con logger come nome dell'autore della notifica:

    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 essere simile al seguente file. In questo Ad esempio, logger è utilizzato come nome dell'autore della notifica.

    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 generatore di notifiche, puoi seguire le istruzioni riportate di seguito i passaggi seguenti per configurare l'avviso.

Configurazione delle notifiche

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

    Nel file di configurazione dell'autore della 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 ulteriori 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 generatore di notifiche in un bucket Cloud Storage:

    1. Se non hai un bucket Cloud Storage, esegui questo comando creare un bucket, dove BUCKET_NAME è il nome da assegnare al bucket, in base ai requisiti di denominazione.

      gcloud storage buckets create gs://BUCKET_NAME/

    2. Carica il file di configurazione dell'autore della notifica nel tuo bucket:

      gcloud storage 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 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, inserisci il percorso della 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à 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 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 build per l'autore della notifica:

    gcloud pubsub topics create cloud-builds

  8. Crea un sottoscrittore push di Pub/Sub per l'autore della 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 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 ora configurate. Il prossimo volta che richiami una build, riceverai una notifica sul tuo canale se corrisponde al filtro configurato.

Notifiche di test

Per testare la funzionalità di notifica per l'esempio utilizzato in questa guida, puoi per richiamare una build 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 si trova success.yaml:

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

Nell'esempio seguente, specifichiamo failure.yaml come configurazione del tuo percorso di apprendimento. L'esecuzione di questo comando dovrebbe causare un errore nella 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 notificatore 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