Membuat pemberi notifikasi sendiri

Cloud Build dapat memberi tahu Anda tentang pembaruan status build dengan mengirim notifikasi ke saluran yang diinginkan. Selain pemberitahuan yang dikelola oleh Cloud Build seperti Slack atau SMTP, Anda juga dapat menggunakan library yang disediakan di repositori cloud-build-notifiers untuk membuat pemberitahuan Anda sendiri.

Halaman ini menjelaskan cara membuat notifikasi Anda sendiri.

Sebelum memulai

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

    Enable the APIs

  • Instal bahasa pemrograman Go.

  • Instal Google Cloud CLI.

Menyiapkan

  1. Buka jendela terminal di perangkat Anda.

  2. Clone dan buka repositori cloud-build-notifiers:

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

  3. Tambahkan direktori untuk notifikasi Anda sendiri dan buka direktori tersebut, dengan DIRECTORY_NAME adalah nama direktori Anda:

      mkdir DIRECTORY_NAME && cd DIRECTORY_NAME

  4. Lakukan inisialisasi modul go di direktori baru, dengan DIRECTORY_NAME adalah nama direktori baru Anda:

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

    Sekarang Anda akan melihat file go.mod di direktori.

  5. Tambahkan baris berikut ke file go.mod Anda untuk memastikan Anda menggunakan notifikasi versi terbaru:

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

Dependensi Anda kini telah disiapkan dan Anda siap membuat notifikasi sendiri.

Membuat pemberi notifikasi sendiri

cloud-build-notifiers berisi direktori lib/notifiers. Di direktori lib/notifiers, Anda akan melihat file bernama notifier.go. File ini berisi framework yang dapat Anda gunakan untuk membuat notifikasi Anda sendiri.

Anda harus menentukan dua metode untuk membuat notifikasi di file utama.

  1. Di direktori baru, buat file bernama main.go.

  2. Di main.go, impor framework library notifikasi dan dependensi lainnya:

    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. Tentukan metode utama untuk notifikasi Anda. Dalam contoh ini, logger adalah nama notifikasi:

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

    Metode main menggunakan metode Main yang ditentukan dalam file notifier.go, yang digunakan untuk menyiapkan biner notifikasi.

  4. Tentukan struct untuk notifikasi, tempat Anda akan menentukan variabel untuk antarmuka. Dalam contoh ini, logger adalah nama notifikasi. Misalnya,

    type logger struct {
	filter notifiers.EventFilter
}

Selanjutnya, Anda akan menambahkan fungsi notifikasi. Antarmuka notifikasi ditentukan oleh dua metode:

  • SetUp: Metode SetUp menerima konfigurasi, mengambil secret, dan menarik filter yang ditentukan dari konfigurasi dan menyimpannya sebagai prediket Common Expression Language yang dapat digunakan untuk mengirim notifikasi. Untuk mempelajari CEL lebih lanjut, lihat repositori cel-spec.

  • SendNotification: Metode SendNotification adalah metode yang digunakan untuk mengirim notifikasi ke saluran atau layanan yang Anda inginkan.

    Definisi notifikasi tersedia di notifier.go dan di dokumentasi Go.

    Pada contoh di bawah, antarmuka notifikasi ditentukan menggunakan metode SetUp dan SendNotification untuk mencetak log build, dengan logger sebagai nama notifikasi Anda:

    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
}

    File main.go akhir Anda akan terlihat seperti file berikut. Dalam contoh ini, logger digunakan sebagai nama notifikasi.

    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
}

    Setelah menentukan notifikasi, Anda dapat mengikuti langkah-langkah berikut untuk mengonfigurasi notifikasi.

Mengonfigurasi notifikasi

  1. Tulis file konfigurasi notifikasi untuk mengonfigurasi notifikasi dan memfilter peristiwa build:

    Pada contoh file konfigurasi notifikasi berikut, kolom filter menggunakan CEL dengan variabel yang tersedia, build, untuk memfilter peristiwa build dengan status SUCCESS:

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

    Dengan keterangan:

    • logging-sample adalah nama notifikasi.

    Untuk kolom tambahan yang dapat Anda gunakan untuk memfilter, lihat resource Build. Untuk contoh pemfilteran tambahan, lihat Menggunakan CEL untuk memfilter peristiwa build.

  2. Upload file konfigurasi notifikasi ke bucket Cloud Storage:

    1. Jika Anda tidak memiliki bucket Cloud Storage, jalankan perintah berikut untuk membuat bucket, dengan BUCKET_NAME adalah nama yang ingin Anda berikan untuk bucket, tunduk pada persyaratan penamaan.

      gcloud storage buckets create gs://BUCKET_NAME/

    2. Upload file konfigurasi notifikasi ke bucket Anda:

      gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME

      Dengan keterangan:

      • BUCKET_NAME adalah nama bucket Anda.
      • CONFIG_FILE_NAME adalah nama file konfigurasi Anda.

  3. Build dan deploy pemberitahuan Anda:

    1. Buat Dockerfile untuk 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. Build dan deploy pemberitahuan menggunakan file cloudbuild.yaml berikut.

      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

      Dengan keterangan:

      • _CONFIG_PATH adalah jalur ke konfigurasi notifikasi Anda, seperti gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

    Untuk menjalankan cloudbuild.yaml, teruskan jalur pemberitahuan sebagai variabel penggantian.

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

  4. Berikan izin Pub/Sub untuk membuat token autentikasi di project Anda:

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

    Dengan keterangan:

    • PROJECT_ID adalah ID project Google Cloud Anda.
    • PROJECT_NUMBER adalah nomor project Google Cloud Anda.

  5. Buat akun layanan untuk merepresentasikan identitas langganan Pub/Sub Anda:

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

    Anda dapat menggunakan cloud-run-pubsub-invoker atau menggunakan nama yang unik dalam project Google Cloud Anda.

  6. Berikan izin Invoker Cloud Run ke akun layanan cloud-run-pubsub-invoker:

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

    Dengan keterangan:

    • SERVICE_NAME adalah nama layanan Cloud Run tempat Anda men-deploy gambar.
    • PROJECT_ID adalah ID project Google Cloud Anda.

  7. Buat topik cloud-builds untuk menerima pesan update build untuk notifikasi Anda:

    gcloud pubsub topics create cloud-builds

  8. Buat pelanggan push Pub/Sub untuk notifikasi Anda:

     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

    Dengan keterangan:

    • subscriber-id adalah nama yang ingin Anda berikan ke langganan.
    • service-url adalah URL yang dibuat Cloud Run untuk layanan baru Anda.
    • project-id adalah ID project Google Cloud Anda.

Notifikasi untuk project Cloud Build Anda kini telah disiapkan. Saat berikutnya Anda memanggil build, Anda akan menerima notifikasi di channel jika build cocok dengan filter yang telah Anda konfigurasi.

Notifikasi pengujian

Untuk menguji fungsi notifikasi untuk contoh yang digunakan dalam panduan ini, Anda dapat memanggil build dengan menjalankan perintah gcloud builds submit.

Pada contoh berikut, kita menentukan success.yaml sebagai jalur konfigurasi. Menjalankan perintah ini akan menghasilkan build yang berhasil secara minimal. Anda juga akan dapat melihat output log build.

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

Dengan success.yaml adalah:

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

Pada contoh berikut, kita menentukan failure.yaml sebagai jalur konfigurasi. Menjalankan perintah ini akan menyebabkan build gagal. Anda akan melihat output yang menginformasikan bahwa tidak ada kecocokan untuk filter CEL yang Anda tentukan di sumber, bukan melihat output log build.

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

Dengan failure.yaml adalah:

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

Jika membuat notifikasi yang dikonfigurasi untuk melakukan tugas lain selain mencatat output ke log layanan Cloud Run, Anda juga dapat menjalankan perintah gcloud builds submit untuk menguji fungsi notifikasi. Untuk memeriksa error yang terkait dengan build, periksa log Cloud Run untuk layanan Anda. Untuk mempelajari lebih lanjut, lihat Melihat log di Cloud Run.

Langkah selanjutnya