Membuat pemberi notifikasi sendiri

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

Halaman ini menjelaskan cara membuat pemberi notifikasi Anda sendiri.

Sebelum memulai

• Aktifkan Cloud Build, Cloud Run, Pub/Sub, dan Secret Manager API.

  Peran yang diperlukan untuk mengaktifkan API

  Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

  Aktifkan API

• Instal bahasa pemrograman Go.

  Catatan: Pemberi notifikasi Cloud Build ditulis dalam Go. Untuk membuat pemberi notifikasi Anda sendiri menggunakan library yang disediakan oleh repositori cloud-build-notifiers, Anda harus menginstal Go di mesin Anda.

• Instal Google Cloud CLI.

Menyiapkan

1. Buka jendela terminal di mesin 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 pemberi 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
   

   Anda akan melihat file go.mod di direktori Anda.

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

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

Dependensi Anda kini telah disiapkan dan Anda siap membuat pemberi notifikasi Anda 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 pemberi notifikasi Anda sendiri.

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

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

2. Di main.go, impor framework library pemberi 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 pemberi notifikasi Anda. Dalam contoh ini, logger adalah nama pemberi 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 pemberi notifikasi.

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

   type logger struct {
   	filter notifiers.EventFilter
   }
   

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

   • SetUp: Metode SetUp menerima konfigurasi, mengambil secret, dan menarik filter yang ditentukan 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 adalah metode yang digunakan untuk mengirim notifikasi ke channel atau layanan yang Anda pilih.

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

     Dalam contoh berikut, antarmuka pemberi notifikasi ditentukan menggunakan metode SetUp dan SendNotification untuk mencetak log build, dengan logger sebagai nama pemberi 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 mirip dengan file berikut. Dalam contoh ini, logger digunakan sebagai nama pemberi 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 pemberi notifikasi Anda.

Mengonfigurasi notifikasi

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

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

   • logging-sample adalah nama pemberi notifikasi.

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

2. Upload file konfigurasi pemberi 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 ke bucket Anda, yang tunduk pada persyaratan penamaan.

      gcloud storage buckets create gs://BUCKET_NAME/
      

   2. Upload file konfigurasi pemberi 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. Buat dan deploy pemberi notifikasi Anda:

   1. Buat Dockerfile untuk 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. Buat dan deploy pemberi 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 pemberi notifikasi Anda, seperti gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

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

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

   Catatan: Cloud Build menghosting image pemberi notifikasi yang ada di Artifact Registry. Karena Anda membuat pemberi notifikasi Anda sendiri, bukan menggunakan pemberi notifikasi yang dihosting Cloud Build, Anda harus membuat pemberi notifikasi untuk membuat image pemberi notifikasi. Untuk melihat contoh file cloudbuild.yaml untuk jenis pemberi notifikasi lain, seperti pemberi notifikasi slack, lihat buildtest.cloudbuild.yaml. Untuk melihat contoh Dockerfile yang digunakan dalam file buildtest.cloudbuild.yaml, lihat Dockerfile.

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

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

   Dengan:

   • PROJECT_ID adalah ID projectAnda. Google Cloud
   • PROJECT_NUMBER adalah nomor projectAnda. Google Cloud

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:

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

7. Buat topik cloud-builds untuk menerima pesan update build untuk pemberi 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. 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 pemberi notifikasi Anda:

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

   Dengan:

   • subscriber-id adalah nama yang ingin Anda berikan ke langganan Anda.
   • service-url adalah URL yang dibuat Cloud Run untuk layanan baru Anda.
   • project-id adalah ID projectAnda. Google Cloud
   Catatan: Secara default, masa berlaku langganan akan berakhir setelah 31 hari tidak aktif. Anda dapat menyesuaikan atau menonaktifkan periode masa berlaku dengan menyertakan --expiration-period flag saat membuat langganan.

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

Notifikasi pengujian

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

Dalam contoh berikut, kita menentukan success.yaml sebagai jalur konfigurasi. Menjalankan perintah ini akan menghasilkan build minimal yang berhasil. 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, Anda akan melihat output yang memberi tahu Anda bahwa tidak ada kecocokan untuk filter CEL yang Anda tentukan di sumber Anda.

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

Dengan failure.yaml adalah:

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

Jika Anda membuat pemberi notifikasi yang dikonfigurasi untuk melakukan tugas lain selain output logging ke log layanan Cloud Run, Anda juga dapat menjalankan perintah gcloud builds submit untuk menguji notifikasi Anda. 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

• Pelajari tentang pemberi notifikasi Cloud Build.
• Pelajari cara berlangganan notifikasi build.