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

  • Aktivieren Sie die Cloud Build API, Cloud Run API, Pub/Sub API und Secret Manager API, falls sie noch nicht aktiviert sind.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    APIs aktivieren

  • Installieren Sie die Go-Programmiersprache.

  • 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, um sicherzustellen, dass Sie die aktuelle Version von Notifiers 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 Benachrichtigungssystems:

    type logger struct {
	filter notifiers.EventFilter
}

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

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

    • SendNotification: Die Methode SendNotification wird verwendet, um Benachrichtigungen an den ausgewählten Kanal oder Dienst zu senden.

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

      Im folgenden Beispiel wird die Notifier-Schnittstelle mit der Methode SetUp und der Methode SendNotification zum Ausgeben von Build-Logs definiert. logger ist der Name Ihres Notifiers:

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

      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 us-docker.pkg.dev/artifact-foundry-prod/docker-3p-trusted/golang@sha256:11fd8f7f63db3b6fb198797042ba4c40a4a34dc83325d3328ca3bc4bb7726786 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.

    Wenn Sie cloudbuild.yaml ausführen möchten, übergeben Sie den Benachrichtigungspfad als Substitutionsvariable.

     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

    Wobei:

    • PROJECT_ID ist die ID des 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 verwenden oder durch einen Namen ersetzen, der in Ihrem Google Cloud -Projekt eindeutig ist.

  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 des Google Cloud -Projekts.

  7. Erstellen Sie das Thema cloud-builds, um Build-Aktualisierungsnachrichten für Ihren Notifier zu empfangen:

    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=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

Dabei gilt: + SUBSCRIBER_ID ist der Name, den Sie dem Abo geben möchten. + SERVICE_URL ist die von Cloud Run generierte URL für den neuen Dienst. + PROJECT_ID ist die ID des Google Cloud -Projekts.

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

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

Wenn Sie Benachrichtigungen für das in dieser Anleitung verwendete Beispiel testen möchten, 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 die 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