Membuat notifikasi Anda sendiri

Cloud Build dapat memberi tahu Anda tentang pembaruan status build dengan mengirimkan notifikasi ke saluran yang diinginkan. 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 notifikasi Anda sendiri.

Halaman ini menjelaskan cara membuat pemberi tahu Anda sendiri.

Sebelum memulai

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

    Mengaktifkan API

  • Instal bahasa pemrograman Go.

  • Instal Google Cloud CLI.

Menyiapkan

  1. Buka jendela terminal pada komputer 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 bukalah di dalamnya, dengan DIRECTORY_NAME sebagai nama direktori Anda:

      mkdir DIRECTORY_NAME && cd DIRECTORY_NAME
    
  4. Lakukan inisialisasi modul go di direktori baru, dengan DIRECTORY_NAME sebagai nama direktori baru Anda:

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

    Sekarang Anda dapat melihat file go.mod di direktori Anda.

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

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

Dependensi Anda sekarang telah diatur dan Anda siap untuk membuat notifikasi Anda sendiri.

Membuat notifikasi Anda sendiri

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

Anda perlu menetapkan dua metode untuk membuat pemberi tahu di file utama Anda.

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

  2. Dalam 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 notifier 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 notifikasi.

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

    type logger struct {
    	filter notifiers.EventFilter
    }
    

Berikutnya, Anda akan menambahkan fungsi notifikasi. Antarmuka pemberi pemberitahuan ditetapkan oleh dua metode:

  • SetUp: Metode SetUp menerima konfigurasi, mengambil secret, dan mengambil 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 mengirimkan notifikasi ke saluran atau layanan yang Anda inginkan.

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

    Pada contoh di bawah, antarmuka pemberi notifikasi ditetapkan 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 seperti 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
    }
    

    Setelah menetapkan pemberi notifikasi, Anda dapat mengikuti langkah-langkah berikut di bawah ini untuk mengonfigurasi pemberi 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 pemberi notifikasi.

    Untuk kolom tambahan yang dapat difilter, 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 sebagai nama yang Anda inginkan untuk memberikan bucket, sesuai dengan persyaratan penamaan.

      gsutil mb gs://BUCKET_NAME/
      
    2. Upload file konfigurasi notifier ke bucket Anda:

      gsutil 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. Bangun dan deploy notifier 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. 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 keterangan:

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

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

     gcloud builds submit .  --substitutions=_CONFIG_PATH=gs://BUCKET_NAME/CONFIG_FILE_NAME
    
  4. Berikan izin Pub/Sub untuk membuat token autentikasi dalam 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 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
    
  8. Buat pelanggan push Pub/Sub untuk pemberi tahu 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 untuk langganan.
    • service-url adalah URL yang dihasilkan Cloud Run untuk layanan baru Anda.
    • project-id adalah ID project Google Cloud Anda.

Notifikasi untuk project Cloud Build Anda sudah siap. Saat berikutnya Anda memanggil build, Anda akan menerima notifikasi di saluran Anda jika build cocok dengan filter yang telah dikonfigurasi.

Notifikasi pengujian

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

Dalam contoh berikut, kami menentukan success.yaml sebagai jalur konfigurasi. Menjalankan perintah ini akan menghasilkan build yang minimal berhasil. 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"]

Dalam contoh berikut, kami menentukan failure.yaml sebagai jalur konfigurasi. Menjalankan perintah ini akan mengakibatkan build yang gagal. Anda akan melihat output yang memberi tahu bahwa tidak ada kecocokan dengan filter CEL yang telah ditentukan dalam sumber, bukan 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 Anda, periksa log Cloud Run untuk layanan Anda. Untuk mempelajari lebih lanjut, baca bagian Melihat log di Cloud Run.

Langkah selanjutnya