ラベルの作成と管理

ラベルとは、関連するリソースをグループ化するために Google Cloud で使用できる Key-Value ペアのことです。たとえば、Compute Engine では、ラベルを使用して、本番環境、ステージング環境、開発環境などのカテゴリで VM をグループ化し、各開発段階に属するリソースを検索できます。

リソースにラベルを追加すると、ネスト化フィルタリング機能により、ラベルを使用してリソースをより正確に検索できます。

始める前に

ラベルとは

ラベルとは、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 つのプロジェクト内のすべてのリソースに適用できるラベルの数に上限はありません。

Compute Engine でのラベルの使用

ラベルは次の Compute Engine リソースに適用できます。

  • 仮想マシン(VM)インスタンス
  • イメージ
  • 永続ディスク
  • 永続ディスクのスナップショット

次のような関連する Google Cloud コンポーネントにもラベルを使用できます。

たとえば、次のラベルを Key-Value ペアとしてリソースに追加できます。

{
 "labels": {
    "vmrole": "webserver",
    "environment": "production",
    "location": "west",...
    }
 }

ラベルの付いたリソースの作成

リソースを新規作成する際は、そのリソースにラベルを適用できます。

Console

  1. 作成するリソースのページに移動します。

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

  3. 作成プロセスを続行します。

gcloud

ラベルを追加するには、--labels フラグを指定して create サブコマンドを実行します。次の gcloud コマンドを使用して、Compute Engine リソースにラベルを追加できます。

gcloud compute instances create ... \
    --labels webserver=backend,media=images

API

API で、新しいリソースを追加する POST リクエストを発行するときに、リクエストの本文中に labels プロパティを追加して新しいリソースにラベルを適用します。

たとえば、次のスニペットは、webserver:backendmedia:images というラベルの付いた VM インスタンスを作成する POST リクエストを作成します。

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances

{
 "name": "myVM",
 "machineType": "zones/us-central1-f/machineTypes/custom-2-15360-ext",
  ...,
 "labels": [{
   "key": "webserver",
   "value": "backend"
   },
   {
   "key": "media",
   "value": "images"
  }]
}

既存のリソースのラベルの追加または更新

リソースへのラベルの追加または既存のラベルの更新を行う場合は、Cloud Console、gcloud ツール、または Compute Engine API を使用します。転送ルールのラベルを追加または更新するには、gcloud ツールまたは Compute Engine API を使用します。

Console

  1. ラベルを追加するリソースのページに移動します。

  2. ラベルを付けるリソースの横のチェックボックスをオンにします。

  3. ラベル列を展開するには、[情報パネルを表示] をクリックします。

  4. パネルで [ラベル] を選択します。

  5. ラベルを追加するには、[ ラベルを追加] をクリックして Key-Value ペアを追加します。

  6. ラベルを更新するには、既存のラベルを選択して値を変更します。

  7. 変更を保存します。

gcloud

ラベルを追加または変更するには、--update-labels フラグを指定して update サブコマンドを実行します。Compute Engine リソースのラベルを更新するには、次の gcloud コマンドを使用します。

gcloud compute disks update example-disk \
    --update-labels backend=webserver,media=images

すでに存在するラベルキーを指定すると、gcloud コマンドライン ツールは既存のキーを新しいラベル値で更新します。新しいキーを指定すると、新しいキーがラベルのリストに追加されます。

API

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

メタデータやタグの場合と同様に、リソースの既存のラベルを残す場合には、新たに追加するラベルと一緒に、これらのラベルをリクエストに指定します。

たとえば、次のスニペットは、environment:testan-existing-tag:yes というラベルを設定するように POST リクエストを VM インスタンスに送信します。

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": {
  "environment": "test",
  "an-existing-tag": "yes"
 },
 "labelFingerprint": "42WmSpB8rSM="
}

ラベルの表示

リソースのラベルを表示するには、Cloud Console、gcloud ツール、または Compute Engine API を使用します。転送ルールのラベルを表示するには、gcloud ツールまたは Compute Engine API を使用します。

Console

  1. リソースのページに移動します。

  2. リソースをクリックすると詳細が表示されます。

  3. ラベルを見つけます。

gcloud

ラベルを表示するには、describe サブコマンドを使用します。Compute Engine リソースのラベルを表示するには、次の gcloud コマンドを使用します。

gcloud compute disks describe example-disk

出力にラベルが含まれます。

...
id: '5047929990219134234'
kind: compute#disk
labelFingerprint: GHZ1Un209U=0
labels:
  environment: dev
  department: finance
...

API

ラベルを取得するには、次のリソースに対して GET リクエストを行います。

たとえば、次のスニペットは、VM インスタンスのラベルを取得する GET リクエストを行います。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

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

  • PROJECT_ID: プロジェクト ID
  • ZONE: VM のゾーン
  • VM_NAME: VM の名前

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

API でラベルを更新または追加するときは、リクエストに最新のラベルのフィンガープリントを入力して、他のリクエストとの競合を防止する必要があります。フィンガープリントが必要となるのは、API リクエストを使用する場合のみです。Cloud Consolegcloud ツールの場合、フィンガープリントは必要ありません。

最新の labelsFingerprint を取得するには、次のリソースに対して GET リクエストを行います。

たとえば、次のスニペットは VM インスタンスの labelsFingerprint を取得します。

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance

レスポンスには、labelFingerprint プロパティが含まれます。

200 OK

{
 "kind": "compute#instance",
 "id": "4392196237934605253",
 "creationTimestamp": "2015-09-15T14:05:16.475-07:00",
 "zone": "https://content.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f",
 "status": "RUNNING",
 ...
 "labels": {
  "environment": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

ラベルの削除

リソースからラベルを削除するには、Cloud Console、gcloud ツール、または Compute Engine API を使用します。転送ルールのラベルを削除するには、gcloud ツールまたは Compute Engine API を使用します。

Console

  1. ラベルを削除するリソースのページに移動します。

  2. ラベルを削除するリソースの横にあるチェックボックスをオンにします。

  3. ラベル列を展開するには、[情報パネルを表示] をクリックします。

  4. ラベルを削除するには、[ 削除] をクリックします。

  5. 変更を保存します。

gcloud

ラベルを追加または変更するには、--remove-labels フラグを指定して update サブコマンドを実行します。Compute Engine リソースのラベルを削除するには、次の gcloud コマンドを使用します。

gcloud compute disks update example-disk \
    --remove-labels backend,media

API

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

すべてのラベルを削除するには、現在の labelsFingerprint とラベルの空のリストを指定します。あるいは、削除しないラベルのリストを指定します(削除するラベルは指定しない)。たとえば、次のスニペットは VM からすべてのラベルを削除します。

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

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

ラベルを使用した検索結果のフィルタリング

リソースの検索結果をラベルでフィルタするには、Cloud Console、gcloud ツール、または Compute Engine API を使用します。転送ルールをラベルでフィルタするには、gcloud ツールまたは Compute Engine API を使用します。

Console

  1. フィルタされたリソースのリストを取得するリソースのページに移動します。

  2. プロンプトが表示されたら、プロジェクトを選択して [続行] をクリックします。

  3. 検索バーに、key、value、または Key-Value ペアを入力します。結果には、部分一致が含まれます。

    たとえば、env:dev というラベルのリソースのみを表示するには、次のいずれかを入力します。

    • キー env を入力します。
    • dev を入力します。
    • Key-Value ペア env:dev を入力します。

gcloud

ラベルに基づいてフィルタリングするには、--filter フラグを指定して、次のリソースの list サブコマンドを実行します。

--filter フラグの値は labels.KEY=VALUE 形式にする必要があります。たとえば、キーが env で値が dev のラベルでフィルタする場合は、次のコマンドを実行します。

gcloud compute instances list \
    --filter labels.env=dev

gcloud ツールのフィルタ構文の詳細については、gcloud topic filters のドキュメントをご覧ください。

API

リソースをフィルタするには、次のリソースの list メソッドに対して GET リクエストを実行します。その際、URL エンコードの filter クエリ パラメータを指定します。

たとえば、ラベル env:dev でフィルタするには、クエリ文字列に filter=labels.env+eq+dev を指定して次の GET リクエストを行います。

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/list?filter=labels.env+eq+dev

詳細については、Compute Engine API リファレンスの filter のドキュメントをご覧ください。

VM ラベルとネットワーク タグの関係

以前は、ラベルとタグが関連していました。たとえば、webserver:test ラベルを VM に追加すると、Compute Engine がその VM に webserver タグを自動的に追加していました。

現在、ラベルとタグは互いに独立しています。VM にラベルを作成しても、Compute Engine は VM のタグを作成しません。VM にタグを作成する必要がある場合は、手動で作成する必要があります。

タグを作成する方法については、ネットワーク タグをご覧ください。

次のステップ