Mengonfigurasi notifikasi SMTP

Cloud Build dapat memberi tahu Anda tentang update build dengan mengirimkan notifikasi ke saluran yang dipilih, seperti Slack atau server SMTP Anda. Halaman ini menjelaskan cara mengonfigurasi notifikasi menggunakan notifikasi SMTP.

Sebelum memulai

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

  Peran yang diperlukan untuk mengaktifkan API

  Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

  Aktifkan API

• Instal Google Cloud CLI.

Mengonfigurasi notifikasi email

Untuk mengirim notifikasi email, Anda memerlukan server SMTP yang berjalan dan akses ke akun di server tersebut, termasuk nama pengguna dan sandi akun yang akan digunakan untuk mengirim notifikasi. Anda dapat menggunakan server SMTP yang ada, tetapi memerlukan akses ke nama dan port server. Misalnya, nama server untuk Gmail adalah smtp.gmail.com dan portnya adalah 587. Pastikan kuota pengiriman server SMTP Anda dapat menangani volume email yang Anda harapkan untuk dibuat.

Bagian berikut menjelaskan cara mengonfigurasi notifikasi email secara manual menggunakan notifikasi SMTP. Jika Anda ingin mengotomatiskan konfigurasi, lihat Mengotomatiskan konfigurasi untuk notifikasi.

Untuk mengonfigurasi notifikasi email:

1. Simpan sandi akun email pengirim di Secret Manager. Perhatikan bahwa untuk gmail, Anda harus menggunakan sandi aplikasi, bukan sandi login akun.

   1. Buka halaman Secret Manager di Google Cloud konsol:

      Buka halaman Secret Manager

   2. Klik Create secret.

   3. Masukkan nama untuk secret Anda.

   4. Di bagian Secret value, tambahkan sandi akun email pengirim.

   5. Untuk menyimpan secret Anda, klik Create secret.

2. Meskipun akun layanan Cloud Run Anda mungkin memiliki peran Editor untuk project Anda, peran Editor tidak cukup untuk mengakses secret Anda di Secret Manager. Untuk memberikan akses akun layanan Cloud Run ke secret Anda, lakukan hal berikut:

   1. Buka halaman IAM di Google Cloud konsol:

      Buka halaman IAM

   2. Temukan akun layanan default Compute Engine yang terkait dengan project Anda:

      Akun layanan default Compute Engine Anda akan terlihat mirip dengan berikut ini:

      [e-mail]
      

      Perhatikan akun layanan default Compute Engine Anda.

      Catatan: Secara default, Cloud Run menjalankan image notifikasi Anda dengan akun layanan default Compute Engine dan menggunakannya untuk mengambil secret Anda. Untuk mempelajari Akun layanan runtime lebih lanjut, lihat Akun layanan runtime.

   3. Buka halaman Secret Manager di Google Cloud konsol:

      Buka halaman Secret Manager

   4. Klik nama secret yang berisi secret untuk sandi akun email pengirim Anda.

   5. Di tab Permissions, klik Add member.

   6. Tambahkan akun layanan default Compute Engine yang terkait dengan project Anda sebagai anggota.

   7. Pilih izin Secret Manager Secret Accessor sebagai peran.

   8. Klik Save.

3. Beri akun layanan Cloud Run Anda izin untuk membaca dari bucket Cloud Storage:

   1. Buka halaman IAM di Google Cloud konsol:

      Buka halaman IAM

   2. Temukan akun layanan default Compute Engine yang terkait dengan project Anda:

      Akun layanan default Compute Engine Anda akan terlihat mirip dengan berikut ini:

      [e-mail]
      

   3. Klik ikon pensil di baris yang berisi akun layanan default Compute Engine Anda. Anda akan melihat tab Edit access.

   4. Klik Add another role.

   5. Tambahkan peran berikut:

      • Storage Object Viewer
      Catatan: Jika Anda ingin memberikan izin di tingkat bucket, bukan tingkat project, tambahkan peran Storage Legacy Object Owner ke bucket Anda saat Anda membuat satu. Untuk mempelajari lebih lanjut, lihat Memberikan peran di tingkat project, tingkat bucket, atau tingkat folder terkelola.

   6. Klik Save.

4. Tulis file konfigurasi notifikasi untuk mengonfigurasi notifikasi SMTP Anda dan memfilter peristiwa build:

   Dalam contoh file konfigurasi notifikasi berikut, kolom filter menggunakan Common Expression Language dengan variabel yang tersedia, build, untuk memfilter peristiwa build dengan status SUCCESS:

   apiVersion: cloud-build-notifiers/v1
   kind: SMTPNotifier
   metadata:
     name: example-smtp-notifier
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS
       params:
         buildStatus: $(build.status)
       delivery:
         server: server-host-name
         port: "port"
         sender: sender-email
         from: from-email
         recipients:
           - recipient-email
           # optional: more emails here
         password:
           secretRef: smtp-password
       template:
         type: golang
         uri: gs://bucket_name/smtp.html
     secrets:
     - name: smtp-password
       value: projects/project-id/secrets/secret-name/versions/latest
   

   Dengan:

   • buildStatus adalah parameter yang ditentukan pengguna. Parameter ini mengambil nilai $(build.status), status build.
   • bucket-name adalah nama bucket Anda.
   • server-host-name adalah alamat server SMTP Anda.
   • port adalah port yang akan menangani permintaan SMTP. Nilai ini harus ditentukan sebagai string.
   • sender-email adalah alamat email akun pengirim yang dilihat oleh server-host-name yang ditentukan.
   • from-email adalah alamat email yang dilihat oleh penerima.
   • recipient-email adalah daftar satu atau beberapa alamat email untuk menerima pesan dari pengirim.
   • smtp-password adalah variabel konfigurasi yang digunakan dalam contoh ini untuk mereferensikan sandi akun email pengirim yang disimpan di Secret Manager. Nama variabel yang Anda tentukan di sini harus cocok dengan kolom name di bagian secrets.
   • project-id adalah ID Google Cloud project Anda.
   • secret-name adalah nama secret Anda yang berisi sandi ke akun email pengirim.

   • Kolom uri mereferensikan file smtp.html. File ini merujuk ke template HTML yang dihosting di Cloud Storage dan mewakili email notifikasi Anda.

     Eksperimental — Menyesuaikan notifikasi menggunakan template

     Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

   Untuk melihat contohnya, lihat file konfigurasi notifikasi untuk notifikasi SMTP.

   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.

5. 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 ke bucket, yang 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.

6. Deploy notifikasi Anda ke Cloud Run:

    gcloud run deploy service-name \
      --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/smtp:latest \
      --no-allow-unauthenticated \
      --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
   

   Dengan:

   • service-name adalah nama layanan Cloud Run tempat Anda men-deploy image.
   • config-path adalah jalur ke file konfigurasi notifikasi untuk notifikasi SMTP Anda, gs://bucket-name/config-file-name.
   • project-id adalah ID Google Cloud project Anda.

   Perintah gcloud run deploy mengambil versi terbaru image yang dihosting dari Artifact Registry milik Cloud Build. Cloud Build mendukung image notifikasi selama sembilan bulan. Setelah sembilan bulan, Cloud Build akan menghapus versi image. Jika ingin menggunakan versi image sebelumnya, Anda harus menentukan versi semantik lengkap dari tag image di atribut image perintah gcloud run deploy Anda. Versi dan tag image sebelumnya dapat ditemukan di Artifact Registry.

   Catatan: Saat menjalankan perintah ini, Anda mungkin diminta untuk menentukan argumen tambahan seperti --region atau --platform. Untuk mempelajari lebih lanjut tentang parameter yang dapat Anda teruskan ke perintah gcloud run deploy, lihat Men-deploy ke Cloud Run. Jika Anda tidak dapat men-deploy notifikasi menggunakan perintah ini, lihat panduan pemecahan masalah Cloud Run untuk mengetahui solusi tentang cara mengatasi error Deployment.

7. Beri izin Pub/Sub untuk membuat token autentikasi di project Anda Google Cloud :

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

   Dengan:

   • project-id adalah ID Google Cloud project Anda.
   • project-number adalah nomor project Anda Google Cloud .
   Catatan: Jika akun layanan Pub/Sub tidak ada di project Anda, lihat Membuat dan menggunakan langganan.

8. 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.

9. Beri akun layanan cloud-run-pubsub-invoker izin Invoker Cloud Run:

   gcloud run services add-iam-policy-binding service-name \
      --member=serviceAccount:[e-mail] \
      --role=roles/run.invoker
   

   Dengan:

   • service-name adalah nama layanan Cloud Run tempat Anda men-deploy image.

   • project-id adalah ID Google Cloud project Anda.

10. 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. 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.

11. 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=[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 Google Cloud project Anda.
    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, recipients yang ditentukan akan menerima email dengan notifikasi jika build cocok dengan filter yang telah Anda konfigurasi.

Menggunakan CEL untuk memfilter peristiwa build

Cloud Build menggunakan CEL dengan variabel, build, pada kolom yang tercantum dalam resource Build untuk mengakses kolom yang terkait dengan peristiwa build Anda seperti ID pemicu, daftar image, atau nilai substitusi. Anda dapat menggunakan filter string untuk memfilter peristiwa build dalam file konfigurasi build menggunakan kolom apa pun yang tercantum dalam Build resource. Untuk menemukan sintaksis yang tepat yang terkait dengan kolom Anda, lihat file cloudbuild.proto.

Memfilter menurut ID pemicu

Untuk memfilter menurut ID pemicu, tentukan nilai ID pemicu Anda di kolom filter menggunakan build.build_trigger_id, dengan trigger-id adalah ID pemicu Anda sebagai string:

filter: build.build_trigger_id == trigger-id

Catatan: ID pemicu Anda bukan nama pemicu Anda. Untuk mendapatkan ID pemicu Anda, jalankan perintah berikut: gcloud beta builds triggers describe trigger-name, dengan trigger-name adalah nama pemicu Anda. Perintah ini akan mencantumkan kolom yang terkait dengan pemicu Anda, termasuk ID pemicu Anda.

Memfilter menurut status

Untuk memfilter menurut status, tentukan status build yang ingin Anda filter di kolom filter menggunakan build.status.

Contoh berikut menunjukkan cara memfilter peristiwa build dengan status SUCCESS menggunakan kolom filter:

filter: build.status == Build.Status.SUCCESS

Anda juga dapat memfilter build dengan status yang berbeda-beda. Contoh berikut menunjukkan cara memfilter peristiwa build yang memiliki status SUCCESS, FAILURE, atau TIMEOUT menggunakan kolom filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Untuk melihat nilai status tambahan yang dapat Anda gunakan untuk memfilter, lihat Status di bagian Referensi resource Build.

Memfilter menurut tag

Untuk memfilter menurut tag, tentukan nilai tag Anda di kolom filter menggunakan build.tags, dengan tag-name adalah nama tag Anda:

filter: tag-name in build.tags

Anda dapat memfilter berdasarkan jumlah tag yang ditentukan dalam peristiwa build menggunakan size. Dalam contoh berikut, kolom filter memfilter peristiwa build yang memiliki tepat dua tag yang ditentukan dengan satu tag yang ditentukan sebagai v1:

filter: size(build.tags) == 2 && "v1" in build.tags

Memfilter menurut image

Untuk memfilter menurut image, tentukan nilai image Anda di kolom filter menggunakan build.images, dengan image-name adalah nama lengkap image Anda seperti yang tercantum di Artifact Registry seperti us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Dalam contoh berikut, filter memfilter peristiwa build yang memiliki us-east1-docker.pkg.dev/my-project/docker-repo/image-one atau us-east1-docker.pkg.dev/my-project/docker-repo/image-two yang ditentukan sebagai nama image:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images

Memfilter menurut waktu

Anda dapat memfilter peristiwa build berdasarkan waktu pembuatan, waktu mulai, atau waktu selesai build dengan menentukan salah satu opsi berikut di kolom filter: build.create_time, build.start_time, atau build.finish_time.

Dalam contoh berikut, kolom filter menggunakan timestamp untuk memfilter peristiwa build dengan waktu permintaan untuk membuat build pada 20 Juli 2020 pukul 06.00:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Anda juga dapat memfilter peristiwa build berdasarkan perbandingan waktu. Dalam contoh berikut, kolom filter menggunakan timestamp untuk memfilter peristiwa build dengan waktu mulai antara 20 Juli 2020 pukul 06.00 dan 30 Juli 2020 pukul 06.00.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Untuk mempelajari lebih lanjut cara zona waktu dinyatakan dalam CEL, lihat definisi bahasa untuk zona waktu.

Untuk memfilter menurut durasi build, Anda dapat menggunakan duration untuk membandingkan stempel waktu. Dalam contoh berikut, kolom filter menggunakan duration untuk memfilter peristiwa build dengan build yang berjalan selama minimal lima menit:

filter: build.finish_time - build.start_time >= duration("5m")

Catatan: Stempel waktu dalam format RFC 3339 UTC "Zulu", dengan resolusi nanodetik dan hingga sembilan digit pecahan.

Memfilter menurut substitusi

Anda dapat memfilter menurut substitusi dengan menentukan variabel substitusi di kolom filter menggunakan build.substitutions. Dalam contoh berikut, kolom filter mencantumkan build yang berisi variabel substitusi substitution-variable dan memeriksa apakah substitution-variable cocok dengan substitution-value yang ditentukan:

filter: build.substitutions[substitution-variable] == substitution-value

Dengan:

• substitution-variable adalah nama variabel substitusi Anda.
• substitution-value adalah nama nilai substitusi Anda.

Anda juga dapat memfilter menurut nilai variabel substitusi default. Dalam contoh berikut, kolom filter mencantumkan build yang memiliki nama cabang master dan build yang memiliki nama repositori github.com/user/my-example-repo. Variabel substitusi default BRANCH_NAME dan REPO_NAME diteruskan sebagai kunci ke build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Jika ingin memfilter string menggunakan ekspresi reguler, Anda dapat menggunakan fungsi matches bawaan. Dalam contoh di bawah, kolom filter memfilter build dengan status FAILURE atau TIMEOUT dan juga memiliki variabel substitusi build TAG_NAME dengan nilai yang cocok dengan ekspresi reguler v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")

Untuk melihat daftar nilai substitusi default, lihat Menggunakan substitusi default.

Langkah berikutnya

• Pelajari tentang notifikasi Cloud Build.
• Pelajari cara berlangganan notifikasi build.
• Pelajari cara menulis file konfigurasi build Cloud Build.