ラベルを使用してリソースを整理する

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

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

始める前に

  • 永続ディスクのドキュメントをお読みください。
  • イメージのドキュメントをお読みください。
  • まだ設定していない場合は、認証を設定します。認証とは、Google Cloud サービスと API にアクセスするために ID を確認するプロセスです。ローカル開発環境からコードまたはサンプルを実行するには、次のように Compute Engine に対する認証を行います。

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

      このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      詳細については、Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

ラベルとは

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

ラベルとタグ

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

Compute Engine でラベルを使用する

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

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

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

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

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

ラベルを適用したリソースを作成する

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

コンソール

  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": {
   "webserver": "backend",
   "media": "images"
  }
}

既存のリソースへのラベルの追加や更新

Google Cloud コンソール、gcloud CLI、または Compute Engine API を使用して、リソースにラベルを追加したり、既存のラベルを更新したりできます。転送ルールのラベルを追加または更新するには、gcloud CLI または Compute Engine API を使用します。

コンソール

  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

既存のラベルキーを指定すると、Google Cloud CLI は既存のキーを新しいラベル値で更新します。新しいキーを指定すると、新しいキーがラベルのリストに追加されます。

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="
}

ラベルを表示する

Google Cloud コンソール、gcloud CLI、または Compute Engine API を使用して、リソースのラベルを表示できます。転送ルールのラベルを表示するには、gcloud CLI または Compute Engine API を使用します。

コンソール

  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 リクエストを使用する場合のみです。Google Cloud コンソールと Google Cloud CLI ツールの場合、フィンガープリントは必要ありません。

最新の 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="
}

ラベルを削除する

Google Cloud コンソール、gcloud CLI、または Compute Engine API を使用して、リソースからラベルを削除できます。転送ルールのラベルを削除するには、gcloud CLI または Compute Engine API を使用します。

コンソール

  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="
}

ラベルを使用して検索結果をフィルタする

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

コンソール

  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 CLI のフィルタ構文の詳細については、gcloud topic filters のドキュメントをご覧ください。

API

リソースをフィルタするには、次のリソースの list メソッドに対して GET リクエストを実行します。その際、フィルタ フィールドを含めます。

たとえば、プロジェクト myproject、ゾーン us-central1-a の VM で env:dev という Key-Value ペアのラベルを持つすべての VM を一覧表示するには、list リクエストの labels.env:dev にフィルタ フィールドを設定します。クエリ文字列パラメータとしてフィルタ フィールドを含める場合は、URL エンコードされたパラメータ値 filter=labels.env%3Adev を使用します。

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?filter=labels.env%3Adev

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

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

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

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

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

次のステップ