Google Cloud Deploy でのアノテーションとラベルの使用

Google Cloud Deploy リソースにはアノテーションやラベルを付けることができます。必須ではありません。

このドキュメントでは、ラベルとアノテーションを添付できるリソースを一覧表示し、それらの使用方法と表示方法について説明します。

アノテーションとラベルについて

アノテーションは、自由形式のテキストの Key-Value ペアです。リソースに関連する任意の情報を添付できます。

ラベルを使用してリソースを整理できます。たとえば、ラベルの選択に基づいてロジックを適用できます。

アノテーションと同様に、ラベルは Key-Value ペアです。ただし、次の制限があります。

1 つの Google Cloud Deploy リソースに含めることができるラベルは 64 個までです。
キーと値はどちらも 128 バイト以下である必要があります。
キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。
キーは、小文字または国際文字で始める必要があります。
すべての文字には UTF-8 エンコーディングを使用する必要があります。国際文字も使用できます。

--labels フラグ（たとえば、gcloud deploy releases create の場合）は、Key-Value ペアのリストを取得できます。

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

詳細については、Google Cloud Deploy API のドキュメントをご覧ください。

Google Cloud Deploy リソースへのアノテーションとラベルの追加

次の Google Cloud Deploy リソースにアノテーションとラベルを追加できます。

デリバリーパイプライン

デリバリーパイプラインの場合、アノテーションとラベルを YAML 構成ファイルに追加します。

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

ターゲット

ターゲット構成 YAML でターゲットにアノテーションとラベルを追加します。

たとえば、アプリケーションのサードパーティモニタリングの詳細情報へのリンクを含めることができます。ただし、ターゲットが共有の場合は、複数のアプリケーションに使用できる可能性があるため、リンクはアプリケーション固有でない必要があります。
リリース

アノテーションまたはラベル、またはその両方をリリースに追加するには、gcloud deploy releases create コマンドで --labels フラグと --annotations フラグを使用します。リリースに追加したラベルとアノテーションは、結果のロールアウトでラベルまたはアノテーションとして引き継がれません。

たとえば、アノテーションを使用して、デプロイする変更を含む Git commit への参照を Git PR、作成者、または SHA ハッシュに含めることができます。詳細については、アノテーションを使用してリリースの来歴を追跡するをご覧ください。
ロールアウト

新しいロールアウトにアノテーションとラベルを追加するには、gcloud deploy releases promote コマンドに --labels または --annotations を指定します。

アノテーションとラベルを最初のロールアウトに追加する唯一の方法は、Cloud Deploy API を使用してロールアウトを作成し、rollout リソースにアノテーションまたはラベルを含めることです。

ロールアウトでアノテーションを使用してできること:
- テスト結果を指定する URL を含むアノテーションを作成します。
- ワークフロー管理システムから、関連するチケット番号を含むアノテーションを作成します。

リソースのアノテーションはどこにありますか？

サポートされている任意のリソースのアノテーションとラベルを表示するには、リソースの describe コマンドを使用するか、Google Cloud コンソールでリソースのメタデータを表示します。

gcloud CLI から

コマンドラインからリソースのアノテーションとラベルを表示するには、そのリソースの describe コマンドを使用します。次の例では、ターゲットの詳細を示します。

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

上記のコマンドは次の出力を返します。

 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'

この出力には target_name アノテーションが含まれていることに注意してください。

Google Cloud コンソールの場合

このようなメタデータを含む Google Cloud Deploy リソースのアノテーションとラベルを表示するには、Google Cloud コンソールでそのリソースの詳細を表示します。

たとえば、アノテーションを含むパイプラインのデリバリーパイプラインの詳細は次のとおりです。

Google Cloud Console でのデリバリーパイプラインの詳細

リリースの詳細は次のとおりです。

Google Cloud Console でのリリースの詳細

Google Cloud Deploy からの自動ラベル

Google Cloud Deploy のデフォルトでは、次のラベルがレンダリングされたマニフェストに追加されます。

app.kubernetes.io/managed-by:

デプロイツールを示す標準ラベル。常に google-cloud-deploy に設定され、ワークロードの送信元を識別します。
deploy.cloud.google.com/location:

デプロイされたデリバリーパイプラインのロケーション（us-central1 など）。
deploy.cloud.google.com/project-id:

デプロイされたデリバリーパイプラインのプロジェクト ID。
deploy.cloud.google.com/delivery-pipeline-id:

使用するデリバリーパイプラインのリソース ID。これはリリーススナップショットから取得されます。
deploy.cloud.google.com/release-id:

デプロイされたリリースのリソース ID。
deploy.cloud.google.com/target-id:

デプロイターゲットのリソース ID。これはリリーススナップショットから取得されます。

使用例

たとえば、これらの自動的に適用されるラベルを使用する一例は、Google Cloud Deploy プロパティによってコンテナ指標を集計する Google Cloud のオペレーションスイート内でグラフを作成することです。

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

これはカスタム指標でも使用できます。たとえば、PodMonitor が app.kubernetes.io/managed-by: google-cloud-deploy と一致するようにラベルで構成されている場合。この場合、クエリを使用してカスタム指標のグラフを定義できます。

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

自動ラベルの無効化

組織は、規制やコンプライアンスなどの理由から、これらの自動ラベルを禁止する場合があります。これをサポートするために、組織ポリシーサービスには、これらのラベルを適用するかどうかを制御する制約が用意されています。

レンダリングされたマニフェストに Google Cloud Deploy が自動的にラベルを追加しないようにするには、組織のポリシーサービス制約 clouddeploy.disableServiceLabelGeneration を適用します。この制約を適用しても、ラベルを手動で指定することはできません。また、既存のリリースからラベルを削除することもできません。

制約の有効化の詳細については、組織ポリシーにブール型制約を使用するをご覧ください。