ラベルの作成と管理

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

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

始める前に

ラベルとは

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

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

ラベルの一般的な用途

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

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

  • コンポーネント ラベル: component:redis、component:frontend、component:ingest、component:dashboard など。

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

  • 状態のラベル: state:active、state:readytodelete、state: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:backend と media: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:test と an-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 Console と gcloud ツールの場合、フィンガープリントは必要ありません。

最新の 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 にタグを作成する必要がある場合は、手動で作成する必要があります。

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

次のステップ