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 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 コンソールの場合

このようなメタデータを含む 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 を適用します。この制約を適用しても、ラベルを手動で指定することはできません。また、既存のリリースからラベルを削除することもできません。

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