Eigenen Notifier erstellen

Cloud Build kann Sie über Aktualisierungen bezüglich Ihres Build-Status informieren, indem Benachrichtigungen an ausgewählte Kanäle gesendet werden. Neben den von Cloud Build verwalteten Notifiern wie Slack oder SMTP können Sie auch die bereitgestellte Bibliothek im Repository cloud-build-notifiers verwenden, um einen eigenen Notifier zu erstellen.

Auf dieser Seite wird erläutert, wie Sie einen eigenen Notifier erstellen.

Hinweis

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

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the APIs

• Installieren Sie die Go-Programmiersprache.

  Hinweis: Cloud Build-Notifier werden in Go geschrieben. Um Ihren eigenen Notifier mit der vom cloud-build-notifiers-Repository bereitgestellten Bibliothek zu erstellen, müssen Sie Go auf Ihrem Computer installieren-

• Installieren Sie die Google Cloud CLI.

Einrichten

1. Öffnen Sie ein Terminalfenster auf Ihrem Computer.

2. Klonen Sie das Repository cloud-build-notifiers und gehen Sie zu diesem Repository:

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

3. Fügen Sie ein Verzeichnis für Ihren eigenen Notifier hinzu und rufen Sie dieses auf, wobei DIRECTORY_NAME der Name des Verzeichnisses ist:

     mkdir DIRECTORY_NAME && cd DIRECTORY_NAME
   

4. Initialisieren Sie Go-Module in Ihrem neuen Verzeichnis, wobei DIRECTORY_NAME der Name des neuen Verzeichnisses ist:

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

   Nun sollte eine go.mod-Datei in Ihrem Verzeichnis angezeigt werden.

5. Fügen Sie der Datei go.mod die folgende Zeile hinzu, damit Sie immer die neueste Version der Notifier verwenden:

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

Ihre Abhängigkeiten sind jetzt eingerichtet und Sie können einen eigenen Notifier erstellen.

Eigenen Notifier erstellen

cloud-build-notifiers enthält ein lib/notifiers-Verzeichnis. Im Verzeichnis lib/notifiers wird eine Datei namens notifier.go angezeigt. Diese Datei enthält das Framework, mit dem Sie einen eigenen Notifier erstellen können.

Sie müssen zwei Methoden definieren, um in der Hauptdatei einen Notifier zu erstellen.

1. Erstellen Sie im neuen Verzeichnis eine Datei mit dem Namen main.go.

2. Importieren Sie in main.go das Notifier-Bibliotheks-Framework und alle anderen Abhängigkeiten:

   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. Definieren Sie eine Hauptmethode für den Notifier. In diesem Beispiel ist logger der Name des Notifiers:

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

   Die main-Methode verwendet die in der Datei notifier.go definierte Main-Methode, um Notifier-Binärdateien einzurichten.

4. Definieren Sie eine Struktur für den Notifier, wo Sie die Variablen für Ihre Schnittstelle definieren. In diesem Beispiel ist logger der Name des Notifiers:

   type logger struct {
   	filter notifiers.EventFilter
   }
   

5. Fügen Sie die Benachrichtigungsfunktion hinzu. Die Notifier-Schnittstelle wird durch zwei Methoden definiert:

   • SetUp: Die Methode SetUp akzeptiert eine Konfiguration, ruft Secrets ab und ruft bestimmte Filter aus der Konfiguration ab. Außerdem wird sie als Prädikat der Common Expression Language gespeichert, das zum Senden von Benachrichtigungen verwendet werden kann. Weitere Informationen zu CEL finden Sie im Repository cel-spec.

   • SendNotification: Mit der SendNotification-Methode werden Benachrichtigungen an den ausgewählten Kanal oder Dienst gesendet.

     Die Definition des Notifiers ist in notifier.go und in der Go-Dokumentation verfügbar.

     Im folgenden Beispiel wird die Notifier-Schnittstelle mit den Methoden SetUp und SendNotification definiert, um Build-Logs auszugeben, wobei logger der Name des Notifiers ist:

     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
     }
     

     Die endgültige Datei main.go sollte in etwa so aussehen: In diesem Beispiel wird logger als Name des Notifiers verwendet.

     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
     }
     

   Konfigurieren Sie als Nächstes Ihren Notifier.

Benachrichtigungen konfigurieren

1. Schreiben Sie eine Notifier-Konfigurationsdatei, um Ihren Notifier zu konfigurieren und nach Build-Ereignissen zu filtern:

   In der folgenden Beispiel-Notifier-Konfigurationsdatei wird im Feld filter CEL mit der verfügbaren Variable build verwendet, um Build-Ereignisse mit dem Status SUCCESS zu filtern:

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

   Wobei:

   • logging-sample ist der Name des Notifiers.

   Weitere Felder, nach denen Sie filtern können, finden Sie in der Ressource Build. Weitere Filterbeispiele finden Sie unter CEL zum Filtern von Build-Ereignissen verwenden.

2. Laden Sie die Notifier-Konfigurationsdatei in einen Cloud Storage-Bucket hoch:

   1. Wenn Sie keinen Cloud Storage-Bucket haben, führen Sie den folgenden Befehl aus, um einen Bucket zu erstellen. Dabei ist BUCKET_NAME der Name, den Sie Ihrem Bucket gemäß den Vorgaben für die Benennung geben möchten.

      gcloud storage buckets create gs://BUCKET_NAME/
      

   2. Laden Sie die Konfigurationsdatei für den Notifier in Ihren Bucket hoch:

      gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME
      

      Hierbei gilt:

      • BUCKET_NAME ist der Name des Buckets.
      • CONFIG_FILE_NAME ist der Name Ihrer Konfigurationsdatei.

3. Erstellen Sie den Notifier und stellen Sie ihn bereit:

   1. Erstellen Sie ein Dockerfile für 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
      # Modify sources.list to point to the Debian archive
      RUN sed -i 's|deb.debian.org|archive.debian.org|g' /etc/apt/sources.list && \
          sed -i 's|security.debian.org|archive.debian.org/debian-security|g' /etc/apt/sources.list && \
          sed -i '/buster-updates/d' /etc/apt/sources.list && \
          echo "deb http://archive.debian.org/debian buster-updates main contrib non-free" >> /etc/apt/sources.list && \
          set -x && \
          apt-get update --allow-releaseinfo-change && \
          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. Erstellen Sie den Notifier mit der folgenden cloudbuild.yaml-Datei und stellen Sie ihn bereit.

      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

      Wobei:

      • _CONFIG_PATH ist der Pfad zu Ihrer Notifier-Konfiguration, z. B. gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

   Übergeben Sie den Notifier-Pfad als Substitutionsvariable, um cloudbuild.yaml auszuführen.

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

   Hinweis :Cloud Build hostet vorhandene Notifier-Images in Artifact Registry. Da Sie Ihren eigenen Notifier erstellen, anstatt einen Cloud Build-Host zu verwenden, müssen Sie den Notifier erstellen, um ein Notifier-Image zu erstellen. Ein Beispiel für eine cloudbuild.yaml-Datei für einen anderen Notifier-Typ, z. B. den slack-Notifier, finden Sie unter buildtest.cloudbuild.yaml. Ein Beispiel für das in der Datei buildtest.cloudbuild.yaml verwendete Dockerfile finden Sie unter Dockerfile.

4. Gewähren Sie Pub/Sub-Berechtigungen zum Erstellen von Authentifizierungstokens in Ihrem Projekt:

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

   Wobei:

   • PROJECT_ID ist die ID Ihres Google Cloud Projekts.
   • PROJECT_NUMBER ist Ihre Google Cloud Projektnummer.

5. Erstellen Sie ein Dienstkonto, das die Pub/Sub-Abonnementidentität darstellen soll:

   gcloud iam service-accounts create cloud-run-pubsub-invoker \
     --display-name "Cloud Run Pub/Sub Invoker"
   

   Sie können cloud-run-pubsub-invoker oder einen innerhalb Ihres Google Cloud -Projekts eindeutigen Namen verwenden.

6. Weisen Sie dem Dienstkonto cloud-run-pubsub-invoker die Cloud Run-Berechtigung Invoker zu:

   gcloud run services add-iam-policy-binding SERVICE_NAME \
      --member=serviceAccount:cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/run.invoker
   

   Hierbei gilt:

   • SERVICE_NAME ist der Name des Cloud Run-Dienstes, in dem Sie das Image bereitstellen.
   • PROJECT_ID ist die ID Ihres Google Cloud Projekts.

7. Erstellen Sie das Thema cloud-builds, um Build-Update-Nachrichten für Ihren Notifier zu erhalten:

   gcloud pubsub topics create cloud-builds
   

   Sie können auch einen benutzerdefinierten Themennamen in Ihrer Build-Konfigurationsdatei definieren, damit Nachrichten stattdessen an das benutzerdefinierte Thema gesendet werden. In diesem Fall würden Sie ein Thema mit demselben benutzerdefinierten Namen erstellen:

   gcloud pubsub topics create topic-name
   

   Weitere Informationen finden Sie unter Pub/Sub-Themen für Build-Benachrichtigungen.

8. Erstellen Sie einen Pub/Sub-Push-Abonnenten für Ihren Notifier:

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

   Hierbei gilt:

   • subscriber-id ist der Name, den Sie Ihrem Abo geben möchten.
   • service-url ist die von Cloud Run generierte URL für Ihren neuen Dienst.
   • project-id ist die ID Ihres Google Cloud Projekts.

Benachrichtigungen sind nun für Ihr Cloud Build-Projekt eingerichtet. Wenn Sie das nächste Mal einen Build aufrufen, erhalten Sie eine Benachrichtigung in Ihrem Kanal, wenn der Build dem von Ihnen konfigurierten Filter entspricht.

Testbenachrichtigungen

Zum Testen von Benachrichtigungen für das in dieser Anleitung verwendete Beispiel können Sie einen Build mit dem Befehl gcloud builds submit aufrufen.

Im folgenden Beispiel geben wir success.yaml als Konfigurationspfad an. Die Ausführung dieses Befehls sollte zu einem minimalen erfolgreichen Build führen. Sie sollten auch eine Ausgabe Ihrer Build-Logs sehen können.

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

Wo success.yaml Folgendes ist:

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

Im folgenden Beispiel geben wir failure.yaml als Konfigurationspfad an. Die Ausführung dieses Befehls sollte zu einem fehlgeschlagenen Build führen. Anstelle einer Ausgabe Ihrer Build-Logs werden Sie darüber informiert, dass für die von Ihnen in der Quelle angegebenen CEL-Filter keine Übereinstimmung vorliegt.

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

Wo failure.yaml Folgendes ist:

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

Wenn Sie einen Notifier erstellt haben, der für eine andere Aufgabe als das Logging der Ausgabe in Cloud Run-Dienstlogs konfiguriert ist, können Sie auch den Befehl gcloud builds submit ausführen, um Ihre Benachrichtigungen zu testen. Prüfen Sie die Cloud Run-Logs für Ihren Dienst, um die mit Ihrem Build verbundenen Fehler zu untersuchen. Weitere Informationen finden Sie unter Logs in Cloud Run ansehen.

Nächste Schritte

• Informationen zu Cloud Build-Benachrichtigungen
• Build-Benachrichtigungen abonnieren