View tags for your EC2 instances using instance metadata
You can access an instance's tags from the instance metadata. By accessing tags from the
instance metadata, you no longer need to use the DescribeInstances
or
DescribeTags
API calls to retrieve tag information, which reduces your
API transactions per second, and lets your tag retrievals scale with the number of
instances that you control. Furthermore, local processes that are running on an instance
can view the instance's tag information directly from the instance metadata.
By default, tags are not available from the instance metadata; you must explicitly allow access. You can allow access at instance launch, or after launch on a running or stopped instance. You can also allow access to tags by specifying this in a launch template. Instances that are launched by using the template allow access to tags in the instance metadata.
If you add or remove an instance tag, the instance metadata is updated while the instance is running, without needing to stop and then start the instance.
Tasks
Allow access to tags in instance metadata
By default, there is no access to instance tags in the instance metadata. For each instance, you must explicitly allow access by using one of the following methods.
Note
If you allow access to tags in instance metadata, instance tag keys are subject to specific restrictions. Non-compliance will result in failed launches for new instances or an error for existing instances. The restrictions are:
-
Can only include letters (
a-z
,A-Z
), numbers (0-9
), and the following characters:+ - = . , _ : @
. -
Can't contain spaces or
/
. -
Can't consist only of
.
(one period),..
(two periods), or_index
.
For more information, see Tag restrictions.
Retrieve tags from instance metadata
After you allow access to instance tags in the instance metadata, you can access the
tags/instance
category from the instance metadata. For more information, see
Access instance metadata for an EC2 instance.
Instance Metadata Service Version 2
Run the following examples on your Amazon EC2 instance to retrieve the instance metadata for IMDSv2.
Instance Metadata Service Version 1
Run the following examples on your Amazon EC2 instance to retrieve the instance metadata for IMDSv1.
Turn off access to tags in instance metadata
To turn off access to instance tags in the instance metadata, use one of the following methods. You don't need to turn off access to instance tags on instance metadata at launch because it's turned off by default.
To turn off access to tags in instance metadata using the console
-
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/
. -
In the navigation pane, choose Instances.
-
Select an instance, and then choose Actions, Instance settings, Allow tags in instance metadata.
-
To turn off access to tags in instance metadata, clear the Allow checkbox.
-
Choose Save.
To turn off access to tags in instance metadata using the AWS CLI
Use the modify-instance-metadata-options command and set
--instance-metadata-tags
to disabled
.
aws ec2 modify-instance-metadata-options \ --instance-id
i-123456789example
\ --instance-metadata-tags disabled
To view whether access to tags in instance metadata is allowed using the AWS CLI
Use the describe-instances
command and specify the instance ID. Use the --query
parameter
to display only the instance metadata options in the results.
aws ec2 describe-instances \ --instance-ids
i-1234567890abcdef0
\ --query "Reservations[*].Instances[*].MetadataOptions"
The following is example output. The value of InstanceMetadataTags
indicates whether access to tags in instance metadata is allowed. If the value is
enabled
, it is allowed. If the value is disabled
, it is
not allowed.
[
[
{
"State": "applied",
"HttpTokens": "required",
"HttpPutResponseHopLimit": 2,
"HttpEndpoint": "enabled",
"HttpProtocolIpv6": "disabled",
"InstanceMetadataTags": "enabled"
}
]
]