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


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

カスタム メタデータを使用すると、個々の VM またはプロジェクトで、独自のメタデータの Key-Value ペアを作成して使用できます。新しいカスタム メタデータキーの追加、既存のキーの値の更新、不要なカスタム メタデータ エントリの削除を行うことができます。 カスタム メタデータの設定は、プロジェクト内の 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

    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 を使用して認証するをご覧ください。

必要なロール

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

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

これらの事前定義ロールには、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 の上限が適用されます。次のように、各 keyvalue に最大サイズの制限も適用されます。

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

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

  • 各メタデータ value の上限は 256 KB です。

  • 各メタデータ value では、ブール値を除き、大文字と小文字が区別されます。

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

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

ブール値

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

ステータス 選択できる値
TRUE YYes1
FALSE NNo0

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

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

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

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

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

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

コンソール

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

    [カスタム メタデータ] ページに移動

  2. ページ上部の [編集] をクリックします。

  3. 新しいカスタム プロジェクト メタデータ エントリを追加するには、次の操作を行います。

    1. ページの一番下まで移動し、 [項目を追加] をクリックします。
    2. [キー] フィールドに、カスタム メタデータキーの名前を入力します。
    3. [] フィールドに、カスタム プロジェクト メタデータの値を入力します。
    4. 省略可。カスタム プロジェクトのメタデータ エントリを追加するには、追加するメタデータ エントリごとに前述の手順を繰り返します。
    5. カスタム プロジェクト メタデータ エントリの追加を終了するには、[保存] をクリックします。
  4. 既存のカスタム プロジェクト メタデータ エントリを編集するには、次の手順を行います。

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

gcloud

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

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

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

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

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

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

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

REST

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

    フィンガープリントとは、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=",
        ...
      }
    }
    
  2. 次に、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: ゾーン メタデータを追加または更新するゾーン。
    • KEY1KEY2...: ゾーン メタデータ値を追加または更新するカスタム メタデータキー。
    • VALUE1VALUE2...: 既存および新規のカスタム メタデータキーに設定するゾーン メタデータ値。カスタム メタデータのキーと値に応じて、次のいずれかが発生します。

    • 対応するカスタム メタデータキーが、プロジェクト メタデータを含む既存のキーである場合、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-1key-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

  1. 最新のフィンガープリントを取得して、そのゾーン内のプロジェクトに対する既存の 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": {
            ...
          }
        }
    
  2. ゾーン メタデータを追加または更新するには、instanceSettings().patch メソッドPATCH リクエストを送信します。リクエストには次の情報を指定する必要があります。

    • 更新マスク。update_mask クエリ パラメータを使用します。更新マスクには、次のメタデータのキーを含める必要があります。

      • 追加する新しいカスタムゾーン メタデータ
      • 値を更新する既存のカスタムゾーン メタデータ

      各キーの接頭辞として文字列 metadata.items. を追加する必要があります(例: metadata.items.key1,metadata.items.key3)。

    • リクエスト本文で、次の内容を指定します。

      • 追加する新しいカスタムゾーン メタデータのメタデータキーと値
      • 更新する既存のカスタムゾーン メタデータのメタデータキーと値
      • 最新のフィンガープリント値

    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-1key-2 であるとします。対象のゾーンでゾーン メタデータの新しいキー key-3 を追加し、さらに既存のキー key-1 のゾーン メタデータの一つを更新する場合は、更新マスクに次の文字列を指定する必要があります。

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: 最新のフィンガープリント値。

    • KEY1KEY2...: 値を追加または更新するカスタムゾーン メタデータキー。更新マスクで指定したすべてのカスタムゾーン メタデータキーを指定します。

    • VALUE1VALUE2...: 既存および新規のカスタム メタデータキーに設定するゾーン メタデータ値。カスタム メタデータのキーと値に応じて、次のいずれかが発生します。

      • 対応するカスタム メタデータキーが、プロジェクト メタデータを含む既存のキーである場合、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-1key-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"

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

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 インスタンスの作成時にメタデータを追加します。

コンソール

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

    [インスタンスの作成] に移動

  2. VM の詳細を指定します。

  3. [詳細オプション] セクションを開き、次の操作を行います。

    1. [管理] セクションを開きます。
    2. カスタム メタデータに複数の Key-Value ペアを追加するには、[メタデータ] セクションで [項目を追加] をクリックします。
  4. VM を作成するには、[作成] をクリックします。

gcloud

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

gcloud compute instances create VM_NAME \
    --metadata=KEY=VALUE

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

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

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

gcloud compute instances create example-instance \
    --metadata=foo=bar

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 インスタンスでメタデータを更新します。

コンソール

  1. Google Cloud コンソールで [VM インスタンス] ページに移動します。

    [VM インスタンス] ページに移動

  2. メタデータを更新するインスタンスをクリックします。
  3. ページの上部にある [編集] ボタンをクリックします。
  4. [カスタム メタデータ] で [項目を追加] をクリックするか、既存のメタデータ エントリを編集します。
  5. 変更を保存します。

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

  1. 最新のフィンガープリントを取得し、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"
          }
        ]
        },
      ...
    }
    
  2. 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 のカスタム メタデータ エントリを削除する方法について説明します。

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

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

コンソール

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

    [メタデータ] ページに移動

  2. ページ上部の [編集] をクリックします。

  3. 削除するメタデータ エントリに移動し、そのエントリの横にある [] 削除ボタンをクリックします。

    削除するメタデータ エントリごとに、この手順を繰り返します。

  4. カスタム プロジェクト メタデータ エントリの削除を終了するには、[保存] をクリックします。

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

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

  • KEY1KEY2...: 削除するカスタム インスタンス メタデータキー。

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

カスタムゾーン メタデータを削除するには、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: ゾーン メタデータを削除するゾーン。
  • KEY1KEY2...: 削除するカスタムゾーン メタデータキー。

コマンドを実行した後、指定したキーのいずれかでプロジェクトのメタデータ値が使用できる場合、それらのプロジェクトのメタデータ値は、指定したゾーン内の 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

  1. 最新のフィンガープリントを取得して、そのゾーン内のプロジェクトに対する既存の 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": {
            ...
          }
        }
    
  2. カスタムゾーン メタデータを削除するには、ゾーン メタデータを削除するメタデータキーをリクエスト本文から除外して、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-1key-2key-3key-4 の場合、key-1key-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-1key-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-1key-2 のプロジェクト メタデータ値を継承しますが、key-3key-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 を使用します。

コンソール

  1. Google Cloud コンソールで [VM インスタンス] ページに移動します。

    [VM インスタンス] ページに移動

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

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 の名前。
  • KEY1KEY2...: 削除するカスタム インスタンス メタデータキー。

REST

  1. 最新のフィンガープリントを取得し、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"
        }
        ]
      },
      ...
    }
    
  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: 最新のフィンガープリント値。
    • KEY1KEY2...: 削除するカスタム インスタンス メタデータキー。
    • VALUE1VALUE2...: 削除するカスタム インスタンス メタデータキーの値。

次のステップ