Getting Instance Metadata

The instance metadata service (IMDS) provides information about a running instance, including a variety of details about the instance, its attached virtual network interface cards (VNICs), its attached multipath-enabled volume attachments, and any custom metadata that you define. IMDS also provides information to cloud-init that you can use for various system initialization tasks.

You can find some of this information in the Console on the Instance Details page, or you can get all of it by logging in to the instance and using the metadata service. The service runs on every instance and is an HTTP endpoint listening on 169.254.169.254. If an instance has multiple VNICs, you must send the request using the primary VNIC.

Important

To increase the security of metadata requests, we strongly recommend that you update all applications to use the IMDS version 2 endpoint, if supported by the image. Then, disable requests to IMDS version 1.

For permissions, see Required IAM Policy for Working with Instances.

Upgrading to the Instance Metadata Service v2

The instance metadata service is available in two versions, version 1 and version 2. IMDSv2 offers increased security compared to v1.

When you disable IMDSv1 and allow requests only to IMDSv2, the following things change:

All requests must be made to the v2 endpoints (/opc/v2). Requests to the v1 endpoints (/opc/v1 and /openstack) are rejected with a 404 not found error.
All requests to the v2 endpoints must include an authorization header. Requests that do not include the authorization header are rejected.
Requests that are forwarded using the HTTP headers Forwarded, X-Forwarded-For, or X-Forwarded-Host are rejected.

To upgrade the instance metadata service on a compute instance, use the following high-level steps:

Verify that the instance uses an image that supports IMDSv2.
Identify requests to the legacy v1 endpoints.
Migrate all applications to support the v2 endpoints.
Disable all requests to the legacy v1 endpoints.

Supported Images for IMDSv2

IMDSv2 is supported on the following platform images:

Oracle Autonomous Linux 8.x images
Oracle Autonomous Linux 7.x images released in June 2020 or later
Oracle Linux 8.x, Oracle Linux 7.x, and Oracle Linux 6.x images released in July 2020 or later

Other platform images, most custom images, and most Marketplace images do not support IMDSv2. Custom Linux images might support IMDSv2 if cloud-init is updated to version 20.3 or later and Oracle Cloud Agent is updated to version 0.0.19 or later. Custom Windows images might support IMDSv2 if Oracle Cloud Agent is updated to version 1.0.0.0 or later; cloudbase-init does not support IMDSv2.

Identifying Requests to the Legacy IMDSv1 Endpoints

To identify the specific IMDS endpoints that requests are being made to, and the agents that are making the requests, use the InstanceMetadataRequests metric.

To identify which versions of IMDS are enabled for an instance, do either of the following things:

Using the Console:
1. Open the navigation menu and click Compute. Under Compute, click Instances.
2. Click the instance that you're interested in.
3. In the Instance Details section, next to Instance metadata service, note the version numbers.
Using the API: Use the GetInstance operation or the ListInstances operation. In the response, the areLegacyImdsEndpointsDisabled attribute in the InstanceOptions object returns false if both IMDSv1 and IMDSv2 are enabled for the instance. It returns true if IMDSv1 is disabled.

Disabling Requests to the Legacy IMDSv1 Endpoints

After you migrate all applications so that they make requests only to the IMDSv2 endpoints, you should disable all requests to the legacy IMDSv1 endpoints.

Important

Verify that the instance does not use the IMDSv1 endpoints before you disable requests to IMDSv1. If the instance still relies on IMDSv1 when you disable requests to it, you might lose some functionality.

Do either of the following things:

Using the Console:
1. Open the navigation menu and click Compute. Under Compute, click Instances.
2. Click the instance that you're interested in.
3. In the Instance Details section, next to Instance metadata service, click Edit.
4. For Allowed IMDS version, select the Version 2 only option.
5. Click Save changes.
Using the API: Use the UpdateInstance operation. In the request body, in the InstanceOptions object, pass the value true for the areLegacyImdsEndpointsDisabled attribute.

Note

If you disable IMDSv1 on an instance that does not support IMDSv2, you might not be able to connect to the instance when you launch it. To reenable IMDSv1: using the Console, on the Instance Details page, next to Instance Metadata Service, click Edit. Select the Version 1 and version 2 option, save your changes, and then restart the instance. Using the API, use the UpdateInstance operation.

Request Throttling

Oracle Cloud Infrastructure applies throttling to instance metadata service requests to prevent accidental or abusive use of resources. To avoid throttling, instead of querying security credentials for every transaction, cache the credentials until they are near expiration.

If you make too many requests too quickly, you might see some succeed and others fail. If you are experiencing throttling, Oracle recommends that you retry using an exponential back-off.

Getting Instance Metadata on Platform Images

You can get instance metadata for platform images by using cURL on Linux instances. On Windows instances, you can use cURL (if supported by the Windows version) or an internet browser.

All requests to the instance metadata service v2 must include the following header:

Authorization: Bearer Oracle

Instance metadata accessed using IMDSv2 is available at the following root URLs:

All of the instance information:
```
http://169.254.169.254/opc/v2/instance/
```
Information about the VNICs that are attached to the instance:
```
http://169.254.169.254/opc/v2/vnics/
```
Information about a volume attached to the instance with multipath-enabled attachment:
```
http://169.254.169.254/opc/v2/volumeAttachments/
```

Instance metadata accessed using IMDSv1 is available at the following root URLs. No header is necessary.

All of the instance information:
```
http://169.254.169.254/opc/v1/instance/
```
Information about the VNICs that are attached to the instance:
```
http://169.254.169.254/opc/v1/vnics/
```
Information about a volume attached to the instance with multipath-enabled attachment:
```
http://169.254.169.254/opc/v1/volumeAttachments/
```

The values for specific metadata keys are available as subpaths below the root URL.

To get instance metadata for Linux instances

Connect to a Linux instance using SSH.
Use cURL to issue a GET request to the instance metadata URL that you're interested in. For example:
```
curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/instance/
```

To get instance metadata for Windows instances

The steps to get metadata on a Windows instance depend on which version of the instance metadata service you're requesting metadata from.

To get Windows instance metadata using IMDSv2:

Connect to a Windows instance by using a Remote Desktop connection.
Depending on whether your Windows version includes cURL, do either of the following:
- If your Windows version includes cURL, use cURL to issue a GET request to the instance metadata URL that you're interested in. For example:
```
curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/instance/
```
- If your Windows version does not include cURL, you can get instance metadata in your internet browser. Navigate to the instance metadata URL that you're interested in, and pass a request that includes the authorization header. See the instructions for your browser for more information about including headers in a request. You might need to install a third-party browser extension that lets you include request headers.

To get Windows instance metadata using IMDSv1:

Connect to a Windows instance by using a Remote Desktop connection.
Open an internet browser and then navigate to the instance metadata URL that you're interested in.

Retries for Instance Metadata

The instance metadata service periodically experiences short periods of downtime for maintenance. Therefore, when you try to access IMDS endpoints, they might be unavailable. As a best practice, implement retry logic when accessing IMDS endpoints. The following strategy is recommended: retry up to three times with a 30 second timeout if you receive a 404, 429, or 5xx response. For more information and examples, see the SDK for Java documentation.

Metadata Keys

The instance metadata includes default metadata keys that are defined by Compute and cannot be edited, as well as custom metadata keys that you create.

Some metadata entries are directories that contain additional metadata keys. In the following tables, entries with a trailing slash indicate a directory. For example, regionInfo/ is a directory that contains other metadata keys.

Metadata Keys for an Instance

The following metadata is available about an instance. The paths are relative to http://169.254.169.254/opc/v2/instance/.


Metadata Entry	Description
`availabilityDomain`	The availability domain the instance is running in. This name includes the tenancy-specific prefix for the availability domain name. Example: `Uocm:PHX-AD-1`
`faultDomain`	The name of the fault domain the instance is running in. Example: `FAULT-DOMAIN-1`
`compartmentId`	The OCID of the compartment that contains the instance.
`displayName`	The user-friendly name of the instance.
`hostname`	The host name of the instance.
`id`	The OCID of the instance.
`image`	The OCID of the image used to boot the instance.
`metadata/`	A directory containing any custom metadata that you provide for the instance. To query the metadata for a specific custom metadata key, use `metadata/<key-name>`, where `<key-name>` is the name of the key that you defined when creating the instance.
`metadata/ssh_authorized_keys`	For Linux instances, the public SSH key that was provided when creating the instance.
`metadata/user_data`	User data to be used by cloud-init or cloudbase-init to run custom scripts or provide custom configuration.
`region`	The region that contains the availability domain the instance is running in. For the us-phoenix-1 and us-ashburn-1 regions, `phx` and `iad` are returned, respectively. For all other regions, the full region identifier is returned. Examples: `phx`, `eu-frankfurt-1`
`canonicalRegionName`	The region identifier for the region that contains the availability domain the instance is running in. Example: `us-phoenix-1`
`ociAdName`	The availability domain the instance is running in. This name is used internally and corresponds to the data center label. Example: `phx-ad-1`
`regionInfo/`	A directory containing information about the region that contains the availability domain the instance is running in.
`regionInfo/realmKey`	The key for the realm that the region is in. Example: `oc1`
`regionInfo/realmDomainComponent`	The domain for the realm. Example: `oraclecloud.com`
`regionInfo/regionKey`	The 3-letter key for the region. Example: `PHX`
`regionInfo/regionIdentifier`	The region identifier. Example: `us-phoenix-1`
`shape`	The shape of the instance. The shape determines the number of CPUs and the amount of memory allocated to the instance. You can enumerate all available shapes by calling the ListShapes operation.
`state`	The current lifecycle state of the instance. For a list of allowed values, see Instance. Example: `Running`
`timeCreated`	The date and time the instance was created, in the UNIX timestamp format in milliseconds since Epoch.
`agentConfig/`	A directory containing information about the Oracle Cloud Agent software and plugins running on the instance.
`agentConfig/monitoringDisabled`	A Boolean value indicating whether the Oracle Cloud Agent software can gather performance metrics and monitor the instance using the monitoring plugins. The monitoring plugins are controlled by this parameter and by the per-plugin configuration in the `pluginsConfig` object.
`agentConfig/managementDisabled`	A Boolean value indicating whether the Oracle Cloud Agent software can run all the available management plugins. The management plugins are controlled by this parameter and by the per-plugin configuration in the `pluginsConfig` object.
`agentConfig/allPluginsDisabled`	A Boolean value indicating whether Oracle Cloud Agent can run all of the available plugins. This includes the management and monitoring plugins.
`agentConfig/pluginsConfig/`	A directory containing information about the plugins that Oracle Cloud Agent manages on the instance.
`agentConfig/pluginsConfig/name`	The plugin name.
`agentConfig/pluginsConfig/desiredState`	Whether the plugin should be enabled or disabled. To enable the monitoring and management plugins, the `monitoringDisabled` and `managementDisabled` attributes must also be set to false.
`freeformTags/`	A directory containing any free-form tags that are added to the instance.
`definedTags/`	A directory containing any defined tags that are added to the instance.

Here's an example response that shows of all of the information for an instance:

{
  "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"
    }
  }
}

Metadata Keys for Attached VNICs

The following metadata is available about the VNICs that are attached to the instance. The paths are relative to http://169.254.169.254/opc/v2/vnics/.


Metadata Entry	Description
`vnicId`	The OCID of the VNIC.
`privateIp`	The private IP address of the primary `privateIp` object on the VNIC. The address is within the CIDR of the VNIC's subnet.
`vlanTag`	The Oracle-assigned VLAN tag of the attached VNIC. If the VNIC belongs to a VLAN as part of the Oracle Cloud VMware Solution, the `vlanTag` value is instead the value of the `vlanTag` attribute for the VLAN. See Vlan.
`macAddr`	The MAC address of the VNIC. If the VNIC belongs to a VLAN as part of the Oracle Cloud VMware Solution, the MAC address is learned. If the VNIC belongs to a subnet, the MAC address is a static, Oracle-provided value.
`virtualRouterIp`	The IP address of the virtual router.
`subnetCidrBlock`	The subnet's CIDR block.
`nicIndex`	Which physical network interface card (NIC) the VNIC uses. Certain bare metal instance shapes have two active physical NICs (0 and 1). If you add a secondary VNIC to one of these instances, you can specify which NIC the VNIC will use. For more information, see Virtual Network Interface Cards (VNICs).

Here's an example response that shows the VNICs that are attached to an instance:

[ {
    "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
} ]

Metadata Keys for Volumes Attached with Multipath-Enabled Attachments

The following metadata is available about the multipath-enabled volume attachments that are attached to the instance. The paths are relative to http://169.254.169.254/opc/v2/volumeAttachments/.


Metadata Entry	Description
`id`	The OCID of the volume attachment.
`instanceId`	The OCID of the instance.
`volumeId`	The OCID of the volume.
`ipv4`	The IPv4 address of the iSCSI target.
`iqn`	The IQN of the iSCSI target.
`port`	The port of the iSCSI target.
`multipathDevices`	A list of secondary multipath devices with the properties `ipv4`, `iqn`, and `port`.

Here's an example response that shows the multipath-enabled volume attachments for an instance:

[
  {
    "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
      }
    ]
  }
]

Oracle Cloud Infrastructure Documentation