Tag your Amazon EC2 resources

To help you manage your instances, images, and other Amazon EC2 resources, you can assign your own metadata to each resource in the form of tags. Tags enable you to categorize your Amazon resources in different ways, for example, by purpose, owner, or environment. This is useful when you have many resources of the same type—you can quickly identify a specific resource based on the tags that you've assigned to it. This topic describes tags and shows you how to create them.

Tag basics

A tag is a label that you assign to an Amazon resource. Each tag consists of a key and an optional value, both of which you define.

Tags enable you to categorize your Amazon resources in different ways, for example, by purpose, owner, or environment. For example, you could define a set of tags for your account's Amazon EC2 instances that helps you track each instance's owner and stack level.

The following diagram illustrates how tagging works. In this example, you've assigned two tags to each of your instances—one tag with the key Owner and another with the key Stack. Each tag also has an associated value.

We recommend that you devise a set of tag keys that meets your needs for each resource type. Using a consistent set of tag keys makes it easier for you to manage your resources. You can search and filter the resources based on the tags you add. For more information about how to implement an effective resource tagging strategy, see the Tagging Best Practices Amazon Whitepaper.

Tags don't have any semantic meaning to Amazon EC2 and are interpreted strictly as a string of characters. Also, tags are not automatically assigned to your resources. You can edit tag keys and values, and you can remove tags from a resource at any time. You can set the value of a tag to an empty string, but you can't set the value of a tag to null. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the old value. If you delete a resource, any tags for the resource are also deleted.

Tag your resources

You can tag most Amazon EC2 resources that already exist in your account. The following table lists the resources that support tagging.

If you're using the Amazon EC2 console, you can apply tags to resources by using the Tags tab on the relevant resource screen, or you can use the Tags Editor in the Amazon Resource Groups console. Some resource screens enable you to specify tags for a resource when you create the resource; for example, a tag with a key of Name and a value that you specify. In most cases, the console applies the tags immediately after the resource is created (rather than during resource creation). The console might organize resources according to the Name tag, but this tag doesn't have any semantic meaning to the Amazon EC2 service.

If you're using the Amazon EC2 API, the Amazon CLI, or an Amazon SDK, you can use the CreateTags EC2 API action to apply tags to existing resources. Additionally, some resource-creating actions enable you to specify tags for a resource when the resource is created. If tags cannot be applied during resource creation, we roll back the resource creation process. This ensures that resources are either created with tags or not created at all, and that no resources are left untagged at any time. By tagging resources at the time of creation, you can eliminate the need to run custom tagging scripts after resource creation. For more information about enabling users to tag resources on creation, see Grant permission to tag resources during creation.

The following table describes the Amazon EC2 resources that can be tagged, and the resources that can be tagged on creation using the Amazon EC2 API, the Amazon CLI, or an Amazon SDK.

You can tag instances, volumes, elastic graphics, network interfaces, and Spot Instance requests on creation using the Amazon EC2 launch instance wizard in the Amazon EC2 console. You can tag your EBS volumes on creation using the Volumes screen, or EBS snapshots using the Snapshots screen. Alternatively, use the resource-creating Amazon EC2 APIs (for example, RunInstances) to apply tags when creating your resource.

You can apply tag-based resource-level permissions in your IAM policies to the Amazon EC2 API actions that support tagging on creation to implement granular control over the users and groups that can tag resources on creation. Your resources are properly secured from creation—tags are applied immediately to your resources, therefore any tag-based resource-level permissions controlling the use of resources are immediately effective. Your resources can be tracked and reported on more accurately. You can enforce the use of tagging on new resources, and control which tag keys and values are set on your resources.

You can also apply resource-level permissions to the CreateTags and DeleteTags Amazon EC2 API actions in your IAM policies to control which tag keys and values are set on your existing resources. For more information, see Example: Tag resources.

For more information about tagging your resources for billing, see Using cost allocation tags in the Amazon Billing User Guide.

Tag restrictions

The following basic restrictions apply to tags:

You can't terminate, stop, or delete a resource based solely on its tags; you must specify the resource identifier. For example, to delete snapshots that you tagged with a tag key called DeleteMe, you must use the DeleteSnapshots action with the resource identifiers of the snapshots, such as snap-1234567890abcdef0.

When you tag public or shared resources, the tags you assign are available only to your Amazon account; no other Amazon account will have access to those tags. For tag-based access control to shared resources, each Amazon account must assign its own set of tags to control access to the resource.

You can't tag all resources. For more information, see Tagging support for Amazon EC2 resources.

Tags and access management

If you're using Amazon Identity and Access Management (IAM), you can control which users in your Amazon account have permission to create, edit, or delete tags. For more information, see Grant permission to tag resources during creation.

You can also use resource tags to implement attribute-based control (ABAC). You can create IAM policies that allow operations based on the tags for the resource. For more information, see Control access to EC2 resources using resource tags.

Tag your resources for billing

You can use tags to organize your Amazon bill to reflect your own cost structure. To do this, sign up to get your Amazon account bill with tag key values included. For more information about setting up a cost allocation report with tags, see Monthly cost allocation report in the Amazon Billing User Guide. To see the cost of your combined resources, you can organize your billing information based on resources that have the same tag key values. For example, you can tag several resources with a specific application name, and then organize your billing information to see the total cost of that application across several services. For more information, see Using cost allocation tags in the Amazon Billing User Guide.

Cost allocation tags can indicate which resources are contributing to costs, but deleting or deactivating resources doesn't always reduce costs. For example, snapshot data that is referenced by another snapshot is preserved, even if the snapshot that contains the original data is deleted. For more information, see Amazon Elastic Block Store volumes and snapshots in the Amazon Billing User Guide.

Work with tags using the console

You can use the Amazon EC2 console to display the tags of an individual resource, and to apply or remove tags from one resource at a time.

You can use the Tag Editor in the Amazon Resource Groups console to display the tags of all of your Amazon EC2 resources across all Regions. You can view tags by resource and by resource type, and you can see which resource types are associated with a specified tag. You can apply or remove tags from multiple resources and multiple resource types at a time. The Tag Editor provides a central, unified way to create and manage your tags. For more information, see the Tagging Amazon Resources User Guide.

Display tags

You can display the tags of an individual resource in the Amazon EC2 console. To display the tags of all your resources, use the Tag Editor in the Amazon Resource Groups console.

Display tags of an individual resource

When you select a resource-specific page in the Amazon EC2 console, it displays a list of those resources. For example, if you select Instances from the navigation pane, the console displays your Amazon EC2 instances. When you select a resource from one of these lists (for example, an instance), if the resource supports tags, you can view and manage its tags. On most resource pages, you can view the tags by choosing the Tags tab.

You can add a column to the resource list to display all values for tags with the same key. You can use this column to sort and filter the resource list by the tag.

Display tags for multiple resources

You can display tags across multiple resources by using the Tag Editor in the Amazon Resource Groups console. For more information, see the Tagging Amazon Resources User Guide.

Add and delete tags on an individual resource

You can manage tags for an individual resource directly from the resource's page.

Add and delete tags for multiple resources

Add a tag when you launch an instance

Filter a list of resources by tag

You can filter your list of resources based on one or more tag keys and tag values.

For more information about using filters in the Amazon EC2 console, see List and filter your resources.

To filter multiple resources across multiple Regions by tag using the Tag Editor

You can use the Tag Editor in the Amazon Resource Groups console to filter multiple resources across multiple Regions by tag. For more information, see Finding resources to tag in the Tagging Amazon Resources User Guide.

Work with tags using the command line

You can add tags to many EC2 resources when you create them, using the tag specifications parameter for the create command. You can view the tags for a resource using the describe command for the resource. You can also add, update, or delete tags for your existing resources using the following commands.

Add tags on resource creation

The following examples demonstrate how to apply tags when you create resources.

aws ec2 run-instances \
    --image-id ami-abc12345 \
    --count 1 \
    --instance-type t2.micro \
    --key-name MyKeyPair \
    --subnet-id subnet-6e7f829e \
    --tag-specifications 'ResourceType=instance,Tags=[{Key=webserver,Value=production}]' 'ResourceType=volume,Tags=[{Key=cost-center,Value=cc123}]' 

aws ec2 run-instances \
    --image-id ami-abc12345 \
    --count 1 \
    --instance-type t2.micro \
    --key-name MyKeyPair \
    --subnet-id subnet-6e7f829e \
    --tag-specifications 'ResourceType=instance,Tags=[{Key=cost-center,Value=cc123}]' 'ResourceType=volume,Tags=[{Key=cost-center,Value=cc123}]' 

aws ec2 create-volume \
    --availability-zone us-east-1a \
    --volume-type gp2 \
    --size 80 \
    --tag-specifications 'ResourceType=volume,Tags=[{Key=purpose,Value=production},{Key=cost-center,Value=cc123}]'

Add tags to an existing resource

The following examples demonstrate how to add tags to an existing resource using the create-tags command.

aws ec2 create-tags \
    --resources ami-78a54011 \
    --tags Key=Stack,Value=production

aws ec2 create-tags \
    --resources ami-1a2b3c4d i-1234567890abcdef0 \
    --tags Key=webserver,Value=  Key=stack,Value=Production

aws ec2 create-tags \
    --resources i-1234567890abcdef0 \
    --tags 'Key="[Group]",Value=test'

aws ec2 create-tags ^
    --resources i-1234567890abcdef0 ^
    --tags Key=\"[Group]\",Value=test

aws ec2 create-tags `
    --resources i-1234567890abcdef0 `
    --tags 'Key=\"[Group]\",Value=test'

Describe tagged resources

The following examples show you how to use filters with the describe-instances to view instances with specific tags. All EC2 describe commands use this syntax to filter by tag across a single resource type. Alternatively, you can use the describe-tags command to filter by tag across EC2 resource types.

aws ec2 describe-instances \
    --filters Name=tag-key,Values=Stack

aws ec2 describe-instances \
    --filters Name=tag:Stack,Values=production

aws ec2 describe-instances \
    --filters Name=tag-value,Values=production

aws ec2 describe-tags \
    --filters Name=key,Values=Stack Name=value,Values=Test

Work with instance tags in 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 at launch using the Amazon 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 Amazon 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

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 Amazon 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

View if access to tags in instance metadata is allowed

For each instance, you can use the Amazon EC2 console or Amazon CLI to view whether access to instance tags from the instance metadata is allowed.

To view if access to tags in instance metadata is allowed using the Amazon CLI

Use the describe-instances command and specify the instance ID.

aws ec2 describe-instances \
    --instance-ids i-1234567890abcdef0

The following example output is truncated for space. The "InstanceMetadataTags" parameter indicates whether tags in instance metadata is allowed. If the value is enabled, tags in instance metadata is allowed. If the value is disabled, tags in instance metadata is not allowed.

{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-1234567890abcdef0",
			...
			
			"MetadataOptions": {
			"State": "applied",
			"HttpTokens": "optional",
			"HttpPutResponseHopLimit": 1,
			"HttpEndpoint": "enabled",
			"HttpProtocolIpv6": "disabled",
			"InstanceMetadataTags": "enabled"
			},
			...

Retrieve tags from instance metadata

If instance tags are allowed in the instance metadata, the tags/instance category is accessible from the instance metadata. For examples on how to retrieve tags from the instance metadata, see Get the instance tags for an instance.

Add tags to a resource using CloudFormation

With Amazon EC2 resource types, you specify tags using either a Tags or TagSpecifications property.

The following examples add the tag Stack=Production to AWS::EC2::Instance using its Tags property.

Tags:
  - Key: "Stack"
    Value: "Production"

"Tags": [
    {
        "Key": "Stack",
        "Value": "Production"
    }
]

The following examples add the tag Stack=Production to AWS::EC2::LaunchTemplate LaunchTemplateData using its TagSpecifications property.

TagSpecifications:
  - ResourceType: "instance"
    Tags:
    - Key: "Stack"
      Value: "Production"

"TagSpecifications": [
    {
        "ResourceType": "instance",
        "Tags": [
            {
                "Key": "Stack",
                "Value": "Production"
            }
        ]
    }
]