Menggunakan anotasi dan label dengan Cloud Deploy

Anda dapat melampirkan anotasi dan label ke resource Cloud Deploy. Hal ini tidak diperlukan.

Dokumen ini mencantumkan resource yang dapat Anda sertakan label dan anotasi, serta menjelaskan cara menggunakannya dan tempat Anda dapat melihatnya.

Tentang anotasi dan label

Anotasi adalah pasangan nilai kunci dari teks bentuk bebas. Anda dapat menggunakannya untuk melampirkan informasi arbitrer yang terkait dengan resource.

Anda dapat menggunakan label untuk mengatur resource. Misalnya, Anda dapat menerapkan logika berdasarkan pemilihan label.

Seperti anotasi, label adalah pasangan nilai kunci. Namun, batasan berikut harus diikuti:

• Resource Cloud Deploy tidak boleh memiliki lebih dari 64 label.

• Kunci dan nilai harus berukuran 128 byte atau kurang.

• Kunci dan nilai hanya boleh berisi huruf kecil, karakter numerik, garis bawah, dan tanda pisah.

• Kunci harus diawali dengan huruf kecil atau karakter internasional.

• Semua karakter harus menggunakan encoding UTF-8. Karakter internasional diperbolehkan.

Flag --labels (misalnya, di gcloud deploy releases create) dapat menggunakan daftar pasangan nilai kunci:

"name=wrench,mass=1.3kg,count=3"

Lihat dokumentasi Cloud Deploy API untuk mengetahui detail selengkapnya.

Menambahkan anotasi dan label ke resource Cloud Deploy

Anda dapat menambahkan anotasi dan label ke resource Cloud Deploy berikut:

• Pipeline pengiriman

  Untuk pipeline pengiriman, Anda menambahkan anotasi dan label ke file konfigurasi YAML.

apiVersion: deploy.cloud.google.com/v1
  kind: DeliveryPipeline
  metadata:
   name:
   annotations:
     key: "value"
   labels:
     key: "value"
  description:
  serialPipeline:
   stages:
   - targetId:
     profiles: []
   - targetId:
     profiles: []

• Target

  Tambahkan anotasi dan label ke target di YAML konfigurasi target.

  Misalnya, Anda dapat menyertakan link ke informasi selengkapnya tentang pemantauan pihak ketiga untuk aplikasi Anda. Namun, jika target dibagikan, ingatlah bahwa target tersebut dapat digunakan untuk lebih dari satu aplikasi, sehingga link tidak boleh spesifik untuk aplikasi.

• Rilis

  Anda dapat menambahkan anotasi atau label, atau keduanya, ke rilis menggunakan flag --labels dan --annotations pada perintah gcloud deploy releases create. Label dan anotasi yang Anda tambahkan ke rilis tidak akan diteruskan sebagai label atau anotasi pada peluncuran yang dihasilkan.

  Misalnya, Anda dapat menggunakan anotasi untuk menyertakan referensi ke PR Git, penulis, atau hash SHA dari commit Git yang berisi perubahan yang akan di-deploy. Lihat Menggunakan anotasi untuk melacak asal rilis untuk mengetahui detail selengkapnya.

• Peluncuran

  Anda dapat menambahkan anotasi dan label ke peluncuran baru dengan menentukan --labels atau --annotations pada perintah gcloud deploy releases promote.

  Anda dapat menambahkan anotasi dan label ke peluncuran pertama dengan menentukan --initial-rollout-labels atau --initial-rollout-annotations pada perintah gcloud deploy releases create.

  Beberapa hal yang dapat Anda lakukan menggunakan anotasi pada peluncuran:

  • Buat anotasi yang berisi URL yang mengarah ke hasil pengujian.
  • Buat anotasi dengan nomor tiket yang relevan dari sistem pengelolaan alur kerja.

Catatan: label dan anotasi yang ditambahkan ke resource Cloud Deploy hanya diterapkan ke resource tersebut. Aturan ini tidak diterapkan secara transitif ke resource yang di-deploy.

Di mana saya dapat menemukan anotasi resource?

Anda dapat melihat anotasi dan label untuk resource apa pun yang didukung menggunakan perintah describe resource atau dengan melihat metadata resource di konsol Google Cloud.

Dari gcloud CLI

Untuk melihat anotasi dan label resource dari command line, gunakan perintah describe pada resource tersebut. Contoh berikut menunjukkan detail untuk target:

 $ gcloud deploy targets describe qsprod --delivery-pipeline=my-demo-app-1 \
                                              --region=us-central1 \
                                              --project=quickstart-basic8

Perintah di atas menampilkan output berikut:

 Target:
   annotations:
     approver_ticket_queue_url: https://workflows.example.com/deploy_approvals/4985729
   createTime: '2021-10-28T19:33:56.907887878Z'
   description: development cluster
   etag: 5b3bbee48f693cd7
   gke:
     cluster: projects/quickstart-basic8/locations/us-central1/clusters/quickstart-cluster-qsdev
   name: projects/quickstart-basic8/locations/us-central1/targets/qsdev
   uid: 3f3a5f8e7e0648e3bb17898ee531455d
   updateTime: '2021-11-10T16:55:11.502660604Z'

Perhatikan bahwa output ini menyertakan anotasi target_name.

Di konsol Google Cloud

Untuk melihat anotasi dan label untuk resource Cloud Deploy yang memiliki metadata tersebut, lihat detail resource tersebut di konsol Google Cloud.

Misalnya, berikut adalah detail pipeline pengiriman untuk pipeline yang menyertakan anotasi:

Berikut detail rilis:

Label otomatis dari Cloud Deploy

Secara default, Cloud Deploy menambahkan label berikut ke manifes yang dirender:

• app.kubernetes.io/managed-by:

  Label standar untuk menunjukkan alat deployment. Nilai ini selalu ditetapkan ke google-cloud-deploy untuk mengidentifikasi asal beban kerja.

• deploy.cloud.google.com/location:

  Lokasi pipeline pengiriman yang di-deploy, misalnya us-central1.

• deploy.cloud.google.com/project-id:

  Project ID pipeline pengiriman yang di-deploy.

• deploy.cloud.google.com/delivery-pipeline-id:

  ID resource pipeline pengiriman yang digunakan. Ini diambil dari snapshot rilis.

• deploy.cloud.google.com/release-id:

  ID resource rilis yang di-deploy.

• deploy.cloud.google.com/target-id:

  ID resource target deployment. Ini diambil dari snapshot rilis.

Contoh penggunaan

Salah satu contoh penggunaan label yang diterapkan secara otomatis ini adalah membuat grafik dalam Google Cloud Observability yang menggabungkan metrik penampung berdasarkan properti Cloud Deploy:

fetch k8s_container
| metric 'kubernetes.io/container/cpu/core_usage_time'
| filter metadata.user.c'app.kubernetes.io/managed-by' = "google-cloud-deploy"
| group_by [
    pipeline: metadata.user.c'deploy.cloud.google.com/delivery-pipeline-id',
    target: metadata.user.c'deploy.cloud.google.com/target-id',
    release: metadata.user.c'deploy.cloud.google.com/release-id',],
      sum(val())
| rate 1m

Anda juga dapat menggunakannya dengan metrik kustom. Misalnya, jika PodMonitor dikonfigurasi dengan label agar cocok dengan app.kubernetes.io/managed-by: google-cloud-deploy. Kemudian, Anda dapat menggunakan kueri untuk menentukan grafik untuk metrik kustom:

fetch k8s_container
| metric workload.googleapis.com/example_requests_total
| filter metadata.user_labels.c'app.kubernetes.io/managed-by' = "google-cloud-deploy"
| group_by [
    pipeline: metadata.user.c'deploy.cloud.google.com/delivery-pipeline-id',
    target: metadata.user.c'deploy.cloud.google.com/target-id',
    release: metadata.user.c'deploy.cloud.google.com/release-id',],
    sum(val())
| rate 1m

Menonaktifkan label otomatis

Organisasi Anda mungkin tidak mengizinkan label otomatis ini karena alasan peraturan, kepatuhan, atau alasan lainnya. Untuk mendukung hal ini, Layanan Kebijakan Organisasi menawarkan batasan yang mengontrol apakah label ini diterapkan atau tidak.

Untuk mencegah Cloud Deploy otomatis menambahkan label ke manifes yang dirender, tetapkan batasan Layanan Kebijakan Organisasi clouddeploy.disableServiceLabelGeneration untuk diterapkan. Penerapan batasan ini tidak mencegah Anda menentukan label secara manual, atau menghapus label dari rilis yang ada.

Lihat Menggunakan batasan boolean dalam kebijakan organisasi untuk mengetahui informasi selengkapnya tentang cara mengaktifkan batasan.