Configure the Instance Metadata Service options (original) (raw)

The Instance Metadata Service (IMDS) runs locally on every EC2 instance. The instance metadata options refer to a set of configurations that control the accessibility and behavior of the IMDS on an EC2 instance.

You can configure the following instance metadata options on each instance:

Instance metadata service (IMDS):enabled | disabled

You can enable or disable the IMDS on an instance. When disabled, you or any code won't be able to access the instance metadata on the instance.

The IMDS has two endpoints on an instance: IPv4 (169.254.169.254) and IPv6 ([fd00:ec2::254]). When you enable the IMDS, the IPv4 endpoint is automatically enabled. If you want to enable the IPv6 endpoint, you need to do so explicitly.

IMDS IPv6 endpoint: enabled |disabled

You can explicitly enable the IPv6 IMDS endpoint on an instance. When the IPv6 endpoint is enabled, the IPv4 endpoint remains enabled. The IPv6 endpoint is only supported on Nitro-based instances in IPv6-supported subnets (dual stack or IPv6 only).

Metadata version: IMDSv1 or IMDSv2 (token optional) | IMDSv2 only (token required)

When requesting instance metadata, IMDSv2 calls require a token. IMDSv1 calls do not require a token. You can configure an instance to allow either IMDSv1 or IMDSv2 calls (where a token is optional), or to only allow IMDSv2 calls (where a token is required).

Metadata response hop limit:1–64

The hop limit is the number of network hops that the PUT response is allowed to make. You can set the hop limit to a minimum of 1 and a maximum of64. In a container environment, a hop limit of1 can cause issues. For information about how to mitigate these issues, see the information about container environments under Instance metadata access considerations.

Access to tags in instance metadata:enabled | disabled

You can enable or disable access to the instance's tags from an instance's metadata. For more information, see View tags for your EC2 instances using instance metadata.

To view an instance's current configuration, see Query instance metadata options for existing instances.

Instance metadata options can be configured at different levels, as follows:

For more information, see Configure instance metadata options for new instances and Modify instance metadata options for existing instances.

The value for each instance metadata option is determined at instance launch, following a hierarchical order of precedence. The hierarchy, with the highest precedence at the top, is as follows:

Each metadata option is evaluated separately. The instance can be configured with a mix of direct instance configuration, account-level defaults, and the configuration from the AMI.

You can change the value of any metadata option after launch on a running or stopped instance, unless changes are restricted by an IAM or SCP policy.

Determine values for metadata options – Example 1

In this example, an EC2 instance is launched into a Region where theHttpPutResponseHopLimit is set to 1 at the account level. The specified AMI has ImdsSupport set to v2.0. No metadata options are specified directly on the instance at launch. The instance is launched with the following metadata options:

"MetadataOptions": {
    ...
    "HttpTokens": "required",
    "HttpPutResponseHopLimit": 1,
    ...

These values were determined as follows:

Determine values for metadata options – Example 2

In this example, the EC2 instance is launched with the same settings as in the previous Example 1, but with HttpTokens set to optional directly on the instance at launch. The instance is launched with the following metadata options:

"MetadataOptions": {
    ...
    "HttpTokens": "optional",
    "HttpPutResponseHopLimit": 1,
    ...

The value for HttpPutResponseHopLimit is determined in the same way as in Example 1. However, the value for HttpTokens is determined as follows: Metadata options configured on the instance at launch take first precedence. Even though the AMI was configured with ImdsSupport: v2.0 (in other words, HttpTokens is set to required), the value specified on the instance at launch (HttpTokens set tooptional) took precedence.

Set the instance metadata version

When an instance is launched, the value for the instance metadata version is either IMDSv1 or IMDSv2 (token optional) or IMDSv2 only (token required).

At instance launch, you can either manually specify the value for the metadata version, or use the default value. If you manually specify the value, it overrides any defaults. If you opt not to manually specify the value, it will be determined by a combination of default settings, as outlined in the following table.

The table shows how the metadata version for an instance at launch (indicated by Resulting instance configuration in column 4) is determined by the settings at the different levels of configuration. The order of precedence is from left to right, where the first column takes the highest precedence, as follows:

Launch parameter Account level default AMI default Resulting instance configuration
V2 only (token required) No preference V2 only V2 only
V2 only (token required) V2 only V2 only V2 only
V2 only (token required) V1 or V2 V2 only V2 only
V1 or V2 (token optional) No preference V2 only V1 or V2
V1 or V2 (token optional) V2 only V2 only V1 or V2
V1 or V2 (token optional) V1 or V2 V2 only V1 or V2
Not set No preference V2 only V2 only
Not set V2 only V2 only V2 only
Not set V1 or V2 V2 only V1 or V2
V2 only (token required) No preference null V2 only
V2 only (token required) V2 only null V2 only
V2 only (token required) V1 or V2 null V2 only
V1 or V2 (token optional) No preference null V1 or V2
V1 or V2 (token optional) V2 only null V1 or V2
V1 or V2 (token optional) V1 or V2 null V1 or V2
Not set No preference null V1 or V2
Not set V2 only null V2 only
Not set V1 or V2 null V1 or V2

Use IAM condition keys to restrict instance metadata options

You can use IAM condition keys in an IAM policy or SCP as follows:

Tasks
Note

You should proceed cautiously and conduct careful testing before making any changes. Take note of the following: