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.

To allow 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 allow access to tags in instance metadata, select the Allow check box.

5. Choose Save.

To allow access to tags in instance metadata at launch using the AWS CLI

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"

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

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