Membuat pemberi notifikasi sendiri

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

Halaman ini menjelaskan cara membuat notifikasi Anda sendiri.

Sebelum memulai

  • 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

  • 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 Anda, 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 Anda.

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

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

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

Membuat pemberi notifikasi Anda 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 notifiers 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 Anda, tempat Anda akan menentukan variabel untuk antarmuka Anda. Dalam contoh ini, logger adalah nama notifikasi:

    type logger struct {
	filter notifiers.EventFilter
}

  5. Tambahkan fungsi notifikasi. Antarmuka notifikasi ditentukan oleh dua metode:

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

    • SendNotification: Metode SendNotification digunakan untuk mengirim notifikasi ke saluran atau layanan yang Anda pilih.

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

      Dalam contoh berikut, 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
}

    Selanjutnya, konfigurasi notifikasi Anda.

Mengonfigurasi notifikasi

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

    Dalam file konfigurasi notifikasi contoh 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:

    • logging-sample adalah nama notifikasi.

    Untuk mengetahui 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 Anda 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:

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

  3. Bangun dan deploy pemberi notifikasi 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
# 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. Bangun dan deploy notifikasi 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:

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

    Untuk menjalankan cloudbuild.yaml, teruskan jalur notifikasi sebagai variabel pengganti.

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

  4. Beri Pub/Sub izin 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:

    • 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. Beri akun layanan cloud-run-pubsub-invoker izin Cloud Run 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:

    • SERVICE_NAME adalah nama layanan Cloud Run tempat Anda men-deploy image.
    • 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

    Anda juga dapat menentukan nama topik kustom dalam file konfigurasi build sehingga pesan dikirim ke topik kustom tersebut. Dalam hal ini, Anda akan membuat topik dengan nama topik kustom yang sama:

    gcloud pubsub topics create topic-name

    Untuk mengetahui informasi selengkapnya, lihat Topik Pub/Sub untuk notifikasi build.

  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:

    • subscriber-id adalah nama yang ingin Anda berikan pada 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 notifikasi untuk contoh yang digunakan dalam panduan ini, Anda dapat memulai build dengan menjalankan perintah gcloud builds submit.

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

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

Dengan success.yaml adalah:

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

Dalam contoh berikut, kita menentukan failure.yaml sebagai jalur konfigurasi. Menjalankan perintah ini akan menghasilkan build yang gagal. Daripada melihat output log build, Anda akan melihat output yang memberi tahu Anda bahwa tidak ada kecocokan untuk filter CEL yang Anda tentukan di sumber.

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

Dengan failure.yaml adalah:

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

Jika Anda 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 notifikasi. Untuk memeriksa error yang terkait dengan build Anda, periksa log Cloud Run untuk layanan Anda. Untuk mempelajari lebih lanjut, lihat Melihat log di Cloud Run.

Langkah berikutnya