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.
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:
Oracle Autonomous Linux 7.x images released in June 2020 or later
Oracle Linux 8.x and Oracle Linux 7.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:
Open the navigation menu and select Compute. Under Compute, select Instances.
Click the instance that you're interested in.
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:
Open the navigation menu and select Compute. Under Compute, select Instances.
Click the instance that you're interested in.
In the Instance Details section, next to Instance metadata service, click Edit.
For Allowed IMDS version, select the Version 2 only option.
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:
Copy
Authorization: Bearer Oracle
Instance metadata accessed using IMDSv2 is available at the following root URLs:
All of the instance information:
Copy
http://169.254.169.254/opc/v2/instance/
Information about the VNICs that are attached to the instance:
Copy
http://169.254.169.254/opc/v2/vnics/
Information about a volume attached to the instance with multipath-enabled
attachment:
Copy
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:
Copy
http://169.254.169.254/opc/v1/instance/
Information about the VNICs that are attached to the instance:
Copy
http://169.254.169.254/opc/v1/vnics/
Information about a volume attached to the instance with multipath-enabled attachment:
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.
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.
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.
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.
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:
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:
This command displays the OCPUs available in each compute shape. This information is useful for flex shapes where an application needs to know more about OCPUS, VNICs, or any configurable shape details.
The following metadata is available about the see Compute Shapes that are attached to the instance. The paths are relative to http://169.254.169.254/opc/v2/instance/shapeConfig.
Metadata Entry
Description
Shape
The name of the instance.
OCPU Count
The number of OCPUs limited by the chosen VM shape and any OCPU quotas set for the tenancy.
networkingBandwidthInGbps
The amount of data that can be transferred in a network between two points.
Memory
The OCPU memory limit for the chosen VM shape. For more information, see Compute Shapes.
maxVnicAttachments
The maximum number of attachments between a VNIC and an instance.
Use the following cURL command to issue a GET request to the instance shape configuration metadata that you're interested in.