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.
To allow access to tags in instance metadata during instance launch
-
Follow the procedure to launch an instance.
-
Expand Advanced details, and for Allow tags in metadata, choose Enable.
-
In the Summary panel, review your instance configuration, and then choose Launch instance. For more information, see Launch an EC2 instance using the launch instance wizard in the console.
To allow access to tags in instance metadata on a running or stopped instance
-
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/
. -
In the navigation pane, choose Instances.
-
Select your instance, and then choose Actions, Instance settings, Allow tags in instance metadata.
-
To allow access to tags in instance metadata, select the Allow checkbox.
-
Choose Save.
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.
This example gets all the tag keys for an instance.
[ec2-user ~]$
TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \ && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/tags/instance
Name Environment
This example gets the value of the Name
key that
was obtained in the previous example. The IMDSv2 request uses the
stored token that was created using the command in the previous example.
The token must not be expired.
[ec2-user ~]$
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/tags/instance/Name
MyInstance
Instance Metadata Service Version 1
Run the following examples on your Amazon EC2 instance to retrieve the instance metadata for IMDSv1.
This example gets all the tag keys for an instance.
[ec2-user ~]$
curl http://169.254.169.254/latest/meta-data/tags/instance
Name Environment
This example gets the value of the Name
key that
was obtained in the previous example.
[ec2-user ~]$
curl http://169.254.169.254/latest/meta-data/tags/instance/Name
MyInstance
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--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--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"
}
]
]