クラスタとノードプールのラベルを作成して管理する

このページでは、Google Kubernetes Engine（GKE）のクラスタラベルとノードプール ラベルの概要について説明します。

GKE クラスタ / ノードプールのラベルと Kubernetes のラベル

GKE クラスタとノードプールのラベルは、Kubernetes のラベルとは異なります。 2 つのラベル付けシステムは独立して動作し、ラベルの継承や共有はされません。

GKE クラスタとノードプールのラベルは、リソースに関連付けられる任意のメタデータであり、使用状況や課金情報をトラックするために使用できます。

これとは別に、Kubernetes ではシステムが内部でラベルを使用して、クラスタのコンポーネントとリソース（Pod やノードなど）を相互に関連付け、リソースのライフサイクルを管理します。Kubernetes ラベルは Kubernetes API で編集できます。GKE API を使用して、クラスタの作成またはクラスタの更新を行い、ノードの Kubernetes ラベルを編集することもできます。

クラスタラベルとは

クラスタラベルは、Google Cloud クラスタに割り当てることができる Key-Value ペアです。ラベルはこれらのリソースを整理し、必要な粒度に基づいてコストを大規模に管理する場合に役立ちます。各リソースにラベルを設定し、そのラベルに基づいてリソースをフィルタできます。ラベルに関する情報は課金システムに転送され、請求料金をラベル別に分類できます。組み込みの請求レポートにより、リソースラベルで費用をフィルタしてグループ化できます。また、ラベルを使用して請求データ エクスポートをクエリすることもできます。

クラスタラベルの要件

リソースに適用するクラスタラベルは、次の要件を満たす必要があります。

• 各リソースには、最大 64 個のクラスタラベルを設定できます。
• クラスタラベルは、Key-Value ペアにする必要があります。
• キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
• キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。キーは、小文字または国際文字で始める必要があります。
• クラスタラベルのキー部分は、単一のリソース内では一意である必要があります。ただし、複数のリソースで同じキーを使用できます

これらの上限は、各クラスタラベルのキーと値、およびクラスタラベルのある個々の Google Cloud リソースに適用されます。1 つのプロジェクト内のすべてのリソースに適用できるクラスタラベルの数に制限はありません。

クラスタラベルの一般的な用途

次に、クラスタラベルの一般的なユースケースを示します。

• チームまたはコストセンターのラベル: チームやコストセンターに基づいてラベルを追加し、各チームが所有するクラスタを区別します（例: team:research、team:analytics）。この種類のラベルは、費用計算または予算作成に使用できます。

• コンポーネント クラスタラベル: たとえば、component:redis、component:frontend、component:ingest、component:dashboard など。

• 環境またはステージのクラスタラベル: たとえば、environment:production、environment:test など。

• 状態クラスタラベル: たとえば、state:active、state:readytodelete、state:archive など。

• オーナー クラスタラベル: 運用担当チームの識別に使用されます（例: team:shopping-cart）。

• 請求の内訳: ノードプールのラベルを使用して、ノードプールごとに請求額を分類します。詳細については、クラスタコストの内訳の表示をご覧ください。

すべての API 呼び出しにタイムスタンプや個別の値を設定するなど、一意のラベルを多数作成することはおすすめしません。このアプローチの問題は、値が頻繁に変更される場合やカタログを混乱させるキーを使用している場合に、リソースを効果的にフィルタして報告することが困難になることです。

ラベルとタグ

ラベルは、リソースに対するクエリ可能なアノテーションとして使用できますが、ポリシーの条件の設定には使用できません。タグを使用すると、ポリシーをきめ細かく制御することによって、リソースに特定のタグが付加されているかどうかに基づいて、条件付きでポリシーを許可または拒否することが可能になります。詳細については、タグの概要をご覧ください。

自動的に適用されるラベル

GKE は、クラスタ リソースに複数のラベルを自動的に適用します。

たとえば、Compute Engine インスタンス、永続ディスク、アクセラレータ（TPU）にラベルを適用します。

次の表に、GKE がリソースに自動的に適用するラベルを示します。

予約済みラベルの編集や削除は行わないでください。予約済みラベルに加えた変更は、自動的に調整されます。

ラベルの伝播

GKE では、クラスタと Standard モードのノードプールにラベルを適用できます。クラスタにラベルを付けると、そのラベルはノード、インスタンス、永続ディスクなど、クラスタの個々のリソースにすべて伝播されます。ノードプールにラベルを付けると、そのラベルはインスタンス、永続ディスクなど、ノードプールの個々のリソースにすべて伝播されます。Standard クラスタでは、クラスタラベルがノードプール ラベルと競合する場合（ラベルキーが同じで値が異なる場合など）、ノードプール ラベルがクラスタラベルをオーバーライドします。

クラスタまたはノードプールに適用したラベルは、1 時間ごとに実行されるバックグラウンド プロセスを介して伝播されます。特定のクラスタに関連付けられているすべてのリソースにラベルが表示されるまでに、最大で 1 時間かかることがあります。また、ラベルは、Compute Engine インスタンスと、Compute Engine インスタンスにアタッチされているゾーンの Persistent Disk にのみ伝播されます。ワークロード、転送ルール、IP アドレス、アタッチされていない Persistent Disk などの他のリソースにはラベルは付けられません。

Standard クラスタの場合、クラスタラベルとノードプール ラベルを Compute Engine リソースに適用すると、それらの変更が GKE によって調整されることなく、リソースラベルを手動で変更できます。Autopilot クラスタでは、GKE がノードを管理するため、Compute Engine リソースのラベルを手動で変更することはできません。これらのラベルは GKE で管理することをおすすめします。これらの Compute Engine リソースの既存のラベルは、自動的に適用されるラベルと競合しない限り、GKE によって削除されません。

始める前に

作業を始める前に、次のことを確認してください。

• Google Kubernetes Engine API を有効にする。
Google Kubernetes Engine API の有効化
• このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。

API リクエストに使用するラベルのフィンガープリントの取得

Google Cloud コンソールまたは gcloud CLI を使用している場合は、この手順をスキップできます。

GKE API を使用してクラスタラベルを更新または追加する際は、リクエストに最新のクラスタラベルのフィンガープリントを入力して、他のリクエストとの競合を防ぐ必要があります。

最新のクラスタラベルのフィンガープリントを取得するには、該当するクラスタに対して GET リクエストを実行します。例:

GET https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster

出力は次のようになります。

200 OK

{

 "name": "mycluster",
 "description": "production-cluster",
 "initialNodeCount": 3,
 ...
 "resourceLabels": {
    "environment": "production",
    ...
  },
  "labelFingerprint": "p1ty_9HoBk0="
}

この出力で、labelFingerprint プロパティはクラスタラベルのフィンガープリントです。

ラベル付きのクラスタを作成する

ラベル付きの Autopilot クラスタと Standard クラスタを作成するには、gcloud CLI、Google Cloud コンソール、GKE API、または Terraform を使用します。

gcloud container clusters create-auto CLUSTER_NAME \
    --labels=KEY=VALUE

gcloud container clusters create CLUSTER_NAME \
    --labels=KEY=VALUE

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-labels"
  location = "us-central1"

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-central1"
  initial_node_count = 2

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

既存のクラスタのラベルを追加または更新する

gcloud CLI、Google Cloud コンソール、または GKE API を使用して、既存のAutopilot クラスタと Standard クラスタのラベルを追加または更新できます。

gcloud container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --update-labels=KEY=VALUE

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": {
  "environment": "production",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

クラスタラベルを削除する

gcloud CLI、Google Cloud コンソール、または GKE API を使用して、Autopilot クラスタと Standard クラスタからラベルを削除できます。

gcloud container clusters update CLUSTER_NAME \
    --remove-labels=KEYS

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

ラベル付き Standard ノードプールを作成する

Standard クラスタにラベル付きノードプールを作成するには、gcloud CLI、Google Cloud コンソール、または GKE API を使用します。

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

既存のノードプールのラベルを追加または更新する

gcloud CLI、Google Cloud コンソール、または GKE API を使用して、既存ノードプールのラベルを追加または更新できます。

この変更を行うにはノードを再作成する必要があります。これにより、実行中のワークロードが中断する可能性があります。この特定の変更について詳しくは、メンテナンス ポリシーを尊重せずにノードのアップグレード戦略を使用してノードを再作成する手動変更の表で対応する行をご覧ください。ノードの更新の詳細については、ノードの更新による中断の計画をご覧ください。

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

ノードプール ラベルを削除する

gcloud CLI、Google Cloud コンソール、または GKE API を使用して、ノードプールからラベルを削除できます。

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

次のステップ

GKE の概要を読む。