IMDS credentials - AWS SDKs and Tools

IMDS credentials

Instance metadata is data about your instance that you can use to configure or manage the running instance. For more information about the data available, see Instance metadata and user data in the Amazon EC2 User Guide for Linux Instances or Instance metadata and user data in the Amazon EC2 User Guide for Windows Instances. Amazon EC2 provides a local endpoint available to instances that can provide various bits of information to the instance. If the instance has a role attached, it can provide a set of credentials that are valid for that role. The SDKs can use that endpoint to resolve credentials as part of their default credential provider chain.

Configure this functionality by using the following:

AWS_EC2_METADATA_DISABLED - environment variable

Whether or not to attempt to use Amazon EC2 Instance Metadata Service (IMDS) to obtain credentials.

Default value: false.

Valid values: true, false.

ec2_metadata_service_endpoint - shared AWS config file setting
AWS_EC2_METADATA_SERVICE_ENDPOINT - environment variable

The endpoint of IMDS.

Default value: If ec2_metadata_service_endpoint_mode equals IPv4, then default endpoint is http://169.254.169.254. If ec2_metadata_service_endpoint_mode equals IPv6, then default endpoint is http://[fd00:ec2::254].

Valid values: Valid URI.

ec2_metadata_service_endpoint_mode - shared AWS config file setting
AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE - environment variable

The endpoint mode of IMDS.

Default value:IPv4.

Valid values: IPv4, IPv6.

Security for IMDS credentials

By default, when the AWS SDK is not configured with valid credentials the SDK will attempt to use the Amazon EC2 Instance Metadata Service (IMDS) to retrieve credentials for an AWS role. This behavior can be disabled by setting the AWS_EC2_METADATA_DISABLED environment variable to true. This prevents unnecessary network activity and enhances security on untrusted networks where the Amazon EC2 Instance Metadata Service may be impersonated.

Note

AWS SDK clients configured with valid credentials will never use IMDS to retrieve credentials, regardless of any of these settings.

Disabling use of Amazon EC2 IMDS credentials

How you set this environment variable depends on what operating system is in use as well as whether or not you want the change to be persistent.

Linux and macOS

Customers using Linux or macOS can set this environment variable with the following command:

$ export AWS_EC2_METADATA_DISABLED=true

If you want this setting to be persistent across multiple shell sessions and system restarts, you can add the above command to your shell profile file, such as .bash_profile, .zsh_profile, or .profile.

Windows

Customers using Windows can set this environment variable with the following command:

$ set AWS_EC2_METADATA_DISABLED=true

If you want this setting to be persistent across multiple shell sessions and system restarts can use the following command instead:

$ setx AWS_EC2_METADATA_DISABLED=true
Note

The setx command does not apply the value to the current shell session, so you will need to reload or reopen the shell for the change to take effect.

Compatibility with AWS SDKS

The following SDKs support the features and settings described on this page, any partial exceptions are noted: