インスタンス・メタデータの取得

インスタンス・メタデータ・サービス(IMDS)は、インスタンスに関する様々な詳細、アタッチされた仮想ネットワーク・インタフェース・カード(VNIC )、アタッチされたマルチマルチマルチテナント対応のボリューム・アタッチメント、定義したカスタム・メタデータなど、実行中のインスタンスに関する情報を提供します。また、IMDSは、様々なシステム初期化タスクに使用できる情報もcloud-initに提供します。

このような情報の一部はコンソールインスタンスの詳細ページに表示されますが、インスタンスにログインしてメタデータ・サービスを使用するとすべてを取得できます。サービスは各インスタンスで実行されます。169.254.169.254でリスニングしているHTTPエンドポイントです。インスタンスに複数のVNICがある場合は、プライマリVNICを使用してリクエストを送信する必要があります。

重要

メタデータ・リクエストのセキュリティを強化するために、イメージでサポートされている場合は、IMDSバージョン2エンドポイントを使用するようにすべてのアプリケーションを更新することを強くお薦めします。次に、IMDSバージョン1へのリクエストを無効にします。

インスタンス・メタデータ・サービスv2へのアップグレード

インスタンス・メタデータ・サービスは、バージョン1とバージョン2の2つのバージョンで使用できます。IMDSv2は、v1と比較してセキュリティが強化されています。

IMDSv1を無効にして、IMDSv2へのリクエストのみを許可すると、次の点が変わります:

  • すべてのリクエストは、v2エンドポイント(/opc/v2)に対して行う必要があります。v1エンドポイント(/opc/v1および/openstack)へのリクエストは、404 not foundエラーで拒否されます。
  • v2エンドポイントへのすべてのリクエストには、認可ヘッダーを含める必要があります。認可ヘッダーを含まないリクエストは拒否されます。
  • HTTPヘッダーForwardedX-Forwarded-ForまたはX-Forwarded-Hostを使用して転送されたリクエストは拒否されます。

コンピュート・インスタンスでインスタンス・メタデータ・サービスをアップグレードするには、次の大まかなステップを使用します:

  1. インスタンスがIMDSv2をサポートするイメージを使用していることを確認します
  2. 従来のv1エンドポイントへのリクエストを識別します
  3. v2エンドポイントをサポートするようにすべてのアプリケーションを移行します。
  4. 従来のv1エンドポイントへのすべてのリクエストを無効にします

IMDSv2でサポートされているイメージ

IMDSv2は、次のプラットフォーム・イメージでサポートされています:

  • 2020年6月以降にリリースされたOracle Autonomous Linux 7.xイメージ
  • 2020年7月以降にリリースされたOracle Linux 8.x、Oracle Linux 7.xおよびOracle Linux 6.xイメージ

その他のプラットフォーム・イメージ、ほとんどのカスタム・イメージおよびほとんどのマーケットプレイス・イメージは、IMDSv2をサポートしていません。cloud-initがバージョン20.03以降に更新され、Oracle Cloud Agentがバージョン0.0.19以降に更新されている場合、カスタムLinuxイメージはIMDSv2をサポートする可能性があります。Oracle Cloud Agentがバージョン1.0.0.0以降に更新されている場合、カスタムWindowsイメージはIMDSv2をサポートする可能性があります。cloudbase-initはIMDSv2をサポートしていません。

従来のIMDSv1エンドポイントへのリクエストの識別

リクエストが行われている特定のIMDSエンドポイントおよびリクエストを行っているエージェントを識別するには、InstanceMetadataRequestsメトリックを使用します。

インスタンスで有効になっているIMDSのバージョンを識別するには、次のいずれかを行います:

  • コンソールの使用:
    1. ナビゲーション・メニューを開き、「コンピュート」をクリックします。「コンピュート」で、「インスタンス」をクリックします。
    2. 関心のあるインスタンスをクリックします。
    3. 「インスタンスの詳細」セクションで、「インスタンス・メタデータ・サービス」の横にあるバージョン番号を書き留めます。
  • APIの使用: GetInstance操作またはListInstances操作を使用します。レスポンスでは、IMDSv1とIMDSv2の両方がインスタンスで有効になっている場合、InstanceOptionsオブジェクトのareLegacyImdsEndpointsDisabled属性はfalseを返します。IMDSv1が無効になっている場合、trueを返します。

従来のIMDSv1エンドポイントへのリクエストの無効化

IMDSv2エンドポイントに対してのみリクエストを行うようにすべてのアプリケーションを移行した後、従来のIMDSv1エンドポイントに対するすべてのリクエストを無効にする必要があります。
重要

IMDSv1へのリクエストを無効にする前に、インスタンスがIMDSv1エンドポイントを使用していないことを確認してください。リクエストを無効にしても、インスタンスがIMDSv1に引き続き依存している場合は、一部の機能が失われる可能性があります。

次のいずれかを行います:

  • コンソールの使用:
    1. ナビゲーション・メニューを開き、「コンピュート」をクリックします。「コンピュート」で、「インスタンス」をクリックします。
    2. 関心のあるインスタンスをクリックします。
    3. 「インスタンスの詳細」セクションで、「インスタンス・メタデータ・サービス」の横にある「編集」をクリックします。
    4. 「許可されるIMDSバージョン」で、「バージョン2のみ」オプションを選択します。
    5. 「変更の保存」をクリックします。
  • APIの使用: UpdateInstance操作を使用します。リクエスト本文のInstanceOptionsオブジェクトで、areLegacyImdsEndpointsDisabled属性に値trueを渡します。
ノート

IMDSv2をサポートしていないインスタンスでIMDSv1を無効にすると、起動時にインスタンスに接続できない場合があります。IMDSv1を再度有効にするには: コンソールを使用して、「インスタンスの詳細」ページの「インスタンス・メタデータ・サービス」の横にある「編集」をクリックします。「バージョン1とバージョン2」オプションを選択して変更を保存し、インスタンスを再起動します。APIを使用して、UpdateInstance操作を使用します。

必要なIAMポリシー

インスタンスにログインして、cURLを使用してメタデータを取得する場合、IAMポリシーは必要ありません。

管理者向け: ユーザーはインスタンス・メタデータをコンピュートAPI (たとえば、GetInstance)を使用して取得することもできます。ユーザーにコンピュート・インスタンスを起動させるのポリシーはこの権限に対応しています。指定されたグループがインスタンスの起動やボリュームのアタッチを必要としない場合、そのポリシーを簡素化し、manage instance-familyのみを含めて、volume-familyおよびvirtual-network-familyに関連する文を削除できます。

作成された新しいインスタンスで従来のIMDSv1エンドポイントを無効にすることを要求するには、次のポリシーを使用します:

Allow group InstanceLaunchers to manage instances in compartment ABC
 where request.instanceOptions.areLegacyEndpointsDisabled= 'true'
ポリシーを初めて使用する場合は、ポリシーの開始共通ポリシーを参照してください。インスタンス、クラウド・ネットワーク、または他のCore Services APIリソースのポリシーを作成するための参照資料については、コア・サービスの詳細を参照してください。

プラットフォーム・イメージでのインスタンス・メタデータの取得

LinuxインスタンスでcURLを使用して、プラットフォーム・イメージのインスタンス・メタデータを取得できます。Windowsインスタンスでは、cURL (Windowsバージョンでサポートされている場合)またはインターネット・ブラウザを使用できます。

インスタンス・メタデータ・サービスv2へのすべてのリクエストには、次のヘッダーを含める必要があります:

Authorization: Bearer Oracle

IMDSv2を使用してアクセスされるインスタンス・メタデータは、次のルートURLにあります:

  • すべてのインスタンス情報:

    http://169.254.169.254/opc/v2/instance/
  • インスタンスにアタッチされているVNICに関する情報:

    http://169.254.169.254/opc/v2/vnics/
  • マルチパス対応のアタッチメントを持つインスタンスにアタッチされたボリュームに関する情報:

    http://169.254.169.254/opc/v2/volumeAttachments/

IMDSv1を使用してアクセスされるインスタンス・メタデータは、次のルートURLにあります。ヘッダーは必要ありません。

  • すべてのインスタンス情報:

    http://169.254.169.254/opc/v1/instance/
  • インスタンスにアタッチされているVNICに関する情報:

    http://169.254.169.254/opc/v1/vnics/
  • マルチパス対応のアタッチメントを持つインスタンスにアタッチされたボリュームに関する情報:

    http://169.254.169.254/opc/v1/volumeAttachments/

特定のメタデータ・キーの値は、ルートURLの下のサブパスとして使用できます。

Linuxインスタンスのインスタンス・メタデータを取得するには

  1. SSHを使用してLinuxインスタンスに接続します。
  2. cURLを使用して、関心があるインスタンス・メタデータURLにGETリクエストを発行します。例:

    curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/instance/

Windowsインスタンスのインスタンス・メタデータを取得するには

Windowsインスタンスでメタデータを取得するステップは、メタデータのリクエスト元のインスタンス・メタデータ・サービスのバージョンによって異なります。

IMDSv2を使用してWindowsインスタンス・メタデータを取得するには:

  1. リモート・デスクトップ接続を使用してWindowsインスタンスに接続します。
  2. WindowsバージョンにcURLが含まれているかどうかに応じて、次のいずれかを行います:

    • WindowsバージョンにcURLが含まれている場合は、cURLを使用して、関心があるインスタンス・メタデータURLにGETリクエストを発行します。例:

      curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/instance/
    • WindowsバージョンにcURLが含まれていない場合は、インターネット・ブラウザでインスタンス・メタデータを取得できます。関心があるインスタンス・メタデータURLに移動し、認可ヘッダーを含むリクエストを渡します。リクエストにヘッダーを含める方法の詳細は、ブラウザの手順を参照してください。リクエスト・ヘッダーを含めることができるサードパーティのブラウザ拡張機能のインストールが必要になる場合があります。

IMDSv1を使用してWindowsインスタンス・メタデータを取得するには:

  1. リモート・デスクトップ接続を使用してWindowsインスタンスに接続します。
  2. インターネット・ブラウザを開き、関心のあるインスタンス・メタデータURLにアクセスします。

インスタンス・メタデータの再試行

インスタンス・メタデータ・サービスでは、メンテナンスのために短期間の停止時間が定期的に発生します。したがって、IMDSエンドポイントにアクセスしようとすると、それらが使用できなくなる可能性があります。ベスト・プラクティスとして、IMDSエンドポイントへのアクセス時に再試行ロジックを実装します。404429または5xxレスポンスを受信した場合は、30秒のタイムアウトで最大3回再試行することをお薦めします。詳細および例は、SDK for Javaのドキュメントを参照してください。

メタデータ・キー

インスタンス・メタデータには、コンピュートによって定義され、編集できないデフォルトのメタデータ・キーと、作成するカスタム・メタデータ・キーが含まれます。

一部のメタデータ・エントリは、追加のメタデータ・キーを含むディレクトリです。次の表で、末尾にスラッシュが付いているエントリはディレクトリを示しています。たとえば、regionInfo/は、他のメタデータ・キーを含むディレクトリです。

インスタンスのメタデータ・キー

インスタンスに関する次のメタデータが使用可能です。パスはhttp://169.254.169.254/opc/v2/instance/を基準とした相対パスです。

メタデータ・エントリ 説明
availabilityDomain

インスタンスが実行されている可用性ドメイン。この名前には、可用性ドメイン名のテナンシ固有の接頭辞が含まれます。

例: Uocm:PHX-AD-1

faultDomain

インスタンスが実行されているフォルト・ドメインの名前。

例: FAULT-DOMAIN-1

compartmentId

インスタンスを含むコンパートメントのOCID

displayName インスタンスのわかりやすい名前。
hostname インスタンスのホスト名。
id インスタンスのOCID 。
image インスタンスの起動に使用されるイメージのOCID。
metadata/

インスタンスに指定するカスタム・メタデータを含むディレクトリ。

特定のカスタム・メタデータ・キーのメタデータを問い合せるには、metadata/<key-name>を使用します。ここで<key-name>は、インスタンスの作成時に定義したキーの名前です。

metadata/ssh_authorized_keys Linuxインスタンスの場合、インスタンスの作成時に指定された公開SSHキー。
metadata/user_data カスタム・スクリプトを実行したり、カスタム構成を提供したりするためにcloud-initまたはcloudbase-initで使用されるユーザー・データ。
region

インスタンスが実行されている可用性ドメインを含むリージョン

us-phoenix-1およびus-ashburn-1リージョンの場合は、それぞれphxおよびiadが返されます。他のすべてのリージョンの場合は、完全なリージョン識別子が返されます。

例: phxeu-frankfurt-1

canonicalRegionName

インスタンスが実行されている可用性ドメインを含むリージョンのリージョン識別子。

例: us-phoenix-1

ociAdName

インスタンスが実行されている可用性ドメイン。この名前は内部で使用され、データ・センターのラベルに対応します。

例: phx-ad-1

regionInfo/ インスタンスが実行されている可用性ドメインを含むリージョンに関する情報を含むディレクトリ。
regionInfo/realmKey

リージョンが存在するレルムのキー。

例: oc1

regionInfo/realmDomainComponent

レルムのドメイン。

例: oraclecloud.com

regionInfo/regionKey

リージョンの3文字のキー。

例: PHX

regionInfo/regionIdentifier

リージョン識別子。

例: us-phoenix-1

shape インスタンスのシェイプ。シェイプによって、インスタンスに割り当てるCPU数とメモリー容量が決まります。ListShapes操作をコールすることで、使用可能なすべてのシェイプを列挙できます。
state

インスタンスの現在のライフサイクル状態。使用できる値のリストは、インスタンスに関する項を参照してください。

例: Running

timeCreated インスタンスが作成された日時(RFC3339で定義された形式)。
agentConfig/ インスタンスで実行されているOracle Cloud Agentソフトウェアおよびプラグインに関する情報を含むディレクトリ。
agentConfig/monitoringDisabled

Oracle Cloud Agentソフトウェアがパフォーマンス・メトリックを収集し、モニタリング・プラグインを使用してインスタンスをモニターできるかどうかを示すブール値。

モニタリング・プラグインは、このパラメータおよびpluginsConfigオブジェクトのプラグインごとの構成によって制御されます。

agentConfig/managementDisabled

Oracle Cloud Agentソフトウェアが使用可能なすべての管理プラグインを実行できるかどうかを示すブール値。

管理プラグインは、このパラメータおよびpluginsConfigオブジェクトのプラグインごとの構成によって制御されます。

agentConfig/allPluginsDisabled Oracle Cloud Agentが使用可能なすべてのプラグインを実行できるかどうかを示すブール値。これには、管理プラグインおよびモニタリング・プラグインが含まれます。
agentConfig/pluginsConfig/ インスタンスでOracle Cloud Agentが管理するプラグインに関する情報を含むディレクトリ。
agentConfig/pluginsConfig/name プラグイン名。
agentConfig/pluginsConfig/desiredState

プラグインを有効にするか無効にするか。

モニタリング・プラグインおよび管理プラグインを有効にするには、monitoringDisabledおよびmanagementDisabled属性もfalseに設定する必要があります。

freeformTags/ インスタンスに追加されるフリーフォーム・タグを含むディレクトリ。
definedTags/ インスタンスに追加される定義済タグを含むディレクトリ。

インスタンスのすべての情報が表示されるレスポンスの例を次に示します:

{
  "availabilityDomain" : "EMIr:PHX-AD-1",
  "faultDomain" : "FAULT-DOMAIN-3",
  "compartmentId" : "ocid1.tenancy.oc1..exampleuniqueID",
  "displayName" : "my-example-instance",
  "hostname" : "my-hostname",
  "id" : "ocid1.instance.oc1.phx.exampleuniqueID",
  "image" : "ocid1.image.oc1.phx.exampleuniqueID",
  "metadata" : {
    "ssh_authorized_keys" : "example-ssh-key"
  },
  "region" : "phx",
  "canonicalRegionName" : "us-phoenix-1",
  "ociAdName" : "phx-ad-1",
  "regionInfo" : {
    "realmKey" : "oc1",
    "realmDomainComponent" : "oraclecloud.com",
    "regionKey" : "PHX",
    "regionIdentifier" : "us-phoenix-1"
  },
  "shape" : "VM.Standard.E3.Flex",
  "state" : "Running",
  "timeCreated" : 1600381928581,
  "agentConfig" : {
    "monitoringDisabled" : false,
    "managementDisabled" : false,
    "allPluginsDisabled" : false,
    "pluginsConfig" : [ {
      "name" : "OS Management Service Agent",
      "desiredState" : "ENABLED"
    }, {
      "name" : "Custom Logs Monitoring",
      "desiredState" : "ENABLED"
    }, {
      "name" : "Compute Instance Run Command",
      "desiredState" : "ENABLED"
    }, {
      "name" : "Compute Instance Monitoring",
      "desiredState" : "ENABLED"
    } ]
  },
  "freeformTags": {
    "Department": "Finance"
  },
  "definedTags": {
    "Operations": {
      "CostCenter": "42"
    }
  }
}

アタッチされたVNICのメタデータ・キー

インスタンスにアタッチされているVNICに関する次のメタデータが使用可能です。パスはhttp://169.254.169.254/opc/v2/vnics/を基準とした相対パスです。

メタデータ・エントリ 説明
vnicId VNICのOCID。
privateIp VNIC上のプライマリprivateIpオブジェクトのプライベートIPアドレス。アドレスはVNICのサブネットのCIDR内にあります。
vlanTag

アタッチされたVNICのOracle割当てのVLANタグ。

VNICがOracle Cloud VMwareソリューションの一部としてVLANに属している場合、vlanTag値は、かわりにVLANのvlanTag属性の値になります。Vlanに関する項を参照してください。

macAddr

VNICのMACアドレス。

VNICがOracle Cloud VMwareソリューションの一部としてVLANに属している場合、MACアドレスが学習されます。VNICがサブネットに属している場合、MACアドレスは静的なOracle提供の値です。

virtualRouterIp 仮想ルーターのIPアドレス。
subnetCidrBlock サブネットのCIDRブロック。
nicIndex VNICが使用する物理ネットワーク・インタフェース・カード(NIC)。特定のベア・メタル・インスタンス・シェイプには、2つのアクティブな物理NIC (0および1)があります。これらのいずれかのインスタンスにセカンダリVNICを追加する場合、VNICが使用するNICを指定できます。詳細は、仮想ネットワーク・インタフェース・カード(VNIC)を参照してください。

インスタンスにアタッチされたVNICが表示されるレスポンスの例を次に示します:

[ {
  "vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
  "privateIp" : "10.0.3.6",
  "vlanTag" : 11,
  "macAddr" : "00:00:00:00:00:01",
  "virtualRouterIp" : "10.0.3.1",
  "subnetCidrBlock" : "10.0.3.0/24",
  "nicIndex" : 0
}, {
  "vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
  "privateIp" : "10.0.4.3",
  "vlanTag" : 12,
  "macAddr" : "00:00:00:00:00:02",
  "virtualRouterIp" : "10.0.4.1",
  "subnetCidrBlock" : "10.0.4.0/24",
  "nicIndex" : 0
} ]

マルチパス対応アタッチメントでアタッチされたボリュームのメタデータ・キー

次のメタデータは、インスタンスにアタッチされているマルチキャスト対応のアタッチメントについて使用できます。パスはhttp://169.254.169.254/opc/v2/volumeAttachments/を基準とした相対パスです。

メタデータ・エントリ 説明
id ボリューム・アタッチメントのOCID。
instanceId インスタンスのOCID 。
volumeId

ボリュームのOCID。

ipv4

iSCSIターゲットのIPv4アドレス。

iqn iSCSIターゲットのIQN。
port iSCSIターゲットのポート。
multipathDevices IPv4、IQNおよびポートのプロパティを持つセカンダリ・マルチパス・デバイスのリスト。

次に、インスタンスのマルチパス対応アタッチメントを示すレスポンスの例を示します。

[
{
"id": "ocid1.volumeattachment.oc1.phx.exampleuniqueID",
"instanceId": "ocid1.instance.oc1.phx.exampleuniqueID",
"volumeId": "ocid1.volume.oc1.phx.exampleuniqueID"
"ipv4": "169.254.2.2",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260,
"multipathDevices": [
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
},
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
},
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
},
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
},
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
},
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
},
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
},
{
"ipv4": "exampleIP",
"iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
"port": 3260
}
]
}
]