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

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

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

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

アノテーションは、自由形式のテキストの Key-Value ペアです。これらを使用して、リソースに関連付けられた任意の情報を付加できます。

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

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

  • Cloud Deploy リソースに付けることができるラベルは 64 個までです。

  • キーと値の両方が 128 バイト以下である必要があります。

  • キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。

  • キーは、小文字または国際文字で始める必要があります。

  • すべての文字には UTF-8 エンコーディングを使用する必要があります。 国際文字も使用できます。

--labels フラグ（gcloud deploy releases create など）には、以下のように Key-Value ペアのリストを指定できます。

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

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

Cloud Deploy リソースにアノテーションとラベルを追加する

アノテーションとラベルは、次の 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 PR、作成者、または Git commit の SHA ハッシュへの参照を含めることができます。詳細については、アノテーションを使用してリリースの出所を追跡するをご覧ください。

  • ロールアウト

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

    最初のロールアウトにアノテーションとラベルを追加するには、gcloud deploy releases create コマンドで --initial-rollout-labels または --initial-rollout-annotations を指定します。

    ロールアウトのアノテーションを使用すると、次のようなことができます。

    • テスト結果を指定する 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 コンソールの場合

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

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

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

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

Cloud Console でのリリースの詳細

Cloud Deploy の自動ラベル

デフォルトでは、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。これはリリース スナップショットから取得されます。

使用例

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

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

自動ラベルの無効化

規制やコンプライアンス上の理由などにより、組織がこれらの自動ラベルを禁止することがあります。これをサポートするために、組織のポリシー サービスは、これらのラベルを適用するかどうかを設定する制約を提供します。

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

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