View tags for your EC2 instances using instance metadata - Amazon Elastic Compute Cloud
Allow access to tags in instance metadataRetrieve tags from instance metadataTurn off access to tags in instance metadata

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.

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.

Console
To allow access to tags in instance metadata during instance launch

  1. Follow the procedure to launch an instance.

  2. Expand Advanced details, and for Allow tags in metadata, choose Enable.

  3. 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.

AWS CLI
To allow access to tags in instance metadata during instance launch

Use the run-instances command and set InstanceMetadataTags to enabled. 

aws ec2 run-instances \
    --image-id ami-0abcdef1234567890 \
    --instance-type c3.large \
    ...
    --metadata-options "InstanceMetadataTags=enabled"
Console
To allow access to tags in instance metadata on a running or stopped instance

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select your instance, and then choose Actions, Instance settings, Allow tags in instance metadata.

  4. To allow access to tags in instance metadata, select the Allow check box.

  5. Choose Save.

AWS CLI
To allow access to tags in instance metadata on a running or stopped instance

Use the modify-instance-metadata-options command and set --instance-metadata-tags to enabled. 

aws ec2 modify-instance-metadata-options \
    --instance-id i-123456789example \
    --instance-metadata-tags enabled

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.

cURL

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
PowerShell

This example gets all the tag keys for an instance.

PS C:\> $token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri 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.

PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri 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.

cURL

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
PowerShell

This example gets all the tag keys for an instance.

PS C:\> Invoke-RestMethod -uri 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.

PS C:\> Invoke-RestMethod -uri 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

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select an instance, and then choose Actions, Instance settings, Allow tags in instance metadata.

  4. To turn off access to tags in instance metadata, clear the Allow check box.

  5. 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"
        }
    ]
]