Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
Configure instance metadata options
for new instances
You can configure the following instance metadata options.
You can use the following methods to require the use of IMDSv2 on your
instances.
Set IMDSv2 as the
default for the account
You can set the default instance metadata version at the account level for each
Amazon Web Services Region. When an instance is launched, the instance metadata version is
automatically set to the account level value.
If you've never changed the account-level default, it indicates no
preference.
You can set the account default for the instance metadata version to IMDSv2 so
that all new instances in the account launch with IMDSv2 required
(in other words, IMDSv1 is disabled). With this account default,
when you launch an instance, the following are the default values for the
instance:
Before setting the account default for Metadata
version to V2 only (token
required), ensure that none of your instances are making
IMDSv1 calls. The MetadataNoToken
CloudWatch metric
tracks IMDSv1 calls. When MetadataNoToken
records
zero IMDSv1 usage, your instances are ready to be fully
transitioned to using IMDSv2.
At launch, you can change the values in the instance configuration. For more information,
see Set the instance metadata
version.
- Console
-
To set IMDSv2 as the default for the account for the specified
Region
Open the Amazon EC2 console at
https://console.amazonaws.cn/ec2/.
-
To change the Amazon Web Services Region, use the Region selector in
the upper-right corner of the page.
-
In the navigation pane, choose EC2 Dashboard.
-
Under Account attributes, choose
Data protection and
security.
-
Next to IMDS defaults, choose
Manage.
-
On the Manage IMDS defaults page,
do the following:
-
For Instance metadata
service, choose
Enabled.
-
For Metadata version,
choose V2 only (token
required).
-
For Metadata response hop limit, specify
2 if your instances will host
containers. Otherwise, select No
preference. When no preference is
specified, at launch, the value defaults to
2 if the AMI requires
IMDSv2; otherwise it defaults to
1.
-
Choose Update.
- Amazon CLI
-
To set IMDSv2 as the default for the account for the specified
Region
Use the modify-instance-metadata-defaults command and
specify the Region in which to modify the IMDS account level
settings. Include --http-tokens
set to
required
and
--http-put-response-hop-limit
set to
2
if your instances will host containers.
Otherwise, specify -1
to indicate no
preference. When -1
(no preference) is
specified, at launch, the value defaults to 2
if the AMI requires IMDSv2; otherwise it defaults to
1
.
aws ec2 modify-instance-metadata-defaults \
--region us-east-1
\
--http-tokens required \
--http-put-response-hop-limit 2
Expected output
{
"Return": true
}
To view the default account settings for the instance metadata options for the
specified Region
Use the get-instance-metadata-defaults
command and specify the
Region.
aws ec2 get-instance-metadata-defaults --region us-east-1
Example output
{
"AccountLevel": {
"HttpTokens": "required",
"HttpPutResponseHopLimit": 2
}
}
When you launch an
instance, you can configure the instance to require the use of
IMDSv2 by configuring the following fields:
When you specify that IMDSv2 is required, you must also enable the
Instance Metadata Service (IMDS) endpoint by setting Metadata
accessible to Enabled (console) or
HttpEndpoint
to enabled
(Amazon CLI).
- New console
-
To require the use of IMDSv2 on a new
instance
-
When launching a new instance in the Amazon EC2 console,
expand Advanced details, and do the
following:
-
For Metadata accessible,
choose Enabled.
-
For Metadata version,
choose V2 only (token
required).
For more information, see Advanced details.
- Old console
-
To require the use of IMDSv2 on a new
instance
For more information, see Step 3: Configure Instance
Details.
- Amazon CLI
-
To require the use of IMDSv2 on a new
instance
The following run-instances example launches a
c6i.large
instance with
--metadata-options
set to
HttpTokens=required
. When you specify a
value for HttpTokens
, you must also set
HttpEndpoint
to enabled
.
Because the secure token header is set to
required
for metadata retrieval requests,
this requires the instance to use IMDSv2 when
requesting instance metadata.
aws ec2 run-instances \
--image-id ami-0abcdef1234567890
\
--instance-type c6i.large
\
...
--metadata-options "HttpEndpoint=enabled,HttpTokens=required"
- PowerShell
-
To require the use of IMDSv2 on a new
instance
The following New-EC2Instance Cmdlet example launches a
c6i.large
instance with
MetadataOptions_HttpEndpoint
set to
enabled
and the
MetadataOptions_HttpTokens
parameter to
required
. When you specify a value for
HttpTokens
, you must also set
HttpEndpoint
to enabled
.
Because the secure token header is set to
required
for metadata retrieval requests,
this requires the instance to use IMDSv2 when
requesting instance metadata.
New-EC2Instance `
-ImageId ami-0abcdef1234567890
`
-InstanceType c6i.large
`
-MetadataOptions_HttpEndpoint enabled `
-MetadataOptions_HttpTokens required
- Amazon CloudFormation
-
To specify the metadata options for an instance using Amazon CloudFormation,
see the AWS::EC2::LaunchTemplate MetadataOptions property
in the Amazon CloudFormation User Guide.
When you register a new AMI or modify an existing AMI, you can set the
imds-support
parameter to v2.0
. Instances
launched from this AMI will have Metadata version set
to V2 only (token required) (console) or
HttpTokens
set to required
(Amazon CLI) . With
these settings, the instance requires that IMDSv2 is used when
requesting instance metadata.
Note that when you set imds-support
to v2.0
,
instances launched from this AMI will also have Metadata response
hop limit (console) or
http-put-response-hop-limit
(Amazon CLI) set to
2.
Do not use this parameter unless your AMI software supports
IMDSv2. After you set the value to v2.0
, you can't
undo it. The only way to "reset" your AMI is to create a new AMI from
the underlying snapshot.
To configure a new AMI for IMDSv2
Use one of the following methods to configure a new AMI
IMDSv2.
- Amazon CLI
-
The following register-image example registers an AMI using the
specified snapshot of an EBS root volume as device
/dev/xvda
. Specify v2.0
for the
imds-support
parameter so that instances
launched from this AMI will require that IMDSv2 is used
when requesting instance metadata.
aws ec2 register-image \
--name my-image
\
--root-device-name /dev/xvda \
--block-device-mappings DeviceName=/dev/xvda,Ebs={SnapshotId=snap-0123456789example
} \
--architecture x86_64 \
--imds-support v2.0
- PowerShell
-
The following Register-EC2Image Cmdlet example registers an AMI
using the specified snapshot of an EBS root volume as device
/dev/xvda
. Specify v2.0
for the
ImdsSupport
parameter so that instances
launched from this AMI will require that IMDSv2 is used
when requesting instance metadata.
Import-Module AWS.Tools.EC2 # Required for Amazon.EC2.Model object creation.
Register-EC2Image `
-Name 'my-image
' `
-RootDeviceName /dev/xvda `
-BlockDeviceMapping (
New-Object `
-TypeName Amazon.EC2.Model.BlockDeviceMapping `
-Property @{
DeviceName = '/dev/xvda';
EBS = (New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice -Property @{
SnapshotId = 'snap-0123456789example
;
VolumeType = 'gp3'
} )
} ) `
-Architecture X86_64 `
-ImdsSupport v2.0
To configure an existing AMI for IMDSv2
Use one of the following methods to configure an existing AMI for
IMDSv2.
- Amazon CLI
-
The following modify-image-attribute example modifies an existing
AMI for IMDSv2 only. Specify v2.0
for the
imds-support
parameter so that instances
launched from this AMI will require that IMDSv2 is used
when requesting instance metadata.
aws ec2 modify-image-attribute \
--image-id ami-0123456789example
\
--imds-support v2.0
- PowerShell
-
The following Edit-EC2ImageAttribute Cmdlet example modifies an
existing AMI for IMDSv2 only. Specify v2.0
for the imds-support
parameter so that instances
launched from this AMI will require that IMDSv2 is used
when requesting instance metadata.
Edit-EC2ImageAttribute `
-ImageId ami-0abcdef1234567890
`
-ImdsSupport 'v2.0'
You can create an IAM policy that prevents users from launching new
instances unless they require IMDSv2 on the new instance.
To enforce the use of IMDSv2 on all new instances by using an
IAM policy
To ensure that users can only launch instances that require the use of
IMDSv2 when requesting instance metadata, you can specify that
the condition to require IMDSv2 must be met before an instance
can be launched. For the example IAM policy, see Work with instance metadata.
By default, the IPv6 endpoint is disabled. This is true even if you are
launching an instance into an IPv6-only subnet. You can choose to enable the
IPv6 endpoint when you launch an instance.
The IPv6 endpoint for the IMDS is only accessible on instances built on the Amazon Nitro System.
Use one of the following methods to launch an instance with the IPv6 endpoint
enabled for IMDS.
- New console
-
To enable the IMDS IPv6 endpoint at launch
For more information, see Advanced details.
- Amazon CLI
-
The following run-instances example launches a c6i.large
instance with the IPv6 endpoint enabled for the IMDS. To
enable the IPv6 endpoint, for the --metadata-options
parameter, specify HttpProtocolIpv6=enabled
. When you
specify a value for HttpProtocolIpv6
, you must also set
HttpEndpoint
to enabled
.
aws ec2 run-instances \
--image-id ami-0abcdef1234567890
\
--instance-type c6i.large
\
...
--metadata-options "HttpEndpoint=enabled,HttpProtocolIpv6=enabled"
- PowerShell
-
The following New-EC2Instance Cmdlet example launches a
c6i.large
instance with the IPv6 endpoint enabled
for the IMDS. To enable the IPv6 endpoint, specify
MetadataOptions_HttpProtocolIpv6
as
enabled
. When you specify a value for
MetadataOptions_HttpProtocolIpv6
, you must also set
MetadataOptions_HttpEndpoint
to
enabled
.
New-EC2Instance `
-ImageId ami-0abcdef1234567890
`
-InstanceType c6i.large
`
-MetadataOptions_HttpEndpoint enabled `
-MetadataOptions_HttpProtocolIpv6 enabled
You can turn off access to the instance metadata by disabling the IMDS when
you launch an instance. You can turn on access later by re-enabling the IMDS.
For more information, see Turn on access
to instance metadata.
You can choose to disable the IMDS at launch or after launch. If you
disable the IMDS at launch, the following
might not work:
-
You might not have SSH access to your instance. The
public-keys/0/openssh-key
, which is your instance's
public SSH key, will not be accessible because the key is normally
provided and accessed from EC2 instance metadata.
-
EC2 user data will not be available and will not run at instance
start. EC2 user data is hosted on the IMDS. If you disable the IMDS,
you effectively turn off access to user data.
To access this functionality, you can re-enable the IMDS after
launch.
- New console
-
To turn off access to instance metadata at launch
For more information, see Advanced details.
- Old console
-
To turn off access to instance metadata at launch
For more information, see Step 3: Configure Instance
Details.
- Amazon CLI
-
To turn off access to instance metadata at launch at
launch
Launch the instance with --metadata-options
set
to HttpEndpoint=disabled
.
aws ec2 run-instances \
--image-id ami-0abcdef1234567890
\
--instance-type c6i.large
\
...
--metadata-options "HttpEndpoint=disabled"
- PowerShell
-
To turn off access to instance metadata at launch at
launch
The following New-EC2Instance Cmdlet example launches an instance
with MetadataOptions_HttpEndpoint
set to
disabled
.
New-EC2Instance `
-ImageId ami-0abcdef1234567890
`
-InstanceType c6i.large
`
-MetadataOptions_HttpEndpoint disabled
- Amazon CloudFormation
-
To specify the metadata options for an instance using Amazon CloudFormation, see
the AWS::EC2::LaunchTemplate MetadataOptions property in
the Amazon CloudFormation User Guide.