Eigene Benachrichtigung erstellen

Cloud Build kann Sie über Updates des Build-Status benachrichtigen, indem Sie Benachrichtigungen an die gewünschten Kanäle senden. Neben den von Cloud Build verwalteten Benachrichtigungen wie Slack oder SMTP können Sie auch die bereitgestellte Bibliothek in der Cloud verwenden -build-notifiers, um Ihren eigenen Notifier zu erstellen.

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

Hinweis

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

    Aktivieren Sie die APIs

  • Installieren Sie die Go-Programmiersprache.

  • Installieren Sie das Cloud SDK.

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 Ihres 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 => ../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 die Datei notifier.go angezeigt. Diese Datei enthält das Framework, mit dem Sie Ihren 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 "google.golang.org/genproto/googleapis/devtools/cloudbuild/v1"
            log "github.com/golang/glog"
            "github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
            "github.com/golang/protobuf/proto"
    )
  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, in der Sie die Variablen für Ihre Schnittstelle definieren. In diesem Beispiel ist logger der Name des Notifiers. Beispiel:

    type logger struct {
        filter notifiers.EventFilter
    }

Als Nächstes 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 speichert sie diese als Prädikat für allgemeine Ausdrücke, mit dem Benachrichtigungen gesendet werden können. Weitere Informationen zu CEL finden Sie im Repository cel-spec.
  • SendNotification: Mit der SendNotification-Methode werden Benachrichtigungen an den gewünschten 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", proto.MarshalTextString(build))
        } else {
            log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
        }
    
        return nil
    }

    Die letzte main.go-Datei sollte der folgenden Datei ähneln. In diesem Beispiel wird logger als Name des Notifers verwendet.

    package main
    
    import (
            "context"
            "fmt"
    
            cbpb "google.golang.org/genproto/googleapis/devtools/cloudbuild/v1"
            log "github.com/golang/glog"
            "github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
            "github.com/golang/protobuf/proto"
    )
    
    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", proto.MarshalTextString(build))
        } else {
            log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
        }
    
        return nil
    }

    Nachdem Sie den Notifier definiert haben, können Sie die folgenden Schritte ausführen, um den Notifier zu konfigurieren.

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

      gsutil mb gs://BUCKET_NAME/
      
    2. Laden Sie die Konfigurationsdatei für den Notifier in Ihren Bucket hoch:

      gsutil 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
      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. 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 den cloudbuild.yaml auszuführen.

     gcloud builds submit .  --substitutions=_CONFIG_PATH=gs://BUCKET_NAME/CONFIG_FILE_NAME
    
  4. Gewähren Sie Pub/Sub-Berechtigungen zum Erstellen von Authentifizierungstokens in Ihrem Projekt:

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
       --role=roles/iam.serviceAccountTokenCreator
    

    Hierbei gilt:

    • PROJECT_ID ist die ID Ihres Cloud-Projekts.
    • PROJECT_NUMBER ist die Nummer Ihres Cloud-Projekts.
  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 Cloud-Projekts.
  7. Nach der Aktivierung der Pub/Sub API sollte das automatisch erstellte Thema cloud-builds auf der Seite Pub/Sub-Themen angezeigt werden. Wenn das Thema cloud-builds nicht angezeigt wird, führen Sie den folgenden Befehl aus, um das Thema manuell zu erstellen und Build-Update-Nachrichten für Ihren Notifier zu erhalten:

    gcloud pubsub topics create cloud-builds
    
  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=cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com
    

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

Benachrichtigungen testen

Zum Testen der Benachrichtigungsfunktion 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 es keine Übereinstimmung mit den CEL-Filtern gibt, die Sie in Ihrer Quelle angegeben haben.

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 die Benachrichtigungsfunktion zu testen. Prüfen Sie die mit Ihrem Build verbundenen Fehler in den Cloud Run-Logs für Ihren Dienst. Weitere Informationen finden Sie unter Logs in Cloud Run ansehen.

Nächste Schritte