Did this page help you? Yes No Tell us about it...

Using Tags

Topics

To help you manage your Amazon EC2 instances, images, and other Amazon EC2 resources, you can assign your own metadata to each resource in the form of tags. This section describes tags and how to create them.

Tag Basics

Each EC2 tag consists of a key and a value, both of which you define. For example, you could define a set of tags for your account's instances that helps you track each instance's owner and stack level. The following diagram illustrates the concept. In the diagram, you've assigned two tags to each of your instances, one called Owner and another called Stack. Each of the tags also has an associated value.

Tags let you categorize your EC2 resources in different ways, e.g., by purpose, owner, environment, etc. We recommend you devise a set of tag keys that meets your needs for each resource type. Using a consistent set of tag keys will make it easier to manage your resources. You can search and filter the resources based on the tags.

AWS doesn't apply any semantic meaning to your tags; they're interpreted strictly as strings of characters. AWS doesn't automatically set any tags on resources.

	Note
	You must not prefix your tag names or values with `aws:`. Tags prefixed with `aws:` have been created by AWS and cannot be edited or deleted.

You can assign tags only to resources that already exist. Exception: You can add tags when you launch an instance in the AWS Management Console. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the old value. You can edit tag keys and values, and you can remove tags from a resource at any time. You can set a tag's value to the empty string, but you can't set a tag's value to null.

If you're using AWS Identity and Access Management (IAM), you can control which Users in your AWS Account have permission to create, edit, or delete tags. For more information about IAM, see AWS Identity and Access Management.

Tag Restrictions

The following basic restrictions apply to tags:

Maximum Number of Tags Per Resource—10
Maximum Key Length—128 Unicode characters
Maximum Value Length—256 Unicode characters
Unavailable Prefix—aws: (we have reserved it for tag names and values)

Tag keys and values are case sensitive.

You can't terminate, stop, or delete a resource based solely on its tags; you must specify the resource identifier instead (e.g., i-1a2b3c4d). For example, to delete snapshots that have been tagged with a tag key called DeleteMe, you must first get a list of the those snapshots by using a DescribeSnapshots call with a filter on the tag. Then you would call DeleteSnapshots with the IDs of the snapshots (e.g., snap-1a2b3c4d). You can't call DeleteSnapshots with a filter on the tag. For more information about using filters when listing your resources, see Listing and Filtering Your Resources.

An instance can't retrieve its own tags from its metadata (for more information about metadata, see Using Instance Metadata). Tag information is available only through the EC2 API.

Resources You Can Tag

You can tag the following Amazon EC2 and Amazon VPC resources:

images (AMIs, kernels, RAM disks)
instances
security groups
Amazon EBS volumes
Amazon EBS snapshots
Reserved Instances
Spot Instance requests
VPCs
subnets
Internet gateways
VPN connections
virtual private gateways
customer gateways
route tables
network ACLs
DHCP options sets

Following are the Amazon EC2 resources you cannot tag:

Elastic IP addresses
Key pairs
Placement groups

You can tag public or shared resources, but the tags you assign are available only to your AWS account and not to the other accounts sharing the resource.

AWS Management Console

In this section, we'll show you how tags work in the AWS Management Console.

Note

Currently in the AWS Management Console, you can add tags only to instances, images, volumes, and snapshots.

The AWS Management Console is designed to let you add, edit, or remove tags only from a single resource at a time, whereas the EC2 API and command line tools let you do that with multiple resources in one call.

The AWS Management Console displays lists of your EC2 instances, images, and other resources. When you select a resource in one of these lists, a Description tab provides detailed information about the resource. Adjacent to that tab is a Tags tab where you can manage tags for the resource. The following image shows the tab for an instance with two tags (Name = DNS Server and Purpose = Network Management).

Adding or Deleting Tags

To add a tag, click Add/Edit Tags, which opens a separate dialog box like the following. The first tag on the page automatically uses Name as the key. However, you can change it; using Name is only a suggestion.

To delete a tag, click the X for the tag in the Remove column.

Displaying Tags as a Column in the List

Once you've added tags, you'll probably want them to appear in the resource list, so that you can sort and filter the resource list by tag. On the Tags tab, just click Show Column for the tag.

The tag appears in the resource list as a new Name column.

Filtering the List by Tag

You can filter your list of resources by a particular tag's value. Just click the filter icon in the top right corner of the tag's column. The following image shows filtering by Name = DNS Server. You can filter the list based on multiple tag keys and multiple tag values.

When you apply the filter, the filter icon changes to indicate the filtering.

So far, you've seen how to add tags to an existing resource. The console enables you to add tags when you launch instances. There's a page in the Classic wizard where you specify tags. As mentioned previously, the first tag on the page automatically uses Name as the key. However, you can change it; using Name is only a suggestion.

Command Line Tools

For information about getting the command line tools, see Getting Started with the Command Line Tools.

Summary of available commands:

ec2-create-tags—Adds a set of tags to a set of resources. You also use this to update a tag's value (overwrites the existing value).
ec2-delete-tags—Deletes a set of tags from a set of resources.
ec2-describe-tags—Lists your tags, or just certain ones you specify.

For details about each command, go to the Amazon Elastic Compute Cloud Command Line Reference.

Adding Tags

Let's say you want to add the same two tags to an AMI and an instance. One tag is webserver (with no value), and the other is stack=Production. In this example, the value of the webserver tag is an empty string.

PROMPT>  ec2-create-tags ami-1a2b3c4d i-6f5d4e3a --tag webserver --tag stack=Production
TAG  ami-1a2b3c4d  image  webserver
TAG  ami-1a2b3c4d  image  stack  Production
TAG  i-6f5d4e3a  image  webserver
TAG  i-6f5d4e3a  image  stack  Production

Listing Tags

You can list your tags and filter the results different ways, as shown in the following examples.

This example describes all the tags belonging to your account.

PROMPT> ec2-describe-tags
TAG  ami-1a2b3c4d  image  webserver
TAG  ami-1a2b3c4d  image  stack  Production
TAG  i-5f4e3d2a  instance  webserver
TAG  i-5f4e3d2a  instance  stack  Production
TAG  i-12345678  instance  database_server
TAG  i-12345678  instance  stack  Test

This example describes the tags for the AMI with ID ami-1a2b3c4d.

PROMPT> ec2-describe-tags --filter "resource-id=ami-1a2b3c4d"
TAG  ami-1a2b3c4d  image  webserver
TAG  ami-1a2b3c4d  image  stack  Production

This example describes the tags for all your instances.

PROMPT> ec2-describe-tags --filter "resource-type=instance"
TAG  i-5f4e3d2a  instance  webserver
TAG  i-5f4e3d2a  instance  stack  Production
TAG  i-12345678  instance  database_server
TAG  i-12345678  instance  stack  Test

This example describes the tags for all your instances tagged with the name webserver.

PROMPT> ec2-describe-tags --filter "resource-type=instance" --filter "key=webserver"
TAG  i-5f4e3d2a  instance  webserver

This example describes the tags for all your instances tagged with either stack=Test or stack=Production.

PROMPT> ec2-describe-tags --filter "resource-type=instance" --filter "key=stack" --filter "value=Test" --filter "value=Production"
TAG  i-5f4e3d2a  instance  stack  Production
TAG  i-12345678  instance  stack  Test

This example describes the tags for all your instances tagged with Purpose=[empty string].

PROMPT> ec2-describe-tags --filter "resource-type=instance" --filter "key=Purpose" --filter "value="

Changing Tag Values

Let's say you now want to change the value of the stack tag for one of the AMIs from Production to Test. You use the ec2-create-tags command to overwrite the original tag value.

PROMPT>  ec2-create-tags ami-1a2b3c4d  --tag stack=Test
TAG  ami-1a2b3c4d  image  stack  Test

Deleting Tags

Now let's say you want to delete the tags you originally assigned to the AMI and instance. You don't need to specify the value.

PROMPT>  ec2-delete-tags ami-1a2b3c4d i-6f5d4e3a --tag webserver --tag stack

If you specify a value for the key, the tag is deleted only if the tag's value matches the one you specified. If you specify the empty string as the value, the tag is deleted only if the tag's value is the empty string. The following example specifies the empty string as the value for the tag to delete (notice the equals sign after Owner).

PROMPT>  ec2-delete-tags snap-1a2b3c4d --tag Owner=

Filtering the List of Resources by Tags

You can describe your resources and filter the results based on the tag. Let's say that you've tagged all your Amazon EBS volumes with an Owner tag and a Purpose tag. You've got a series of teams (TeamA, TeamB, TeamC, etc.), and each has a series of volumes they own. You can get tag descriptions and filter the results by volume.

PROMPT>  ec2-describe-tags --filter resource-type=volume
TAG  vol-abcd1234  volume  Owner  TeamA
TAG  vol-abcd1234  volume  Purpose  Project1
TAG  vol-efba9876  volume  Owner  TeamA
TAG  vol-efba9876  volume  Purpose Project2
TAG  vol-4562dabf  volume  Owner  TeamA
TAG  vol-4562dabf  volume  Purpose  RawLogData
TAG  vol-2a3d4b5f  volume  Owner  TeamB
TAG  vol-2a3d4b5f  volume  Purpose Project1
TAG  vol-9f8g7d6c  volume  Owner  TeamB
TAG  vol-9f8g7d6c  volume  Purpose  Project2
TAG  vol-3b3a4c4d  volume  Owner  TeamB
TAG  vol-3b3a4c4d  volume  Purpose Logs
TAG  vol-1234abcd  volume  Owner  TeamC
TAG  vol-1234abcd  volume  Purpose Project1
TAG  vol-7f7g7d7a  volume  Owner  TeamC
TAG  vol-7f7g7d7a  volume  Purpose  Project2
TAG  vol-4a4b4c4d  volume  Owner  TeamC
TAG  vol-4a4b4c4d  volume  Purpose Logs

Likewise, you can get volume descriptions, and filter the results by tag. The filter name you use is tag:key. Let's say you want to get a list of just the volumes belonging to either TeamA or TeamB, and that contain log data. This time you use ec2-describe-volumes with a filter based on the tags of interest. You use a wildcard to find the volumes with "Log" in the Purpose tag's value.

PROMPT>  ec2-describe-volumes --filter tag:Owner=TeamA --filter tag:Owner=TeamB --filter tag:Purpose=*Log*
VOLUME  vol-4562dabf  5  us-east-1b  available   2010-02-22T22:50:43+0000   Owner  TeamA  Purpose  RawLogData
VOLUME  vol-3b3a4c4d  12  us-east-1b  available  2010-05-01T13:09:27+0000   Owner  TeamB  Purpose Logs

API

Summary of available API actions:

CreateTags—Adds a set of tags to a set of resources. You also use this to update a tag's value (overwrites the existing value).
DeleteTags—Deletes a set of tags from a set of resources.
DescribeTags—Lists your tags, or just certain ones you specify.

For details about each action and examples, go to the Amazon Elastic Compute Cloud API Reference.

Using the API to add, update, list, and delete tags is straightforward. The topics in the API reference show examples. In the following sections, we will demonstrate how you can list tags, or list resources and filter the results based on tags.

Filtering the List of Resources by Tags

Example Query request:

https://ec2.amazonaws.com/?Action=DescribeTags
&Filter.1.Name=resource-type
&Filter.1.Value=volume
&AuthParams

In this example, the response includes 18 tags covering 9 volumes.

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-04-01/">
   <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
   <tagSet>
       <item>
         <resourceId>vol-abcd1234</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamA</value>
      </item>
      <item>
         <resourceId>vol-abcd1234</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Project1</value>
      </item>
      <item>
         <resourceId>vol-efba9876</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamA</value>
      </item>
      <item>
         <resourceId>vol-efba9876</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Project2</value>
      </item>
      <item>
         <resourceId>vol-4562dabf</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamA</value>
      </item>
      <item>
         <resourceId>vol-4562dabf</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>RawLogData</value>
      </item>
      <item>
         <resourceId>vol-2a3d4b5f</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamB</value>
      </item>
      <item>
         <resourceId>vol-2a3d4b5f</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Project1</value>
      </item>
      <item>
         <resourceId>vol-9f8g7d6c</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamB</value>
      </item>
      <item>
         <resourceId>vol-9f8g7d6c</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Project2</value>
      </item>
      <item>
         <resourceId>vol-3b3a4c4d</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamB</value>
      </item>
      <item>
         <resourceId>vol-3b3a4c4d</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Logs</value>
      </item>
        <item>
         <resourceId>vol-1234abcd</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamC</value>
      </item>
      <item>
         <resourceId>vol-1234abcd</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Project1</value>
      </item>
      <item>
         <resourceId>vol-7f7g7d7a</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamC</value>
      </item>
      <item>
         <resourceId>vol-7f7g7d7a</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Project2</value>
      </item>
      <item>
         <resourceId>vol-4a4b4c4d</resourceId>
         <resourceType>volume</resourceType>
         <key>Owner</key>
         <value>TeamC</value>
      </item>
      <item>
         <resourceId>vol-4a4b4c4d</resourceId>
         <resourceType>volume</resourceType>
         <key>Purpose</key>
         <value>Logs</value>
      </item>
  </tagSet>
</DescribeTagsResponse>

Likewise, you can get volume descriptions, and filter the results by tag. The filter name you use is tag:key. Let's say you want to get a list of just the volumes belonging to either TeamA or TeamB, and that contain log data. This time you use DescribeVolumes with a filter based on the tags of interest. You use a wildcard to find the volumes with "Log" in the Purpose tag's value.

Example Query request:

https://ec2.amazonaws.com/?Action=DescribeVolumes
&Filter.1.Name=tag:Owner
&Filter.1.Value.1=TeamA
&Filter.1.Value.2=TeamB
&Filter.2.Name=tag:Purpose
&Filter.2.Value.1=*Log*
&AuthParams

Because of the filtering, the response includes only two of the volumes that were in the preceding list of tagged volumes. The volume's tags are included in the response.

<DescribeVolumesResponse xmlns="http://ec2.amazonaws.com/doc/2012-04-01/">
   <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
   <volumeSet>
      <item>
         <volumeId>vol-4562dabf</volumeId>
         <size>5</size>
         <snapshotId/>
         <availabilityZone>us-east-1b</availabilityZone>
         <status>available</status>
         <createTime>2010-02-22T22:50:43+0000</createTime>
         <attachmentSet/>
         <tagSet>
            <item>
               <key>Owner</key>
               <value>TeamA</key>
            </item>
            <item>
               <key>Purpose</key>
               <value>RawLogData</key>
            </item>
         </tagSet>
      </item>
      <item>
         <volumeId>vol-3b3a4c4d</volumeId>
         <size>12</size>
         <snapshotId/>
         <availabilityZone>us-east-1b</availabilityZone>
         <status>available</status>
         <createTime>2010-05-01T13:09:27+0000</createTime>
         <attachmentSet/>
         <tagSet>
            <item>
               <key>Owner</key>
               <value>TeamB</key>
            </item>
             <item>
               <key>Purpose</key>
               <value>Logs</key>
            </item>
         </tagSet>
      </item>
    </volumeSet>
</DescribeVolumesResponse>

Document Conventions
Terms of Use

Did this page help you? Yes No Tell us about it...