ラベルは互いに関連するリソースを簡単にグループ化するための方法です。たとえば一般的な方法としては、本番環境用、ステージング用、開発用それぞれのリソースを別個にラベル付けして、各開発段階に属するリソースを必要に応じて簡単に検索できるようにします。vmrole:webserver
、environment:production
、location:west
などのラベルを作成できます。ラベルは Key-Value ペアで追加します。
{
"labels": {
"vmrole": "webserver",
"environment": "production",
"location": "west",...
}
}
ラベルは次のリソースに適用できます。
- 仮想マシン インスタンス
- 転送ルール(アルファ版)
- イメージ
- 永続ディスク
- 永続ディスクのスナップショット
- 静的外部 IP アドレス(アルファ版)
- VPN トンネル(アルファ版)
リソースにラベルを追加すると、ネスト化フィルタリングなどの機能を利用して、より正確な検索を行うことができます。
始める前に
- このガイドのコマンドラインの例を使用する場合、以下を行います。
- gcloud コマンドライン ツールの最新バージョンをインストールするか、最新バージョンに更新します。
- デフォルトのリージョンとゾーンを設定します。
- このガイドの API の例を使用する場合、API アクセスを設定します。
- 永続ディスクのドキュメントをお読みください。
- イメージのドキュメントをお読みください。
制限事項
- 各リソースには最大 64 のラベルを割り当てることができます。
- アルファ版のリソースは、
gcloud
または Google Cloud Platform Console でサポートされていません。これらのリソースにラベルを設定する場合には、アルファ版の API を使用してください。 ラベルのキーと値には次の制限があります。
- キーと値は、それぞれ 63 文字以下にする必要があります。
- キーと値に使用できるのは、小文字、数字、アンダースコア、ダッシュだけです。国際文字も使用可能。
- ラベルのキーは小文字で始める必要があります。国際文字は使用できます。
- ラベルのキーは空にできません。
ラベルの付いたリソースの作成
リソースを新規作成する際は、そのリソースにラベルを適用することができます。
Console
- [インスタンスの作成] ページに移動します。
- [管理、セキュリティ、ディスク、ネットワーク、単一テナンシー] セクションを展開します。
- [管理] で、このリソースに追加する [ラベル] を指定します。
- 作成プロセスを続行します。
gcloud
リソースを作成する場合は、--labels
フラグを指定し、それに続けてラベルの Key-Value ペアをカンマ区切りのリストとして指定します。次に例を示します。
gcloud compute instances create ... --labels webserver=backend,media=images
イメージやディスクの作成時にもこれと同じフラグを指定します。
API
API で、新しいリソースを追加する POST
リクエストを発行する際、リクエストの本文中に labels
プロパティを追加すると、新しいリソースにラベルを適用できます。たとえば、VM インスタンスを作成する場合、リクエストの本文には labels プロパティを次のように追加します。
body = {
"name": "[INSTANCE_NAME]",
"machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
...,
"labels": [{
"key": "webserver",
"value": "backend"
},
{
"key": "media",
"value": "images"
}]
}
イメージやディスクの作成時にもこれと同じプロパティを指定できます。
既存のリソースのラベルの追加または更新
リソースにラベルを追加したり、既存のラベルを更新したりできます。
Console
- ラベルを追加するそれぞれのリソースのページに移動します。
- インスタンスの場合は、[VM インスタンス] ページに移動します。
- ディスクの場合は、[ディスク] ページに移動します。
- スナップショットの場合は、[スナップショット] ページに移動します。
- イメージの場合は、[イメージ] ページに移動します。
- ラベルを付けるリソースの横のチェックボックスをオンにします。
- [情報パネルを表示] をクリックして、ラベルの列を展開します。
- 必要に応じて、ラベルを更新したり、新しいラベルを追加したりします。
- 変更を保存します。
gcloud
ラベルを追加または変更するには、gcloud
コマンドライン ツールの update
サブコマンドで --update-labels
フラグを使用します。たとえば、ディスクにラベルを追加するには gcloud compute disks update [DISK] --update-labels
サブコマンドを使用します。
gcloud compute disks update example-disk --update-labels backend=webserver,media=images
既存のラベルのキーを指定すると、既存のキーが新しいラベル値で更新されます。新しいキーを指定すると、ラベルのリストに新しいキーが追加されます。
たとえば、インスタンス、スナップショット、イメージには、gcloud compute instances
、gcloud compute snapshots
、gcloud compute images
の各コマンドを使用します。
API
ラベルを追加または更新するには、本文にラベルの最新のフィンガープリントと適用するラベルの完全なリストを含めた POST
リクエストを、該当するリソースの setLabels
メソッドに対して実行します。
メタデータやタグの場合と同様に、リソースの既存のラベルを残す場合には、新たに追加するラベルと一緒に、これらのラベルをリクエストに指定します。
たとえば、次のスニペットは、インスタンスの setLabels
メソッドに対してリクエストを実行します。ディスク、スナップショット、イメージの setLabels
メソッドに対してリクエストを実行することもできます。
Request
POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels
{
"labels": {
"environment": "test",
"an-existing-tag": ""
},
"labelFingerprint": "42WmSpB8rSM="
}
同様に、リソースの作成時に labels
オブジェクトを指定すれば、リソースにラベルを追加できます。
API リクエストに使用するラベルのフィンガープリントの取得
API でラベルを更新または追加するときは、リクエストに最新のラベルのフィンガープリントを入力して、他のリクエストとの競合を防止する必要があります。フィンガープリントが必要となるのは、API リクエストを使用する場合のみです。GCP Console や gcloud
ツールを使用する場合、フィンガープリントは必要ありません。
リクエストを行うため最新のラベルのフィンガープリントを取得するには、それぞれのリソースに対して GET
リクエストを実行します。たとえば、次のスニペットは、インスタンスの labelsFingerprint
を取得します。同様のリクエストを、ディスク、スナップショット、イメージに対して実行することもできます。
次のように labelFingerprint
プロパティを確認します。
Request
GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance
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=" }
ラベルの削除
Console
- ラベルを追加するそれぞれのリソースのページに移動します。
- インスタンスの場合は、[VM インスタンス] ページに移動します。
- ディスクの場合は、[ディスク] ページに移動します。
- スナップショットの場合は、[スナップショット] ページに移動します。
- イメージの場合は、[イメージ] ページに移動します。
- ラベルを削除するリソースの横にあるチェックボックスをオンにします。
- [情報パネルを表示] をクリックして、ラベルの列を展開します。
- 削除するラベルの横にある
X
をすべてクリックします。 - 変更を保存します。
gcloud
gcloud
コマンドライン ツールを使用する場合は、--remove-labels
フラグを指定して update
コマンドを実行します。削除するラベルのキーを指定します。次に例を示します。
gcloud compute disks update example-disk --remove-labels backend,media
スナップショットとイメージの場合は、gcloud compute snapshots
コレクションまたは gcloud compute images
コレクションを使用します。
API
API で、該当する API リソース(インスタンス、ディスク、スナップショット)の setLabels
メソッドに対して POST
リクエストを実行します。
現在の labelsFingerprint
とラベルの空のリストを指定して、すべてのラベルを削除します。あるいは、削除するラベルのリストは省略し、削除しないラベルのリストを指定します。次に例を示します。
Request
POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels
{
"labels": { },
"labelFingerprint": "42WmSpB8rSM="
}
ラベルを使用した検索結果のフィルタリング
リソースの検索結果をラベルでフィルタリングできます。
Console
- ラベルを追加するそれぞれのリソースのページに移動します。
- インスタンスの場合は、[VM インスタンス] ページに移動します。
- ディスクの場合は、[ディスク] ページに移動します。
- スナップショットの場合は、[スナップショット] ページに移動します。
- イメージの場合は、[イメージ] ページに移動します。
- プロンプトが表示されたら、プロジェクトを選択して [続行] をクリックします。
- 検索バーに「
labels.
」を入力すると、フィルタを適用できるラベルが自動的に表示されます。
gcloud
gcloud
では、list
リクエストを作成し、--filter
フラグを使用します。ラベルでフィルタリングを行うには、構文 labels.key=[VALUE]
を使用します。たとえば、キーが env
で値が dev
のラベルでフィルタリングする場合は、次のコマンドを実行します。
gcloud compute instances list --filter labels.env=dev
gcloud
ツールのフィルタ構文の詳細な説明については、gcloud topic filters
に関するドキュメントをご覧ください。
API
API では、list リクエストを作成し、URL エンコードされた filter
クエリ パラメータを指定します。たとえば、ラベルキー env
が値 dev
と等しいという条件でフィルタリングするには、次の GET
リクエストを行います。
GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/list?filter=labels.env+eq+dev
詳細については、API リファレンスの filter
に関するドキュメントをご覧ください。
インスタンスのラベルとネットワーク タグの関係
以前は、ラベルとタグが関連していました。たとえば、webserver:test
ラベルを VM インスタンスに追加すると、Compute Engine はそのインスタンスに自動的に webserver
タグを追加していました。
現在は、ラベルとタグが互いに独立しています。インスタンスにラベルを作成しても、Compute Engine はそのインスタンスのタグを作成しません。インスタンスにタグを作成する必要がある場合は、手動でタグを作成する必要があります。
タグを作成する方法については、ネットワーク タグのページをご覧ください。