クラスタラベルの作成と管理

このページでは、GKE のクラスタラベルの概要を説明します。

クラスタラベルとは

クラスタラベルとは、Google Cloud のクラスタの整理に役立つ Key-Value ペアのことです。各リソースにラベルを設定し、そのラベルに基づいてリソースをフィルタリングできます。ラベルに関する情報は課金システムに転送されるため、ラベルを基準に請求料金を分析することもできます。

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

タイムスタンプやすべての API 呼び出しに個別に値を作成するなど、一意のラベルを多数作成することはおすすめしません。次に、クラスタラベルの一般的なユースケースを示します。

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

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

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

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

クラスタラベルの要件

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

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

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

始める前に

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

次のいずれかの方法で gcloud のデフォルトの設定を指定します。

  • gcloud init。デフォルトの設定全般を確認する場合に使用します。
  • gcloud config。プロジェクト ID、ゾーン、リージョンを個別に設定する場合に使用します。

gcloud init の使用

エラー One of [--zone, --region] must be supplied: Please specify location を受信した場合は、このセクションの内容を実施します。

  1. gcloud init を実行して、次の操作を行います。

    gcloud init

    リモート サーバーで SSH を使用している場合は、--console-only フラグを指定して、コマンドがブラウザを起動しないようにします。

    gcloud init --console-only
  2. 手順に従って gcloud を承認し、Google Cloud アカウントを使用します。
  3. 新しい構成を作成するか、既存の構成を選択します。
  4. Google Cloud プロジェクトを選択します。
  5. ゾーンクラスタの場合はデフォルトの Compute Engine ゾーン、リージョン クラスタまたは Autopilot クラスタの場合はデフォルトの Compute Engine リージョンを選択します。

gcloud config の使用

  • デフォルトのプロジェクト ID を設定します。
    gcloud config set project PROJECT_ID
  • ゾーンクラスタを使用する場合は、デフォルトのコンピューティング ゾーンを設定します。
    gcloud config set compute/zone COMPUTE_ZONE
  • Autopilot クラスタまたはリージョン クラスタを使用する場合は、デフォルトのコンピューティング リージョンを設定します。
    gcloud config set compute/region COMPUTE_REGION
  • gcloud を最新バージョンに更新します。
    gcloud components update

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

クラスタの作成後、GKE はクラスタ リソースに複数のラベルを自動的に適用します。たとえば、Compute Engine インスタンス、永続ディスク、アクセラレータ(TPU)にラベルを適用します。自動的に適用されるラベルには、特別な接頭辞(goog-gke-)が付いています。

次の goog-gke- ラベルは GKE のリソースに自動的に適用されます。Compute Engine レベルまたは GKE クラスタレベルの予約済みの goog-gke- ラベルに行った変更は、自動的に調整されます。このため、これらの予約済みラベルの編集や削除はおすすめしません。

ラベル 適用されるリソース
goog-gke-node GKE ノード
goog-gke-volume GKE ノードにアタッチした永続ディスク
goog-gke-tpu GKE の Cloud TPU

クラスタのラベル付けについて

GKE では、クラスタレベルでラベルを適用します。クラスタにラベルを付けると、そのラベルがクラスタの個々のリソース(ノードや永続ディスクなど)のすべてに伝播されます。

クラスタラベルを追加、更新、削除するには、Google Cloud Console、gcloud コマンドライン ツールまたは GKE API を使用します。

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

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

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

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

レスポンスに含まれる labelFingerprint プロパティを見つけます。

200 OK

{

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

ラベル付きクラスタの作成

ラベル付きクラスタを作成するには、gcloud ツール、Google Cloud Console、または GKE API を使用します。

gcloud

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

gcloud container clusters create [CLUSTER_NAME] --labels [KEY]=[VALUE]

例:

gcloud container clusters create example-cluster --labels env=dev

Console

クラスタを作成するときにラベルを追加するには:

  1. Cloud Console で Google Kubernetes Engine のメニューに移動します。

    Google Kubernetes Engine のメニューに移動

  2. [ 作成] をクリックします。

  3. 必要に応じてクラスタを構成します。

  4. ナビゲーション パネルの [クラスタ] の下の [メタデータ] をクリックします。

  5. [ラベルを追加] をクリックします。

  6. 必要なラベルを追加します。

  7. [作成] をクリックします。

API

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

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

gcloud

gcloud ツールでラベルを更新するには、次のコマンドを実行します。

gcloud container clusters update [CLUSTER_NAME] \
    [--region [REGION] | --zone [ZONE]] \
    --update-labels [KEY]=[VALUE]

例:

gcloud container clusters update example-cluster --zone us-west1-a \
    --update-labels env=dev,release=stable

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

Console

ラベルを追加または更新するには:

  1. Cloud Console で Google Kubernetes Engine のメニューに移動します。

    Google Kubernetes Engine のメニューに移動

  2. クラスタリストで、変更するクラスタを選択します(複数可)。

  3. 情報パネルが表示されていない場合は、[情報パネルを表示] をクリックします。

  4. 必要に応じてラベルを追加または更新します。

  5. [保存] をクリックします。

API

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

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

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

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

{
 "resourceLabels": {
  "env": "test",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

クラスタラベルの削除

gcloud

gcloud コマンドライン ツールで、--remove-labels フラグを指定して update コマンドを実行します。削除するラベルのキーを指定します。例:

gcloud container clusters update example-cluster --remove-labels env

Console

ラベルを削除するには:

  1. Cloud Console で Google Kubernetes Engine のメニューに移動します。

    Google Kubernetes Engine のメニューに移動

  2. クラスタリストで、変更するクラスタを選択します(複数可)。

  3. 情報パネルが表示されていない場合は、[情報パネルを表示] をクリックします。

  4. 削除するラベルの [] フィールドの横にある [アイテムを削除] をクリックします。

  5. [保存] をクリックします。

API

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

Request

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

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

次のステップ

GKE の概要を読む