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

このページでは、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 がリソースに自動的に適用するラベルを示します。

ラベル	適用されるリソース
`goog-gke-node`	GKE ノードの基盤となる Compute Engine VM インスタンス。
`goog-gke-volume`	GKE ノードの基盤となる VM インスタンスにアタッチされた Compute Engine 永続ディスク。
`goog-gke-tpu`	GKE の Cloud TPU。
`goog-k8s-cluster-name`	GKE ノードの基盤となる Compute Engine VM インスタンスと、VM インスタンスにアタッチされている永続ディスク。
`goog-k8s-cluster-location`	GKE ノードの基盤となる Compute Engine VM インスタンスと、VM インスタンスにアタッチされている永続ディスク。
`goog-k8s-node-pool-name`	GKE ノードの基盤となる Compute Engine VM インスタンスとそのブートディスク。
`goog-fleet-project`	クラスタがフリートに登録されている場合、GKE ノードの基盤となる Compute Engine VM インスタンスと、VM インスタンスにアタッチされている永続ディスク。

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

ラベルの伝播

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 を実行して最新のバージョンを取得します。
注: gcloud CLI がすでにインストールされている場合には、必ず compute/region と compute/zone のプロパティを設定してください。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防ぐことができます。

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

ラベル付きの Autopilot クラスタを作成するには、次のコマンドを実行します。

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

ラベル付きの Standard クラスタを作成するには、次のコマンドを実行します。

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

次のように置き換えます。

CLUSTER_NAME: クラスタの名前。
KEY: ラベルの Key-Value ペアのキー。
VALUE: ラベルの Key-Value ペアの値。

コンソール

クラスタの作成時にラベルを追加する手順は次のとおりです。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
[ 作成] をクリックします。
[Autopilot] または [Standard] で [構成] をクリックします。
クラスタを構成します。
ナビゲーションパネルの [クラスタ] の下の [メタデータ] をクリックします。
[ラベルを追加] をクリックします。
ラベルを追加します。
[作成] をクリックします。

API

クラスタの作成時にラベルを設定するには、projects.zones.clusters.create に指定する cluster オブジェクト内に resourceLabels オブジェクトを指定します。

Terraform

Terraform を使用してラベル付きの Autopilot クラスタを作成するには、次の例を参照してください。

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
}

Terraform を使用してラベル付きの Standard クラスタを作成するには、次の例を参照してください。

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-west1"
  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
}

Terraform を使用する詳細については、GKE での Terraform のサポートをご覧ください。

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

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

gcloud

次のコマンドを実行します。

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

次のように置き換えます。

CLUSTER_NAME: クラスタの名前。
COMPUTE_REGION: 新しいクラスタの Compute Engine のリージョン。ゾーン Standard クラスタの場合は、--zone=COMPUTE_ZONE を使用します。
KEY: ラベルの Key-Value ペアのキー。
VALUE: ラベルの Key-Value ペアの値。

ラベルを更新すると、クラスタの既存のラベルが上書きされます。クラスタの既存のラベルを保持する場合は、追加する新しいラベルとともに既存のラベルを含める必要があります。

コンソール

ラベルを追加または更新する手順は次のとおりです。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
[クラスタの詳細] ページで、変更する 1 つ以上のクラスタのチェックボックスをオンにします。
[ラベル] をクリックします。
ラベルを追加または更新します。
[保存] をクリックします。

API

最新のフィンガープリントと適用するラベルの完全なリストを指定したクラスタの resourceLabels メソッドに POST リクエストを行います。

メタデータやタグの場合と同様に、クラスタの既存のラベルを残したい場合は、追加する新しいラベルとともに、既存のラベルをリクエストに含める必要があります。

たとえば、次のスニペットは、resourceLabels メソッドにリクエストを行います。

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

--remove-labels フラグを指定して update コマンドを実行します。

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

次のように置き換えます。

CLUSTER_NAME: クラスタの名前。
KEYS: 削除するラベルキーのカンマ区切りリスト。

コンソール

ラベルを削除する手順は次のとおりです。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
クラスタリストで、変更するクラスタ（1 つまたは複数）のチェックボックスをオンにします。
[ラベル] をクリックします。
削除するラベルの [値] フィールドの横にある [アイテムの削除] をクリックします。
[保存] をクリックします。

API

該当するクラスタの resourceLabels メソッドに POST リクエストを行います。すべてのラベルを削除するには、現在の labelsFingerprint とラベルの空のリストを指定します。あるいは、削除しないラベルのリストを指定します（削除するラベルは省略します）。次に例を示します。

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

次のコマンドを実行します。

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

次のように置き換えます。

NODE_POOL_NAME: ノードプールの名前。
CLUSTER_NAME: クラスタの名前。
COMPUTE_REGION: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE を使用します。
KEY: ラベルの Key-Value ペアのキー。
VALUE: ラベルの Key-Value ペアの値。

API

ノードプールの作成時にラベルを含めるには、projects.zones.clusters.nodePools.create に指定するノードプールオブジェクト内の resourceLabels オブジェクトを指定します。

コンソール

新しいノードプールにラベルを追加する手順は次のとおりです。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
[クラスタの詳細] ページで、変更するクラスタの名前をクリックします。
[ ノードプールを追加] をクリックします。
新しいノードプールを構成します。
ナビゲーションパネルで [メタデータ] をクリックします。
[ラベルを追加] をクリックします。
ラベルを追加します。
[作成] をクリックします。

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

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

gcloud

次のコマンドを実行します。

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

次のように置き換えます。

NODE_POOL_NAME: ノードプールの名前
CLUSTER_NAME: クラスタの名前。
COMPUTE_REGION: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE を使用します。
KEY: ラベルの Key-Value ペアのキー。
VALUE: ラベルの Key-Value ペアの値。

ラベルを更新すると、ノードプールの既存のラベルが上書きされます。ノードプールの既存のラベルを保持する場合は、追加する新しいラベルとともに既存のラベルを含める必要があります。

API

ノードプールの変更時にラベルを含めるには、projects.zones.clusters.nodePools.update に指定するノードプールオブジェクト内の resourceLabels オブジェクトを指定します。

コンソール

ラベルを追加または更新する手順は次のとおりです。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
クラスタのリストで、変更するノードプールを含むクラスタの名前をクリックします。
[ノードプール] セクションで、変更するノードプールの名前をクリックします。
[編集] をクリックします。
[ラベル] で、ラベルを追加または更新します。
[保存] をクリックします。

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

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

gcloud

次のコマンドを実行します。

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

次のように置き換えます。

NODE_POOL_NAME: ノードプールの名前。
CLUSTER_NAME: クラスタの名前。
COMPUTE_REGION: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE を使用します。
KEY: ラベルの Key-Value ペアのキー。
VALUE: ラベルの Key-Value ペアの値。

ラベルを更新すると、ノードプールの既存のラベルが上書きされます。ノードプールにある既存のラベルを残す場合は、削除するラベルを除外する必要があります。すべてのラベルを削除するには、Key-Value ペアなしで --labels= を使用します。

API

ノードプールの変更時にラベルを含めるには、projects.zones.clusters.nodePools.update に指定するノードプールオブジェクト内の resourceLabels オブジェクトを指定します。すべてのラベルを削除するには、ラベルの空のリストを指定します。あるいは、削除しないラベルのリストを指定します。削除するラベルは省略します。

コンソール

ノードプールからラベルを削除するには、次の操作を行います。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
クラスタのリストで、変更するノードプールを含むクラスタの名前をクリックします。
[ノードプール] セクションで、変更するノードプールの名前をクリックします。
削除するラベルの [値] フィールドの横にある [アイテムの削除] をクリックします。
[保存] をクリックします。

次のステップ

GKE の概要を読む。

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

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

クラスタラベルとは何か

クラスタラベルの要件

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

ラベルとタグ

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

ラベルの伝播

始める前に

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

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

gcloud

コンソール

API

Terraform

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

gcloud

コンソール

API

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

gcloud

コンソール

API

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

gcloud

API

コンソール

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

gcloud

API

コンソール

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

gcloud

API

コンソール

次のステップ

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