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

ラベルは、関連するリソースをグループ化するために 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. Google Cloud CLI をインストールします。 インストール後、次のコマンドを実行して Google Cloud CLI を初期化します。 

      gcloud init

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

    2. Set a default region and zone.

    REST

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

      Google Cloud CLI をインストールします。 インストール後、次のコマンドを実行して Google Cloud CLI を初期化します。 

      gcloud init

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

    詳細については、 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 コンポーネントにもラベルを使用できます。

  • Cloud Storage バケット
  • ネットワーキング リソース:
    • 内部アプリケーション ロードバランサで使用される転送ルール（内部アプリケーション ロードバランサ以外のロードバランサの転送ルールはサポートされていません）
    • VPN トンネル（プレビュー）
    • 静的外部 IP アドレス（プレビュー）

たとえば、次のラベルを 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

REST

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 は既存のキーを新しいラベル値で更新します。新しいキーを指定すると、新しいキーがラベルのリストに追加されます。

REST

ラベルを追加または更新するには、最新のフィンガープリントと適用するラベルの完全なリストを指定して、リソースの 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
...

REST

ラベルを取得するには、次のリソースに対して 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 console コンソールまたは 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

REST

ラベルを削除するには、最新のフィンガープリントと適用するラベルの完全なリストを指定して、リソースの 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 のドキュメントをご覧ください。

REST

リソースをフィルタするには、次のリソースの 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 にタグを作成する必要がある場合は、手動で作成する必要があります。

タグとその用途の詳細については、タグの概要をご覧ください。

次のステップ