Configure instance metadata options for new instances
You can configure the following instance metadata options for new
instances.
The settings for these options are configured at the account level, either directly in the
account or by using a declarative policy. They must be configured in each
AWS Region where you want to configure instance metadata options. Using a
declarative policy allows you to apply the settings across multiple Regions
simultaneously, as well as across multiple accounts simultaneously. When a
declarative policy is in use, you can't modify the settings directly within an
account. This topic describes how to configure the settings directly within an
account. For information about using declarative policies, see Declarative policies in the AWS Organizations User
Guide.
You can use the following methods to require the use of IMDSv2 on your
new instances.
Set IMDSv2 as the default for the account
You can set the default version for the instance metadata service (IMDS)
at the account level for each AWS Region. This means that when you launch
a new instance, the instance metadata
version is automatically set to the account-level default. However, you can
manually override the value at launch or after launch. For more information
about how the account-level settings and manual overrides affect an
instance, see Order of precedence for instance metadata options.
Setting the account-level default does not reset existing instances. For example, if you set
the account-level default to IMDSv2, any existing instances that
are set to IMDSv1 are not affected. If you want to change the
value on existing instances, you must manually change the value on the
instances themselves.
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, and IMDSv1 will
be disabled. With this account default, when you launch an instance, the
following are the default values for the instance:
- Console
-
To set IMDSv2 as the default for the account for the specified Region
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
To change the AWS 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 has the setting
ImdsSupport: v2.0; otherwise it
defaults to 1.
-
Choose Update.
- AWS 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 has the setting ImdsSupport: v2.0;
otherwise it defaults to 1.
aws ec2 modify-instance-metadata-defaults \
--region us-east-1 \
--http-tokens required \
--http-put-response-hop-limit 2
The following is example 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
The following is example output.
{
"AccountLevel": {
"HttpTokens": "required",
"HttpPutResponseHopLimit": 2
},
"ManagedBy": "account"
}
The ManagedBy field indicates the entity that
configured the settings. In this example, account
indicates that the settings were configured directly in the
account. A value of declarative-policy would mean
the settings were configured by a declarative policy. For more
information, see Declarative policies in the AWS Organizations User Guide.
To set IMDSv2 as the default for the account for all Regions
Use the modify-instance-metadata-defaults command to
modify the IMDS account level settings for all Regions.
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 has the setting ImdsSupport: v2.0;
otherwise it defaults to 1.
echo -e "Region \t Modified" ; \
echo -e "-------------- \t ---------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 modify-instance-metadata-defaults \
--region $region \
--http-tokens required \
--http-put-response-hop-limit 2 \
--output text)
echo -e "$region \t $output"
);
done
The following is example output.
Region Modified
-------------- ---------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
To view the default account settings for the instance metadata options for all Regions
Use the get-instance-metadata-defaults command.
echo -e "Region \t Level Hops HttpTokens" ; \
echo -e "-------------- \t ------------ ---- ----------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 get-instance-metadata-defaults \
--region $region \
--output text)
echo -e "$region \t $output"
);
done
The following is example output.
Region Level Hops HttpTokens
-------------- ------------ ---- ----------
ap-south-1 ACCOUNTLEVEL 2 required
eu-north-1 ACCOUNTLEVEL 2 required
eu-west-3 ACCOUNTLEVEL 2 required
...
- PowerShell
-
To set IMDSv2 as the default for the account for the specified Region
Use the Edit-EC2InstanceMetadataDefault cmdlet and
specify the Region in which to modify the IMDS account level
settings. Include -HttpToken set to
required and
-HttpPutResponseHopLimit 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 has the setting ImdsSupport: v2.0;
otherwise it defaults to 1.
Edit-EC2InstanceMetadataDefault `
-Region us-east-1 `
-HttpToken required `
-HttpPutResponseHopLimit 2
The following is example output.
True
To view the default account settings for the instance metadata options for the specified Region
Use the Get-EC2InstanceMetadataDefault cmdlet and
specify the Region.
Get-EC2InstanceMetadataDefault -Region us-east-1 | Format-List
The following is example output.
HttpEndpoint :
HttpPutResponseHopLimit : 2
HttpTokens : required
InstanceMetadataTags :
To set IMDSv2 as the default for the account for all Regions
Use the Edit-EC2InstanceMetadataDefault cmdlet to
modify the IMDS account level settings for all Regions.
Include -HttpToken set to required
and -HttpPutResponseHopLimit 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 has the setting ImdsSupport: v2.0;
otherwise it defaults to 1.
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
Modified = (Edit-EC2InstanceMetadataDefault `
-Region $_ `
-HttpToken required `
-HttpPutResponseHopLimit 2)
}
} | `
Format-Table Region, Modified -AutoSize
Expected output
Region Modified
------ --------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
To view the default account settings for the instance metadata options for all Regions
Use the Get-EC2InstanceMetadataDefault cmdlet.
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit
HttpTokens = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens
}
} | `
Format-Table -AutoSize
Example output
Region HttpPutResponseHopLimit HttpTokens
------ ----------------------- ----------
ap-south-1 2 required
eu-north-1 2 required
eu-west-3 2 required
...
Enforce IMDSv2 at the account level
You can enforce the use of IMDSv2 at the account level for each AWS Region. When
enforced, instances can only launch if they're configured to require
IMDSv2. This enforcement applies regardless of how the instance or
AMI is configured.
Before enabling IMDSv2 enforcement at the account level, ensure that your
applications and AMIs support IMDSv2. For more information, see
Recommended path to requiring IMDSv2. If
IMDSv2 enforcement is enabled and httpTokens is not
set to required in either the instance configuration at
launch, the account settings, or the AMI configuration, the instance
launch will fail. For troubleshooting information, see Launching an IMDSv1-enabled instance fails.
This setting does not change the IMDS version of existing instances, but blocks enabling
IMDSv1 on existing instances that currently have IMDSv1
disabled.
- Console
-
To enforce IMDSv2 for the account in the specified Region
-
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
To change the AWS Region, use the Region selector in the top 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 Metadata version, choose V2 only (token
required).
-
For Enforce IMDSv2, choose
Enabled.
-
Choose Update.
- AWS CLI
-
To enforce IMDSv2 for the account in the specified Region
Use the modify-instance-metadata-defaults command and
specify the Region in which to enforce IMDSv2.
aws ec2 modify-instance-metadata-defaults \
--region us-east-1 \
--http-tokens required \
--http-tokens-enforced enabled
The following is example output.
{
"Return": true
}
To view the IMDSv2 enforcement setting for the account in a specific Region
Use the get-instance-metadata-defaults command and
specify the Region.
aws ec2 get-instance-metadata-defaults --region us-east-1
The following is example output.
{
"AccountLevel": {
"HttpTokens": "required",
"HttpTokensEnforced": "enabled"
},
"ManagedBy": "account"
}
The ManagedBy field indicates the entity that configured the settings. In
this example, account indicates that the settings
were configured directly in the account. A value of
declarative-policy would mean the settings were
configured by a declarative policy. For more information, see
Declarative policies in the AWS Organizations User Guide.
To enforce IMDSv2 for the account for all Regions
Use the modify-instance-metadata-defaults command to
enforce IMDSv2 in all Regions.
echo -e "Region \t Modified" ; \
echo -e "-------------- \t ---------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 modify-instance-metadata-defaults \
--region $region \
--http-tokens-enforced enabled \
--output text)
echo -e "$region \t $output"
);
done
The following is example output.
Region Modified
-------------- ---------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
To view the IMDSv2 enforcement settings for the account in all Regions
Use the get-instance-metadata-defaults command.
echo -e "Region \t Level HttpTokensEnforced" ; \
echo -e "-------------- \t ------------ ----------------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 get-instance-metadata-defaults \
--region $region \
--query 'AccountLevel.HttpTokensEnforced' \
--output text)
echo -e "$region \t ACCOUNTLEVEL $output"
);
done
The following is example output.
Region Level HttpTokensEnforced
-------------- ------------ ------------------
ap-south-1 ACCOUNTLEVEL enabled
eu-north-1 ACCOUNTLEVEL enabled
eu-west-3 ACCOUNTLEVEL enabled
...
- PowerShell
-
To enforce IMDSv2 for the account in the specified Region
Use the Edit-EC2InstanceMetadataDefault cmdlet and
specify the Region in which to enforce IMDSv2.
Edit-EC2InstanceMetadataDefault `
-Region us-east-1 `
-HttpToken required `
-HttpPutResponseHopLimit 2
The following is example output.
@{
Return = $true
}
To view the IMDSv2 enforcement setting for the account in a specific Region
Use the Get-EC2InstanceMetadataDefault command and specify the Region.
Get-EC2InstanceMetadataDefault -Region us-east-1
The following is example output.
@{
AccountLevel = @{
HttpTokens = "required"
HttpTokensEnforced = "enabled"
}
ManagedBy = "account"
}
The ManagedBy field indicates the entity that configured the settings. In
this example, account indicates that the settings
were configured directly in the account. A value of
declarative-policy would mean the settings were
configured by a declarative policy. For more information, see
Declarative policies in the AWS Organizations User Guide.
To enforce IMDSv2 for the account for all Regions
Use the modify-instance-metadata-defaults command to
enforce IMDSv2 in all Regions.
echo -e "Region \t Modified" ; \
echo -e "-------------- \t ---------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 modify-instance-metadata-defaults \
--region $region \
--http-tokens-enforced enabled \
--output text)
echo -e "$region \t $output"
);
done
The following is example output.
Region Modified
-------------- ---------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
To set IMDSv2 as the default for the account for all Regions
Use the Edit-EC2InstanceMetadataDefault cmdlet to
modify the IMDS account level settings for all Regions.
Include -HttpToken set to required
and -HttpPutResponseHopLimit 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 has the setting ImdsSupport: v2.0;
otherwise it defaults to 1.
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
Modified = (Edit-EC2InstanceMetadataDefault `
-Region $_ `
-HttpToken required `
-HttpPutResponseHopLimit 2)
}
} | `
Format-Table Region, Modified -AutoSize
Expected output
Region Modified
------ --------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
To view the default account settings for the instance metadata options for all Regions
Use the Get-EC2InstanceMetadataDefault cmdlet.
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit
HttpTokens = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens
}
} | `
Format-Table -AutoSize
Example output
Region HttpPutResponseHopLimit HttpTokens
------ ----------------------- ----------
ap-south-1 2 required
eu-north-1 2 required
eu-west-3 2 required
...
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 (AWS CLI).
In a container environment, when IMDSv2 is required, we recommend
setting the hop limit to 2. For more information, see Instance metadata access considerations.
- 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).
-
(Container environment) For Metadata
response hop limit, choose
2.
For more information, see Advanced details.
- AWS 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.
In a container environment, when IMDSv2 is required,
we recommend setting the hop limit to 2 with
HttpPutResponseHopLimit=2.
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--instance-type c6i.large \
...
--metadata-options "HttpEndpoint=enabled,HttpTokens=required,HttpPutResponseHopLimit=2"
- 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
- CloudFormation
-
To specify the metadata options for an instance using CloudFormation,
see the AWS::EC2::LaunchTemplate MetadataOptions property
in the AWS 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 (AWS 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 (AWS 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 for
IMDSv2.
- AWS 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.
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.
- AWS 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-0abcdef1234567890 \
--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 does one of the following:
-
Prevents users from launching new instances unless they require
IMDSv2 on the new instance.
-
Prevents users from calling the ModifyInstanceMetadataOptions API
to change the metadata options of a running instance. Restrict
access to the ModifyInstanceMetadataOptions httpTokens property to
prevent unintended updates of running instances.
-
Prevent users from calling the ModifyInstanceMetadataDefaults API
to change the account default settings of both httpTokens and
httpTokensEnforced. Restricting access to these two properties will
ensure that only authorized roles can modify the account
defaults.
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, do the
following:
-
Restrict access to both ModifyInstanceMetadataOptions
and ModifyInstanceMetadataDefaults API, and more
specifically the httpTokens and
httpTokensEnforced properties.
-
Then, set the account default to httpTokens =
required and httpTokensEnforced =
enabled.
For the example IAM policy, see Work with instance metadata.
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. The IPv6 endpoint remains disabled even if
you launch an instance into an IPv6-only subnet. To enable the IPv6 endpoint,
you need to do so explicitly. When you enable the IPv6 endpoint, the IPv4
endpoint remains enabled.
You can enable the IPv6 endpoint at instance launch or after.
Requirements for enabling the IPv6 endpoint
Use any of the following methods to launch an instance with the IMDS IPv6
endpoint enabled.
- Console
-
To enable the IMDS IPv6 endpoint at instance launch
For more information, see Advanced details.
- AWS CLI
-
To enable the IMDS IPv6 endpoint at instance launch
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
-
To enable the IMDS IPv6 endpoint at instance launch
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.
- Console
-
To turn off access to instance metadata at launch
For more information, see Advanced details.
- AWS 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
- CloudFormation
-
To specify the metadata options for an instance using CloudFormation, see
the AWS::EC2::LaunchTemplate MetadataOptions property in
the CloudFormation User Guide.
By default, instance tags are not accessible in the instance metadata. For
each instance, you must explicitly allow access. If access is allowed, instance
tag keys must comply with specific character
restrictions, otherwise the instance launch will fail. For more information, see
Enable access to tags in instance metadata.