カスタムメタデータの設定と削除

Linux Windows

各メタデータエントリは、Key-Value ペアとしてメタデータサーバーに保存されます。メタデータキーでは大文字と小文字が区別されます。キーは、事前定義されたメタデータキーまたはカスタムメタデータキーのいずれかにすることができます。

カスタムメタデータを使用すると、個々の VM またはプロジェクトで、独自のメタデータの Key-Value ペアを作成して使用できます。新しいカスタムメタデータキーの追加、既存のキーの値の更新、不要なカスタムメタデータエントリの削除を行うことができます。カスタムメタデータの設定は、プロジェクト内の VM に任意の値を渡す場合に便利です。また、起動スクリプトとシャットダウンスクリプトを作成する場合にも役立ちます。

このドキュメントでは、以下の操作を行う方法について説明します。

VM でカスタムメタデータを追加または更新する
VM からカスタムメタデータを削除する

始める前に

Compute Engine の VM メタデータを定義、分類、配置する方法の基本を確認します。詳細については、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

必要なロール

VM でカスタムメタデータを設定または削除するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

VM またはプロジェクトに対する Compute インスタンス管理者（v1）（roles/compute.instanceAdmin.v1）
VM でサービスアカウントを使用する場合: サービスアカウントまたはプロジェクトに対するサービスアカウントユーザー（roles/iam.serviceAccountUser）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、VM のカスタムメタデータを設定または削除するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

VM でカスタムメタデータを設定または削除するには、次の権限が必要です。

VM でサービスアカウントを使用する場合: サービスアカウントまたはプロジェクトに対する iam.serviceAccounts.actAs
プロジェクトのカスタムメタデータを追加、更新、削除するには:
- プロジェクトに対する compute.projects.get
- プロジェクトに対する compute.projects.setCommonInstanceMetadata
カスタムゾーンメタデータを追加、更新、削除するには:
- プロジェクト内の必要なゾーンのインスタンス設定に対する compute.instanceSettings.get
- プロジェクト内の必要なゾーンのインスタンス設定に対する compute.instanceSettings.update
カスタムインスタンスメタデータを追加、更新、削除するには:
- VM に対する compute.instances.get
- VM に対する compute.instances.setMetadata

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

制限事項

Compute Engine では、すべてのメタデータエントリに対して合計で 512 KB の上限が適用されます。次のように、各 key と value に最大サイズの制限も適用されます。

各メタデータ key の上限は 128 バイトです。
各メタデータ key では大文字と小文字が区別されます。

プロジェクトゾーンメタデータの場合、Compute Engine では、同じ文字列を持つ 2 つのメタデータキーを別々に作成することはできません（大文字と小文字の表記が異なっていても同じ文字列とみなされます）。たとえば、project-zonal-metadata-key というゾーンメタデータのカスタムメタデータキーがすでにある場合、そのゾーンのゾーンメタデータに対して、Project-Zonal-Metadata-Key、PROJECT-ZONAL-METADATA-KEY のように、大文字と小文字が違っていても、文字列が同じであれば、新しいメタデータキーを作成することはできません。
各メタデータ value の上限は 256 KB です。
各メタデータ value では、ブール値を除き、大文字と小文字が区別されます。

たとえば、SSH 認証鍵は ssh-keys 鍵の下にカスタムメタデータとして保存されます。この鍵のメタデータコンテンツまたは value が 256 KB の上限を超えると、SSH 認証鍵を追加できなくなります。この制限に達した場合は、新しいキーのメタデータスペースを解放するために未使用のキーを削除することを検討してください。

また、起動スクリプトまたはシャットダウンスクリプトの内容を直接指定すると、これらのスクリプトの内容もカスタムメタデータとして保存され、サイズの制限にカウントされることがあります。これを避けるには、起動スクリプトまたはシャットダウンスクリプトを Cloud Storage などの外部の場所でホストされるファイルとして保存し、VM の作成時に起動スクリプトの URL を指定します。これらのファイルは、メタデータサーバーに保存されず、VM にダウンロードされます。

ブール値

ブール値、TRUE、FALSE のいずれかを受け入れるフィールドについては、次の値も使用できます。

ステータス	選択できる値
`TRUE`	`Y`、`Yes`、`1`
`FALSE`	`N`、`No`、`0`

ブール値では大文字と小文字は区別されません。たとえば、False、false、または FALSE を使用して機能を無効にできます。

VM にカスタムメタデータを設定する

このセクションでは、次のいずれかの方法で、Compute Engine VM に対して新しいカスタムメタデータを追加する方法、または既存のカスタムメタデータ値を更新する方法について説明します。

プロジェクトのカスタムメタデータを設定する。プロジェクト内のすべての VM のカスタムプロジェクトメタデータを追加または更新します。
カスタムゾーンメタデータを設定する。プロジェクト内の VM のゾーンスコープを使用して、カスタムメタデータを追加または更新します。
カスタムインスタンスメタデータを設定する。特定の VM のカスタムインスタンスメタデータを追加または更新します。

カスタムプロジェクトメタデータを設定する

Google Cloud コンソール、Google Cloud CLI、または REST を使用して、プロジェクト内のすべてのインスタンスのカスタムメタデータを追加または更新できます。

次の手順に沿って、プロジェクト内のすべての VM にメタデータ設定を適用します。たとえば、baz=bat というプロジェクトのメタデータペアを定義すると、対象のメタデータペアはプロジェクトのすべての VM に自動的に適用されます。

コンソール

Google Cloud コンソールで、[メタデータ] ページに移動します。
[カスタムメタデータ] ページに移動
ページ上部の [編集] をクリックします。
新しいカスタムプロジェクトメタデータエントリを追加するには、次の操作を行います。
1. ページの一番下まで移動し、 [項目を追加] をクリックします。
2. [キー] フィールドに、カスタムメタデータキーの名前を入力します。
3. [値] フィールドに、カスタムプロジェクトメタデータの値を入力します。
4. 省略可。カスタムプロジェクトのメタデータエントリを追加するには、追加するメタデータエントリごとに前述の手順を繰り返します。
5. カスタムプロジェクトメタデータエントリの追加を終了するには、[保存] をクリックします。
既存のカスタムプロジェクトメタデータエントリを編集するには、次の手順を行います。
1. 編集するメタデータエントリに移動します。
2. 特定のカスタムメタデータキーの名前を更新するには、対象のエントリの [キー] フィールドに新しい名前を入力します。
3. カスタムプロジェクトメタデータエントリの値を更新するには、対象のエントリの [値] フィールドに新しい値を入力します。
4. 省略可。特定のカスタムプロジェクトメタデータエントリを削除するには、メタデータエントリの横にある削除アイコンをクリックします。
5. 複数のカスタムプロジェクトメタデータエントリを編集するには、編集するメタデータエントリごとに前述の手順を繰り返します。
6. カスタムプロジェクトのメタデータエントリの編集を終了するには、[保存] をクリックします。

gcloud

project-info add-metadata コマンドを使用します。

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

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

KEY: メタデータキーの名前
VALUE: このキーに格納されている値

例

たとえば、プロジェクトに 2 つの新しいエントリ foo=bar と baz=bat を設定するには、次のコマンドを実行します。

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

--metadata-from-file フラグを使用して、メタデータの読み取り元のファイルを 1 つ以上指定することもできます。

REST

省略可。楽観的ロックを実行するには、必要に応じてフィンガープリントを指定します。

フィンガープリントとは、Compute Engine によって生成されるランダムな文字列です。フィンガープリントはリクエストのたびに変更され、一致しないフィンガープリントを指定するとリクエストが拒否されます。

フィンガープリントを指定しない場合、整合性のチェックが行われず、projects().setCommonInstanceMetadata リクエストは成功します。この動作は、フィンガープリントを常に必要とする instances().setMetadata および instanceSettings().patch メソッドとは異なります。

プロジェクトの最新のフィンガープリントを取得するには、project().get メソッドを呼び出します。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
```
出力は次のようになります。
```
{
  "name": "myproject",
  "commonInstanceMetadata": {
    "kind": "compute#metadata",
    "fingerprint": "FikclA7UBC0=",
    ...
  }
}
```

次に、projects().setCommonInstanceMetadata メソッドにリクエストを送信して、カスタムメタデータの Key-Value ペアを設定します。

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata

{
  "fingerprint": "FikclA7UBC0=",
  "items": [
    {
    "key": "foo",
    "value": "bar"
    }
  ]
}

PROJECT_ID は、実際のプロジェクト ID に置き換えます。

カスタムゾーンメタデータを設定する

カスタムゾーンメタデータを設定する場合は、プロジェクトの特定のゾーンにある VM のゾーンメタデータエントリを追加または更新します。カスタムゾーンメタデータを設定することで、次のことができます。

プロジェクト内の特定のゾーンに新しいカスタムメタデータキーを作成し、プロジェクトの対象ゾーン内のすべての VM のメタデータを設定します。
プロジェクトの特定のゾーンにあるすべての VM について、既存のカスタムゾーンメタデータエントリの値を更新します。
プロジェクトメタデータ値を持つ既存のカスタムメタデータキーの場合は、特定のゾーンでそれらのプロジェクトメタデータ値をオーバーライドし、代わりにゾーンメタデータを設定します。特定のゾーンでこれらのキーのゾーンメタデータを設定すると、プロジェクトの対象ゾーン内のすべての VM が、それらのキーのゾーンメタデータ値を使用します。

カスタムゾーンメタデータを設定する前の注意点

プロジェクトとゾーンメタデータエントリは、同じ project/ ディレクトリに保存されます。プロジェクトレベルとゾーンレベルの VM について、同じカスタムメタデータキーに異なる値を設定すると、これらのキーのゾーンメタデータ値は、それぞれのゾーンにおけるプロジェクトのメタデータよりも優先されます。

すでにプロジェクトの値が設定されているメタデータキーに、ゾーンメタデータ値を追加すると、Compute Engine によって、この指定されたゾーン内にある VM のプロジェクトメタデータ値がオーバーライドされ、/project ディレクトリがゾーン値で更新されます。
すでにゾーンメタデータ値が設定されているメタデータキーに、新しいプロジェクト全体のメタデータ値を追加しても、何も変更されません。Compute Engine では、特定のゾーンの /project ディレクトリにゾーンメタデータの値が保持されます。
特定のゾーンのカスタムメタデータキーにゾーンメタデータ値を指定しない場合は、キーにプロジェクトメタデータ値が設定されていれば、それらのゾーンの VM では引き続きプロジェクトメタデータ値が保持されます。

手順

Google Cloud CLI または REST を使用して、プロジェクトの特定のゾーンでカスタムゾーンメタデータを追加または更新できます。

gcloud

カスタムゾーンメタデータを追加または更新するには、gcloud compute project-zonal-metadata add コマンドを使用します。
```
gcloud compute project-zonal-metadata add \
  --zone=ZONE \
  --project=PROJECT_ID  \
  --metadata=KEY1=VALUE1,KEY2=VALUE2,...
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID
- ZONE: ゾーンメタデータを追加または更新するゾーン。
- KEY1、KEY2...: ゾーンメタデータ値を追加または更新するカスタムメタデータキー。
- VALUE1、VALUE2...: 既存および新規のカスタムメタデータキーに設定するゾーンメタデータ値。カスタムメタデータのキーと値に応じて、次のいずれかが発生します。
- 対応するカスタムメタデータキーが、プロジェクトメタデータを含む既存のキーである場合、Compute Engine は、指定されたゾーンで、キーのプロジェクトメタデータ値を指定されたゾーンメタデータ値でオーバーライドします。プロジェクトの指定されたゾーン内のすべての VM は、対象のキーに対して新しく指定されたゾーンメタデータを継承します。他のゾーン内の VM は、引き続き現行のプロジェクトまたはゾーンメタデータの値を保持します。このキーのプロジェクトメタデータ値を後で更新しても、プロジェクトのこのゾーン内の VM には影響せず、引き続きこのキーのゾーンメタデータ値が使用されます。
- 対応するカスタムメタデータキーが、既存のプロジェクトまたはゾーンメタデータに使用されていない新しいメタデータキーの場合、Compute Engine はカスタムメタデータキーを作成して、この値を指定されたゾーンのゾーンメタデータとして設定します。
- 対応するカスタムメタデータキーが、指定されたゾーンにゾーンメタデータ値を持つ既存のメタデータキーの場合:
  - 指定されたメタデータ値が既存の値と異なる場合、Compute Engine はゾーンメタデータエントリを新しい値で更新します。
  - 指定されたメタデータ値が既存の値と同じ場合、ゾーンメタデータエントリは変更されません。

例: 新しいカスタムゾーンメタデータエントリを追加する

たとえば、次のカスタムメタデータを持つ my-project というプロジェクトについて考えてみましょう。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"value-1" と "key-2":"value-2"

"key-4":"value-4" を新しいカスタムゾーンメタデータのペアとして us-central1-a ゾーンに追加するには、次のコマンドを実行します。

gcloud compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

例: 既存のカスタムゾーンメタデータエントリの値を更新する

同じサンプルプロジェクト my-project について考えてみましょう。このプロジェクトには、次のカスタムメタデータが含まれています。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"value-1"、"key-2":"value-2"、"key-4":"value-4"

us-cerntral1-a ゾーンの key-1 と key-4 のゾーンメタデータ値を新しい値で更新するには、次のコマンドを実行します。

gcloud compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

例: キーのプロジェクトメタデータ値をオーバーライドし、ゾーンメタデータ値を使用する

同じサンプルプロジェクト my-project について考えてみましょう。このプロジェクトには、次のカスタムメタデータが含まれています。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"new-value-1"、"key-2":"value-2"、"key-4":"new-value-4"

このサンプルプロジェクトでは、プロジェクトのメタデータ値が value-c である key-3 について考えてみましょう。us-central1-a ゾーン内のすべての VM に対して、このキーにゾーンメタデータ値 value-3 を設定するとします。このオペレーションを実行すると、Compute Engine により、us-central1-a ゾーン内のすべての VM に対してプロジェクトメタデータ値がオーバーライドされ、ゾーンメタデータ値が使用されます。プロジェクトの他のすべてのゾーンの VM では、key-3 に対して、現行のプロジェクトまたはゾーンメタデータの値が保持されます。

key-3 のプロジェクトメタデータ値をオーバーライドし、ゾーンメタデータ値を設定するには、次のコマンドを実行します。

gcloud compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

最新のフィンガープリントを取得して、そのゾーン内のプロジェクトに対する既存の Key-Value ペアを表示します。

オプティミスティックロックを実行するには、フィンガープリントを指定する必要があります。フィンガープリントとは、Compute Engine によって生成されるランダムな文字列です。フィンガープリントは、ゾーンメタデータの追加、更新、削除をリクエストするたびに変更されます。指定したフィンガープリントが一致しないと、Compute Engine によってリクエストが拒否されます。

フィンガープリントを指定しない場合は、整合性のチェックが実行され、更新リクエストは成功しません。これにより、一度に実行できるリクエストが 1 つだけになるため、競合を防ぐことができます。この動作は、フィンガープリントを常に必要とする instances().setMetadata と一致します。

ゾーンメタデータの最新のフィンガープリントを取得するには、instanceSettings().get メソッドに GET リクエストを送信します。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID
- ZONE: ゾーンメタデータを設定するゾーン。
このリクエストの出力例を次に示します。
```
    {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }
```
ゾーンメタデータを追加または更新するには、instanceSettings().patch メソッドに PATCH リクエストを送信します。リクエストには次の情報を指定する必要があります。
- 更新マスク。update_mask クエリパラメータを使用します。更新マスクには、次のメタデータのキーを含める必要があります。
  - 追加する新しいカスタムゾーンメタデータ
  - 値を更新する既存のカスタムゾーンメタデータ
  各キーの接頭辞として文字列 metadata.items. を追加する必要があります（例: metadata.items.key1,metadata.items.key3）。
  
  重要: 更新マスクは小文字にする必要があります。
- リクエスト本文で、次の内容を指定します。
  - 追加する新しいカスタムゾーンメタデータのメタデータキーと値
  - 更新する既存のカスタムゾーンメタデータのメタデータキーと値
  - 最新のフィンガープリント値
注意: 更新マスクで既存のカスタムゾーンメタデータキーを指定した場合は、指定したキーをリクエスト本文に配置しないと、Compute Engine によって、それらのゾーンメタデータエントリが削除されます。詳細については、カスタムゾーンメタデータを削除するをご覧ください。
```
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
      "KEY1": "VALUE1",
      "KEY2": "VALUE2",
      ...
    }
  }
}
```
次のように置き換えます。
- PROJECT_ID: プロジェクトの ID。
- ZONE: ゾーンメタデータを設定するゾーン。
- PREFIXED_METADATA_KEYS: 次のメタデータキーのリスト。各キーの先頭に文字列 metadata.items. が付加されています。
  - 追加する新しいカスタムゾーンメタデータ
  - 値を更新する既存のカスタムゾーンメタデータ
  たとえば、特定のゾーンの現在のゾーンメタデータキーが key-1 と key-2 であるとします。対象のゾーンでゾーンメタデータの新しいキー key-3 を追加し、さらに既存のキー key-1 のゾーンメタデータの一つを更新する場合は、更新マスクに次の文字列を指定する必要があります。
  
  metadata.items.key1,metadata.items.key3
- FINGER_PRINT: 最新のフィンガープリント値。
- KEY1、KEY2...: 値を追加または更新するカスタムゾーンメタデータキー。更新マスクで指定したすべてのカスタムゾーンメタデータキーを指定します。
  
  注意: 更新マスクで既存のカスタムゾーンメタデータキーを指定した場合は、指定したキーをリクエスト本文に配置しないと、Compute Engine によって、それらのゾーンメタデータエントリが削除されます。詳細については、カスタムゾーンメタデータを削除するをご覧ください。
- VALUE1、VALUE2...: 既存および新規のカスタムメタデータキーに設定するゾーンメタデータ値。カスタムメタデータのキーと値に応じて、次のいずれかが発生します。
  - 対応するカスタムメタデータキーが、プロジェクトメタデータを含む既存のキーである場合、Compute Engine は、指定されたゾーンで、キーのプロジェクトメタデータ値を指定されたゾーンメタデータ値でオーバーライドします。プロジェクトの指定されたゾーン内のすべての VM は、対象のキーに対して新しく指定されたゾーンメタデータを継承します。他のゾーン内の VM は、引き続き現行のプロジェクトまたはゾーンメタデータの値を保持します。このキーのプロジェクトメタデータ値を後で更新しても、プロジェクトのこのゾーン内の VM には影響せず、引き続きこのキーのゾーンメタデータ値が使用されます。
  - 対応するカスタムメタデータキーが、既存のプロジェクトまたはゾーンメタデータに使用されていない新しいメタデータキーの場合、Compute Engine はカスタムメタデータキーを作成して、この値を指定されたゾーンのゾーンメタデータとして設定します。
  - 対応するカスタムメタデータキーが、指定されたゾーンにゾーンメタデータ値を持つ既存のメタデータキーの場合:
  - 指定されたメタデータ値が既存の値と異なる場合、Compute Engine はゾーンメタデータエントリを新しい値で更新します。
  - 指定されたメタデータ値が既存の値と同じ場合、ゾーンメタデータエントリは変更されません。

例: 新しいカスタムゾーンメタデータエントリを追加する

たとえば、次のカスタムメタデータを持つ my-project というプロジェクトについて考えてみましょう。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"value-1" と "key-2":"value-2"

"key-4":"value-4" を新しいカスタムゾーンメタデータのペアとして us-central1-a ゾーンに追加するには、次の PATCH リクエストを行います。

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

例: 既存のカスタムゾーンメタデータエントリの値を更新する

同じサンプルプロジェクト my-project について考えてみましょう。このプロジェクトには、次のカスタムメタデータが含まれています。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"value-1"、"key-2":"value-2"、"key-4":"value-4"

us-cerntral1-a ゾーンの key-1 と key-4 のゾーンメタデータ値を新しい値で更新するには、次の PATCH リクエストを行います。

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

例: キーのプロジェクトメタデータ値をオーバーライドして、ゾーンメタデータ値を設定する

同じサンプルプロジェクト my-project について考えてみましょう。このプロジェクトには、次のカスタムメタデータが含まれています。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"new-value-1"、"key-2":"value-2"、"key-4":"new-value-4"

key-3 のプロジェクトメタデータ値をオーバーライドし、代わりにゾーンメタデータ値 value-3 を使用するには、次の PATCH リクエストを行います。

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

カスタムインスタンスメタデータを設定する

単一の VM インスタンスのカスタムメタデータを追加または更新するには、Google Cloud コンソール、Google Cloud CLI、または REST を使用します。

カスタムインスタンスメタデータは、次のいずれかの方法で設定できます。

新しい VM の場合は、VM の作成時にカスタムメタデータを追加できます。
既存の VM の場合は、VM の実行中にカスタムメタデータを追加または更新できます。

VM の作成時にカスタムインスタンスメタデータを追加する

次の手順に沿って、特定の VM インスタンスの作成時にメタデータを追加します。

コンソール

Google Cloud コンソールで、[インスタンスの作成] ページに移動します。

[インスタンスの作成] に移動
VM の詳細を指定します。
[詳細オプション] セクションを開き、次の操作を行います。
1. [管理] セクションを開きます。
2. カスタムメタデータに複数の Key-Value ペアを追加するには、[メタデータ] セクションで [項目を追加] をクリックします。
VM を作成するには、[作成] をクリックします。

gcloud

カスタムメタデータを設定するには、--metadata フラグを指定して gcloud compute instances create コマンドを使用します。

gcloud compute instances create VM_NAME \
--zone=ZONE \
--image-project=IMAGE_PROJECT \
IMAGE_FLAG \
--metadata=KEY=VALUE

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

VM_NAME: VM の名前
ZONE: VM を作成するゾーン
IMAGE_PROJECT: VM に使用するイメージを含むプロジェクト
IMAGE_FLAG: 次のいずれかを指定します。
- --image IMAGE_NAME フラグを使用して、公開イメージの特定のバージョンを指定します。
  
  例: --image debian-12-bookworm-v20241112
- --image-family IMAGE_FAMILY_NAME フラグを使用してイメージファミリーを指定します。
  
  これにより、イメージファミリーの最新の非推奨ではない OS イメージから VM が作成されます。たとえば、--image-family debian-12 を指定すると、Compute Engine は Debian 12 イメージファミリーの最新バージョンの OS イメージを使用します。
KEY: メタデータキーの名前
VALUE: このキーに格納されている値

例

たとえば、example-instance という名前の VM で、値が test の新しいキー env を設定するには、次のコマンドを実行します。

 gcloud compute instances create example-instance \
   --zone=us-central1-a --image-project=debian-cloud \
   --image-family=debian-12 \
   --metadata=env=test

REST

instances.insert メソッドを使用して、リクエスト内の metadata プロパティの一部としてカスタムメタデータを指定します。

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

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

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

PROJECT_ID: プロジェクト ID
ZONE: VM を作成するゾーン
MACHINE_TYPE: 新しい VM のマシンタイプ（事前定義またはカスタム）
VM_NAME: 新しい VM の名前
KEY: メタデータキーの名前
VALUE: このキーに格納されている値

既存の VM でカスタムインスタンスメタデータを追加または更新する

次の手順に沿って、既存の特定の VM インスタンスでメタデータを更新します。

コンソール

Google Cloud コンソールで [VM インスタンス] ページに移動します。
[VM インスタンス] ページに移動
メタデータを更新するインスタンスをクリックします。
ページの上部にある [編集] ボタンをクリックします。
[カスタムメタデータ] で [項目を追加] をクリックするか、既存のメタデータエントリを編集します。
変更を保存します。

gcloud

gcloud CLI では、追加アクションを使用して VM メタデータを更新します。追加または変更するメタデータキーのみを指定します。指定したキーがすでに存在する場合は、そのキーの値が新しい値で更新されます。

instances add-metadata コマンドを実行します。

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

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

VM_NAME: VM の名前
KEY: メタデータキーの名前
VALUE: このキーに格納されている値

例

foo=bar エントリを追加する場合は、次のコマンドを使用します。

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

foo=bar エントリを foo=bat に変更するには、次のコマンドを使用します。

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

最新のフィンガープリントを取得し、VM の既存の Key-Value ペアを表示します。そのためには、instances().get メソッドを呼び出します。

フィンガープリントとは、Compute Engine によって生成されるランダムな文字列で、オプティミスティックロックを実行するために使用されます。VM を更新するには、一致するフィンガープリント値を指定する必要があります。フィンガープリントはリクエストのたびに変更され、指定したフィンガープリントが一致しないとリクエストは拒否されます。これにより、一度に実行できる更新が 1 つだけになるため、競合を防ぐことができます。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID
- ZONE: VM インスタンスが配置されているゾーン
- VM_NAME: VM の名前。
出力は次のようになります。
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
    },
  ...
}
```
instances().setMetadata メソッドにリクエストを行います。新しいメタデータ値のリストと、最新の fingerprint 値を指定します。

VM の既存の Key-Value ペアを保持する場合は、新しい Key-Value ペアとともにこのリクエストに含める必要があります。

例
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "zhma6O1w2l8=",
"items": [
  {
    "key": "foo",
    "value": "bar"
  },
  {
    "key": "baz",
    "value": "bat"
  }
]
}
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID
- ZONE: VM インスタンスが配置されているゾーン
- VM_NAME: VM の名前。

VM からカスタムメタデータを削除する

このセクションでは、次のいずれかの方法で Compute Engine VM のカスタムメタデータエントリを削除する方法について説明します。

カスタムプロジェクトメタデータを削除する。プロジェクト内のすべての VM に設定されたカスタムメタデータを削除します。
カスタムゾーンメタデータを削除する。プロジェクトの特定のゾーンにあるすべての VM に設定されたカスタムメタデータを削除します。
カスタムインスタンスメタデータを削除する。特定の VM に設定された VM メタデータを削除します。

カスタムプロジェクトメタデータを削除する

プロジェクトのカスタムメタデータを削除するには、Google Cloud コンソールまたは Google Cloud CLI を使用します。

コンソール

Google Cloud コンソールで、[メタデータ] ページに移動します。

[メタデータ] ページに移動
ページ上部の [編集] をクリックします。
削除するメタデータエントリに移動し、そのエントリの横にある [] 削除ボタンをクリックします。

削除するメタデータエントリごとに、この手順を繰り返します。
カスタムプロジェクトメタデータエントリの削除を終了するには、[保存] をクリックします。

gcloud

プロジェクトのカスタムメタデータを削除するには、gcloud compute project-info remove-metadata コマンドを使用します。

特定のキーのカスタムメタデータエントリを削除するには、--keys フラグを使用してキーを指定し、そのキーの値を除外します。

gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...

VM のカスタムメタデータをすべて削除するには、--all フラグを指定します。

gcloud compute project-info remove-metadata \
    --all

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

KEY1、KEY2...: 削除するカスタムインスタンスメタデータキー。

カスタムゾーンメタデータを削除する

カスタムゾーンメタデータを削除するには、Google Cloud CLI または REST を使用します。

gcloud

カスタムゾーンメタデータを削除するには、gcloud compute project-zonal-metadata remove コマンドを使用し、--keys フラグを使用して削除するすべてのメタデータキーを指定します。

gcloud compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

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

PROJECT_ID: プロジェクト ID
ZONE: ゾーンメタデータを削除するゾーン。
KEY1、KEY2...: 削除するカスタムゾーンメタデータキー。

コマンドを実行した後、指定したキーのいずれかでプロジェクトのメタデータ値が使用できる場合、それらのプロジェクトのメタデータ値は、指定したゾーン内の VM によって継承されます。メタデータエントリがゾーンレベルでのみ設定され、対象のキーに対応するプロジェクトメタデータ値が存在しない場合、該当するゾーン内の VM はメタデータ情報を失います。

例:

次のカスタムプロジェクトメタデータを含むサンプルプロジェクト my-project について考えてみましょう。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"new-value-1"、"key-2":"value-2"、"key-3":"value-3"、"key-4":"new-value-4"

us-central1-a ゾーンのゾーンメタデータをすべて削除するには、次のコマンドを実行します。

gcloud compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

このコマンドを実行すると、us-central1-a ゾーンの VM は次のカスタムプロジェクトメタデータエントリを保有するようになります。

"key-1":"value-a"
"key-2":"value-b"
"key-3":"value-c"

REST

最新のフィンガープリントを取得して、そのゾーン内のプロジェクトに対する既存の Key-Value ペアを表示します。

オプティミスティックロックを実行するには、フィンガープリントを指定する必要があります。フィンガープリントとは、Compute Engine によって生成されるランダムな文字列です。フィンガープリントは、ゾーンメタデータの追加、更新、削除をリクエストするたびに変更されます。指定したフィンガープリントが一致しないと、Compute Engine によってリクエストが拒否されます。

フィンガープリントを指定しない場合は、整合性のチェックが実行され、削除リクエストは成功しません。これにより、一度に実行できるリクエストが 1 つだけになるため、競合を防ぐことができます。この動作は、フィンガープリントを常に必要とする instances().setMetadata と一致します。

プロジェクトの最新のフィンガープリントを取得するには、instanceSettings().get メソッドを呼び出します。
```
GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID
- ZONE: ゾーンメタデータを削除するゾーン。
このリクエストの出力例を次に示します。
```
    {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }
```
カスタムゾーンメタデータを削除するには、ゾーンメタデータを削除するメタデータキーをリクエスト本文から除外して、instanceSettings().patch メソッドに PATCH リクエストを行います。リクエストには次の情報を指定する必要があります。
- 更新マスク。update_mask クエリパラメータを使用します。更新マスクには、ゾーンメタデータを削除する既存のカスタムメタデータキーがすべて含まれている必要があります。各キーの接頭辞として文字列 metadata.items. を追加する必要があります（例: metadata.items.key1,metadata.items.key3）。
  
  重要: 更新マスクは小文字にする必要があります。
- リクエスト本文には、最新のフィンガープリント値のみを指定します。更新マスクで指定したすべてのカスタムメタデータキーを除外します。更新マスクとリクエスト本文の両方にいずれかのメタデータキーを配置すると、それらのキーのゾーンメタデータは Compute Engine によって削除されません。
```
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
    }
  }
}
```
次のように置き換えます。
- PROJECT_ID: プロジェクトの ID。
- ZONE: ゾーンメタデータを削除するゾーン。
- PREFIXED_METADATA_KEYS: ゾーンメタデータを削除する既存のカスタムメタデータキーのリスト。各キーの先頭に文字列 metadata.items. が付加されます。削除リクエストが確実に成功するように、そのメタデータキーをリクエスト本文から除外します。更新マスクとリクエスト本文の両方にいずれかのメタデータキーを配置すると、それらのキーのゾーンメタデータは Compute Engine によって削除されません。
  
  たとえば、ゾーンメタデータを含む現在のメタデータキーが key-1、key-2、key-3、key-4 の場合、key-1 と key-2 のゾーンメタデータエントリを削除するには、更新マスクに次の文字列が必要です。
  
  metadata.items.key1,metadata.items.key2
- FINGER_PRINT: 最新のフィンガープリント値。

リクエストを行った後、指定したキーのいずれかでプロジェクトのメタデータ値が使用できる場合、それらのプロジェクトのメタデータ値は、指定したゾーン内の VM によって継承されます。メタデータキーがゾーンレベルでのみ設定され、キーに対応するプロジェクトメタデータ値が存在しない場合、該当するゾーン内の VM はメタデータ情報を失います。

例:

次のカスタムプロジェクトメタデータを含むサンプルプロジェクト my-project について考えてみましょう。

プロジェクトメタデータ: "key-1":"value-a"、"key-2":"value-b"、"key-3":"value-c"
us-central1-a ゾーンのゾーンメタデータ: "key-1":"new-value-1"、"key-2":"value-2"、"key-3":"value-3"、"key-4":"new-value-4"

us-central1-a ゾーンの key-1 と key-2 のゾーンメタデータを削除するには、次の PATCH リクエストを行います。

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

このリクエストが完了すると、us-central1-a ゾーンの VM は次のカスタムプロジェクトメタデータを保有します。VM は、key-1 と key-2 のプロジェクトメタデータ値を継承しますが、key-3 と key-4 のゾーンメタデータは保持されます。

プロジェクトメタデータ: "key-1":"value-a" と "key-2":"value-b"
us-central1-a ゾーンのゾーンメタデータ: "key-3":"value-3" と "key-4":"new-value-4"

カスタムインスタンスメタデータを削除する

カスタムインスタンスメタデータを削除するには、Google Cloud コンソール、Google Cloud CLI、または REST を使用します。

コンソール

Google Cloud コンソールで [VM インスタンス] ページに移動します。
[VM インスタンス] ページに移動
[名前] 列で、メタデータを削除する VM の名前をクリックします。
ページ上部の [編集] をクリックします。
[メタデータ] セクションで、削除するメタデータエントリごとに [アイテムを削除] をクリックします。
変更を確認してカスタムインスタンスメタデータを削除するには、[保存] をクリックします。

gcloud

カスタムインスタンスメタデータを削除するには、gcloud compute instances remove-metadata コマンドを使用します。

特定のキーのカスタムメタデータエントリを削除するには、--keys フラグを使用してキーを指定し、そのキーの値を除外します。

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...

VM のカスタムメタデータをすべて削除するには、--all フラグを指定します。

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

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

PROJECT_ID: プロジェクト ID。
ZONE: VM のゾーン。
VM_NAME: VM の名前。
KEY1、KEY2...: 削除するカスタムインスタンスメタデータキー。

REST

最新のフィンガープリントを取得し、VM の既存の Key-Value ペアを表示します。そのためには、instances().get メソッドを呼び出します。

フィンガープリントとは、Compute Engine によって生成されるランダムな文字列で、オプティミスティックロックを実行するために使用されます。VM を更新するには、一致するフィンガープリント値を指定する必要があります。フィンガープリントはリクエストのたびに変更され、指定したフィンガープリントが一致しないとリクエストは拒否されます。これにより、一度に実行できる更新が 1 つだけになるため、競合を防ぐことができます。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- ZONE: VM のゾーン。
- VM_NAME: VM の名前。
出力は次のようになります。
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
    {
      "key": "key-1",
      "value": "value-1"
    }
    {
      "key": "key-2",
      "value": "value-2"
    }
    ]
  },
  ...
}
```
instances().setMetadata メソッドにリクエストを行います。リクエストを成功させるには、最新のメタデータのフィンガープリント値を含める必要があります。
- VM からすべてのカスタムメタデータの Key-Value ペアを削除するには、items プロパティで、メタデータ値を削除するメタデータキーを除外します。
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "FINGER_PRINT"
"items": [
  {
    "key": "KEY1"
    "value": "VALUE1"
  }
  {
    "key": "KEY2"
    "value": "VALUE2"
  }
  ...
]
}
```
- VM のすべてのカスタムインスタンスメタデータを削除するには、items プロパティも除外します。
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": FINGER_PRINT
}
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- ZONE: VM のゾーン。
- VM_NAME: VM の名前。
- FINGER_PRINT: 最新のフィンガープリント値。
- KEY1、KEY2...: 削除するカスタムインスタンスメタデータキー。
- VALUE1、VALUE2...: 削除するカスタムインスタンスメタデータキーの値。

次のステップ

VM メタデータの詳細を確認する。
クエリメタデータを表示してクエリを実行する方法を学習する。
メタデータサーバーで起動スクリプトまたはシャットダウンスクリプトを実行する方法を学習する。

カスタム メタデータの設定と削除 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

Console

gcloud

REST

必要なロール

必要な権限

制限事項

ブール値

VM にカスタム メタデータを設定する

カスタム プロジェクト メタデータを設定する

コンソール

gcloud

REST

カスタムゾーン メタデータを設定する

カスタムゾーン メタデータを設定する前の注意点

手順

gcloud

例: 新しいカスタムゾーン メタデータ エントリを追加する

例: 既存のカスタムゾーン メタデータ エントリの値を更新する

例: キーのプロジェクト メタデータ値をオーバーライドし、ゾーン メタデータ値を使用する

REST

例: 新しいカスタムゾーン メタデータ エントリを追加する

例: 既存のカスタムゾーン メタデータ エントリの値を更新する

例: キーのプロジェクト メタデータ値をオーバーライドして、ゾーン メタデータ値を設定する

カスタム インスタンス メタデータを設定する

VM の作成時にカスタム インスタンス メタデータを追加する

コンソール

gcloud

REST

既存の VM でカスタム インスタンス メタデータを追加または更新する

コンソール

gcloud

REST

VM からカスタム メタデータを削除する

カスタム プロジェクト メタデータを削除する

コンソール

gcloud

カスタムゾーン メタデータを削除する

gcloud

例:

REST

例:

カスタム インスタンス メタデータを削除する

コンソール

gcloud

REST

次のステップ

カスタムメタデータの設定と削除

VM にカスタムメタデータを設定する

カスタムプロジェクトメタデータを設定する

カスタムゾーンメタデータを設定する

カスタムゾーンメタデータを設定する前の注意点

例: 新しいカスタムゾーンメタデータエントリを追加する

例: 既存のカスタムゾーンメタデータエントリの値を更新する

例: キーのプロジェクトメタデータ値をオーバーライドし、ゾーンメタデータ値を使用する

例: 新しいカスタムゾーンメタデータエントリを追加する

例: 既存のカスタムゾーンメタデータエントリの値を更新する

例: キーのプロジェクトメタデータ値をオーバーライドして、ゾーンメタデータ値を設定する

カスタムインスタンスメタデータを設定する

VM の作成時にカスタムインスタンスメタデータを追加する

既存の VM でカスタムインスタンスメタデータを追加または更新する

VM からカスタムメタデータを削除する

カスタムプロジェクトメタデータを削除する

カスタムゾーンメタデータを削除する

カスタムインスタンスメタデータを削除する