ゲスト属性の設定とクエリ

ゲスト属性は、仮想マシン（VM）インスタンスでの実行中にアプリケーションから書き込み可能な特定の型のカスタム メタデータです。VM インスタンスのアプリケーションまたはユーザーは、このようなゲスト属性のメタデータ値を読み取ることも、データを書き込むこともできます。

準備

  • Windows Server VM の場合は、PowerShell 3.0 以降を使用します。コピーしたコードブロックを貼り付ける場合は ctrl+v の使用をおすすめします。
  • まだ設定していない場合は、認証を設定します。認証とは、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 の内部と外部のどちらからタスクを実行するのかよって異なります。

VM の内部

VM 内からゲスト属性を設定、クエリ、削除する場合に必要なのは、VM に接続するためのロールと権限のみです。VM インスタンスで実行中のプロセスはゲスト属性に値を書き込むことができます。sudo や管理者レベルの権限がないスクリプトやアプリケーションも書き込むことができます。

VM 内で読み取りと書き込みを行うため、メタデータ サーバーはインスタンス レベルで認証と認可を自動的に行います。各 VM は、自身のメタデータ サーバーに対してのみ読み書きが許可されます。他の VM は別の VM のメタデータ サーバーにアクセスできません。

VM の外部

ゲスト属性を有効にする場合や、VM の外部から Google Cloud CLI または REST を使用してゲスト属性を表示する場合は、次のロールと権限が必要です。VM の外部からゲスト属性を設定または削除することはできません。

ゲスト属性の有効化または表示に必要な権限がユーザーまたはサービス アカウントに付与されるようにするには、VM またはプロジェクトに対する Compute インスタンス管理者（v1）（roles/compute.instanceAdmin.v1）IAM ロールをユーザーまたはサービス アカウントに付与するよう管理者に依頼してくださいロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

この事前定義ロールには、ゲスト属性の有効化または表示に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

ゲスト属性を有効にするか、表示するには、次の権限が必要です。

  • ゲスト属性を有効にする: VM またはプロジェクトに対する compute.instances.setMetadata
  • ゲスト属性を表示する: VM またはプロジェクトに対する compute.instances.getGuestAttributes

管理者は、カスタムロールや他の事前定義ロールを使用して、これらの権限をユーザーまたはサービス アカウントに付与することもできます。

ゲスト属性を使用するタイミング

ゲスト属性は、頻繁に変更されない少量のデータが必要なユースケースにのみ使用します。ゲスト属性は次のようなユースケースに使用します。

  • 1 つの VM インスタンスで 1 分間に実行できるクエリの数が最大 10 件に制限されている。
  • 1 秒間に増加できるクエリ数が 3 件までに制限されている。この制限を超えると、Compute Engine が書き込み中のゲスト属性を削除することがあります。他の重要なシステムデータがサーバーに確実に書き込まれるようにするため、このようなデータの削除が必要になります。

ゲスト属性は、使用頻度の低い少量のデータを公開する場合にも使用できます。たとえば、ゲスト属性は次のようなユースケースに使用されます。

  • ゲスト属性にカスタム ステータス値を設定し、起動スクリプトで、初期化の成功を通知できるようにする。
  • 構成管理エージェントで、ゲスト OS の名前とバージョンをゲスト属性に公開できるようにする。
  • インベントリ管理エージェントで、VM インスタンスにインストールされているパッケージのリストをゲスト属性に公開できるようにする。
  • ゲスト属性にカスタム ステータス値を設定し、ワークロード オーケストレーション ソフトウェアで、ゲスト内のオペレーションの完了をソフトウェア コントロール プレーンに通知できるようにする。

ゲスト属性は、イベント ストリーミング、Pub/Sub、または他の形式のデータ ストレージや構成リポジトリに代わるものではありません。

ゲスト属性とその他の Google Cloud サービス

ゲスト属性は、他の Google Cloud サービスで次のように使用されます。

  • SSH セキュリティ: ゲスト属性が有効で、OS Login が無効になっている場合、ゲスト環境と gcloud CLI はゲスト属性を使用して、SSH で VM に接続する前に Google API を使用してホストキーを取得することで、SSH のセキュリティを向上させます。
  • VM Manager: OS Config エージェントは、オペレーティング システムのデータをゲスト属性にパブリッシュします。

これらのサービスによって保存されるメタデータ エントリを確認するには、事前定義されたゲスト属性のメタデータキーをご覧ください。

VM でゲスト属性を有効にする

ゲスト属性はデフォルトで無効になっています。ゲスト属性を有効にするには、個々の VM またはプロジェクト全体のメタデータに必要なメタデータ値を設定します。

Console

VM の作成時にインスタンス メタデータで enable-guest-attributes を設定するには:

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

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

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

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

    1. [管理] セクションを開きます。

    2. [メタデータ] セクションで [項目を追加] をクリックし、次のメタデータ エントリを追加します。

      • キー: enable-guest-attributes
      • 値: TRUE

  4. VM を作成するには、[作成] をクリックします。

プロジェクト全体のメタデータで enable-guest-attributes を設定し、プロジェクト内のすべての VM に適用するには:

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

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

  2. [編集] をクリックします。

  3. キーが enable-guest-attributes で値が TRUE のメタデータ エントリを追加します。この機能を無効にする場合は値を FALSE に設定します。

  4. [保存] をクリックして変更を適用します。

既存の VM のメタデータで enable-guest-attributes を設定するには:

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

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

  2. メタデータ値を設定する VM の名前をクリックします。
  3. インスタンスの詳細ページの上部にある [編集] をクリックしてインスタンス設定の編集画面を開きます。
  4. カスタム メタデータで、キーが enable-guest-attributes で値が TRUE のメタデータ エントリを追加します。VM でこの機能を無効にする場合は、値を FALSE に設定します。
  5. インスタンスの詳細ページの一番下にある [保存] をクリックして変更内容を VM に適用します。

gcloud

VM の作成時にインスタンス メタデータで enable-guest-attributes を設定するには:

Google Cloud CLI で gcloud compute instances create コマンドを使用し、enable-guest-attributes=TRUE を設定してゲスト属性を有効にします。VM_NAME は実際の VM 名に置き換えます。

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

プロジェクト全体のメタデータで enable-guest-attributes を設定し、プロジェクト内のすべての VM に適用するには:

Google Cloud CLI で project-info add-metadata コマンドを使用し、enable-guest-attributes=TRUE を設定してゲスト属性を有効にします。

gcloud compute project-info add-metadata \
    --metadata=enable-guest-attributes=TRUE

また、enable-guest-attributes を FALSE に設定して、ゲスト属性を無効にすることもできます。

既存の VM のメタデータで enable-guest-attributes を設定するには:

Google Cloud CLI で instances add-metadata コマンドを使用し、enable-guest-attributes=TRUE を設定してゲスト属性を有効にします。VM_NAME は実際の VM 名に置き換えます。

gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE

また、enable-guest-attributes を FALSE に設定して、VM でゲスト属性の使用を無効にすることもできます。

ゲスト属性を設定する

VM インスタンスで実行中のプロセスはゲスト属性に値を書き込むことができます。sudo や管理者レベルの権限がないスクリプトやアプリケーションも書き込むことができます。VM 外のユーザーまたはサービス アカウントは、ゲスト属性にメタデータ値を書き込むことができません。

Linux VM

たとえば、VM 内から curl リクエストを使用して、guest-attributes メタデータパスに値を書き込むことができます。

curl -X PUT --data "VALUE" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

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

  • NAMESPACE: 実際の KEY の論理グループ。ゲスト属性には名前空間が必要です。
  • VALUE: 書き込む値。
  • KEY: 値を保存する guest-attributes 内のメタデータパス。

文字、数字、アンダースコア（_）、NAMESPACE と KEY フィールドのハイフン（-）のみを使用できます。

Windows VM

たとえば、VM 内から Invoke-RestMethod リクエストを使用して、guest-attributes メタデータパスに値を書き込むことができます。

PS C:\> 
$value = (Invoke-RestMethod `
         -Method PUT -Body "VALUE" `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

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

  • NAMESPACE: 実際の KEY の論理グループ。ゲスト属性には名前空間が必要です。
  • VALUE: 書き込む値。
  • KEY: 値を保存する guest-attributes 内のメタデータパス。

文字、数字、アンダースコア（_）、NAMESPACE と KEY フィールドのハイフン（-）のみを使用できます。

ゲスト属性を取得する

必要なロールを持つユーザーまたはサービス アカウントは、VM の外部からゲスト属性を読み取ることができます。VM 内のユーザーやアプリケーションは、その VM のメタデータ値を読み取ることができます。

仮想マシンで実行中のプロセスはゲスト属性に値を書き込むことができます。sudo や管理者レベルの権限がないスクリプトやアプリケーションも書き込むことができます。

メタデータ サーバーにクエリする

VM 内からゲスト属性をクエリするには、次の操作を行います。

  1. VM に接続します。

  2. ゲスト属性をクエリします。

    Linux VM

    たとえば、VM 内から curl リクエストを使用して、guest-attributes メタデータパスから値を読み取ることができます。

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

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

    • NAMESPACE: クエリを実行する guest-attributes キーの名前空間。
    • KEY: メタデータ値を読み取る guest-attributes 内のパス。

    1 つのリクエストですべてのゲスト属性値を取得することもできます。NAMESPACE はクエリを実行する guest-attributes キーの名前空間に置き換えます。

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/ -H "Metadata-Flavor: Google"

    Windows VM

    たとえば、VM 内から Invoke-RestMethod リクエストを使用して、guest-attributes メタデータパスから値を読み取ることができます。

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

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

    • NAMESPACE: クエリを実行する guest-attributes キーの名前空間。
    • KEY: メタデータ値を読み取る guest-attributes 内のパス。

    1 つのリクエストですべてのゲスト属性値を取得することもできます。NAMESPACE はクエリを実行する guest-attributes キーの名前空間に置き換えます。

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/")
$value

Google Cloud CLI または REST を使用する

VM の外部からゲスト属性を表示するには、次の操作を行います。

gcloud

Google Cloud CLI を使用して、VM のゲスト属性のメタデータ値を読み取ります。たとえば、次のように VM のすべての値を取得できます。

gcloud compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

特定の名前空間のすべての値を取得するには、--query-path フラグと定義済みの名前空間を使用します。

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE \
    --zone=ZONE

特定の名前空間にあるすべての値を取得するには、--query-path フラグ、名前空間、定義済みの値のキーを使用します。

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

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

  • VM_NAME: ゲスト属性のメタデータ値を読み取る VM の名前
  • NAMESPACE: クエリを実行する guest-attributes キーの名前空間
  • KEY: 値が格納される guest-attributes メタデータ内部のパス
  • ZONE: VM が配置されているゾーン

REST

compute.instances.getguestattributes メソッドを使用します。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

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

  • PROJECT_ID: プロジェクト ID
  • ZONE: VM インスタンスが配置されているゾーン
  • VM_NAME: ゲスト属性のメタデータ値を読み取る VM の名前
  • NAMESPACE: クエリを実行する guest-attributes キーの名前空間
  • KEY: 値が格納される guest-attributes メタデータ内部のパス

NAMESPACE のすべてのキーを取得するには、KEY を省略します。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

VM の各名前空間のすべてのキーを取得するには、NAMESPACE と queryPath を完全に省略します。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes

また、OAuth トークンがある場合は、curl を使用できます。

curl -H "Authorization: Bearer OAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

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

  • OAUTH_TOKEN: 実際の OAuth トークン
  • PROJECT_ID: プロジェクト ID
  • ZONE: VM インスタンスが配置されているゾーン
  • VM_NAME: ゲスト属性のメタデータ値を読み取る VM の名前
  • NAMESPACE: クエリを実行する guest-attributes キーの名前空間
  • KEY: 値が格納される guest-attributes メタデータ内部のパス

ゲスト属性を削除する

VM 内からゲスト属性を削除するには、次の操作を行います。

  1. VM に接続します。

  2. ゲスト属性を削除します。

    Linux VM

    ゲスト属性は削除することもできます。たとえば、curl を使用して特定のキーを削除します。

    curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

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

    • NAMESPACE: 削除する guest-attributes キーの名前空間
    • KEY: 値が格納される guest-attributes 内のパス

    Windows VM

    ゲスト属性は削除することもできます。たとえば、Invoke-RestMethod を使用して特定のキーを削除します。

    PS C:\> 
$value = (Invoke-RestMethod `
          -Method DELETE `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

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

    • NAMESPACE: 削除する guest-attributes キーの名前空間
    • KEY: 値が格納される guest-attributes 内のパス

組織またはフォルダでゲスト属性を無効にする

組織またはフォルダ内のすべての VM でゲスト属性を無効にする場合は、ゲスト属性の機能を完全に無効にします。

組織またはフォルダに constraints/compute.disableGuestAttributesAccess 制約を設定し、PROJECT_ID を実際のプロジェクトの名前に置き換えます。

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess \
    --project=PROJECT_ID

組織に制約を設定して管理する方法については、制約の使用をご覧ください。

次のステップ