Menu
Amazon Relational Database Service
User Guide (API Version 2014-10-31)

Tagging Amazon RDS Resources

What You Should Know About Amazon RDS Resource Tags

You can use Amazon RDS tags to add metadata to your Amazon RDS resources. In addition, these tags can be used with IAM policies to manage access to Amazon RDS resources and to control what actions can be applied to the Amazon RDS resources. Finally, these tags can be used to track costs by grouping expenses for similarly tagged resources.

All Amazon RDS resources can be tagged:

  • DB instances

  • DB clusters

  • Read replicas

  • DB snapshots

  • DB cluster snapshots

  • Reserved DB instances

  • Event subscriptions

  • DB option groups

  • DB parameter groups

  • DB cluster parameter groups

  • DB security groups

  • DB subnet groups

For information on managing access to tagged resources with IAM policies, see Authentication and Access Control for Amazon RDS.

An Amazon RDS tag is a name-value pair that you define and associate with an Amazon RDS resource. The name is referred to as the key. Supplying a value for the key is optional. You can use tags to assign arbitrary information to an Amazon RDS resource. A tag key could be used, for example, to define a category, and the tag value could be a item in that category. For example, you could define a tag key of “project” and a tag value of “Salix,” indicating that the Amazon RDS resource is assigned to the Salix project. You could also use tags to designate Amazon RDS resources as being used for test or production by using a key such as environment=test or environment =production. We recommend that you use a consistent set of tag keys to make it easier to track metadata associated with Amazon RDS resources.

Use tags to organize your AWS bill to reflect your own cost structure. To do this, sign up to get your AWS account bill with tag key values included. Then, to see the cost of combined resources, organize your billing information according to resources with 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 Cost Allocation and Tagging in About AWS Billing and Cost Management.

Each Amazon RDS resource has a tag set, which contains all the tags that are assigned to that Amazon RDS resource. A tag set can contain as many as ten tags, or it can be empty. If you add a tag to an Amazon RDS resource that has the same key as an existing tag on resource, the new value overwrites the old value.

AWS does not apply any semantic meaning to your tags; tags are interpreted strictly as character strings. Amazon RDS may set tags on a DB instance or other Amazon RDS resources, depending on the settings that you use when you create the resource. For example, Amazon RDS may add a tag indicating that a DB instance is for production or for testing.

The following list describes the characteristics of a DB instance tag.

  • The tag key is the required name of the tag. The string value can be from 1 to 128 Unicode characters in length and cannot be prefixed with "aws:" or "rds:". The string may contain only the set of Unicode letters, digits, white-space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$").

  • The tag value is an optional string value of the tag. The string value can be from 1 to 256 Unicode characters in length and cannot be prefixed with "aws:". The string may contain only the set of Unicode letters, digits, white-space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$").

    Values do not have to be unique in a tag set and can be null. For example, you can have a key-value pair in a tag set of project/Trinity and cost-center/Trinity.

You can use the AWS Management Console, the command line interface, or the Amazon RDS API to add, list, and delete tags on Amazon RDS resources. When using the command line interface or the Amazon RDS API, you must provide the Amazon Resource Name (ARN) for the Amazon RDS resource you want to work with. For more information about constructing an ARN, see Constructing a New Amazon RDS ARN.

Note that tags are cached for authorization purposes. Because of this, additions and updates to tags on Amazon RDS resources may take several minutes before they are available.

Copying Tags

When you create or restore a DB instance, you can specify that the tags from the DB instance are copied to snapshots of the DB instance. Copying tags ensures that the metadata for the DB snapshots matches that of the source DB instance and any access policies for the DB snapshot also match those of the source DB instance. Tags are not copied by default.

You can specify that tags are copied to DB snapshots for the following actions:

  • Creating a DB instance.

  • Restoring a DB instance.

  • Creating a Read Replica.

  • Copying a DB snapshot.

Note

If you include a value for the --tag-key parameter of the create-db-snapshot AWS CLI command (or supply at least one tag to the CreateDBSnapshot API action) then RDS will not copy tags from the source DB instance to the new DB snapshot. This functionality applies even if the source DB instance has the --copy-tags-to-snapshot (CopyTagsToSnapshot) option enabled. If you take this approach, you can create a copy of a DB instance from a DB snapshot without adding tags that don't apply to the new DB instance. Once you have created your DB snapshot using the AWS CLI create-db-snapshot command (or the CreateDBSnapshot Amazon RDS API action) you can then add tags as described later in this topic.

AWS Management Console

The process to tag an Amazon RDS resource is similar for all resources. The following procedure shows how to tag an Amazon RDS DB instance.

To add a tag to a DB instance

  1. Sign in to the AWS Management Console and open the Amazon RDS console at https://console.aws.amazon.com/rds/.

  2. In the navigation pane, choose Instances.

    Note

    To filter the list of DB instances in the DB Instances pane, in the box beside the Viewing box, type a text string. Only DB instances that contain the string will appear.

  3. Select the DB instance that you want to tag. The inline summary appears.

  4. In the inline summary, choose the details icon to open the details section.

    Console details icon
  5. In the details section, scroll down and choose Tags to open the tags section.

  6. Choose Add/Edit Tags. The Tag DB Instance pane appears.

    Console Tag DB Instance pane
  7. Choose Add another Tag.

  8. Type a key and value for the tag, and then choose Save Tags.

To delete a tag from a DB instance

  1. Sign in to the AWS Management Console and open the Amazon RDS console at https://console.aws.amazon.com/rds/.

  2. In the navigation pane, click Instances.

    Note

    To filter the list of DB instances in the DB Instances pane, in the box beside the Viewing box, type a text string. Only DB instances that contain the string will appear.

  3. Select the DB instance from which you want to remove a tag. The inline summary appears.

  4. In the inline summary, choose the details icon to open the details section.

    Console details icon
  5. In the details section, scroll down and choose Tags to open the tags section.

  6. Choose Add/Edit Tags. The Tag DB Instance pane appears.

    Console Tag DB Instance pane
  7. Choose the red "X" in the Remove column next to the tag you want to delete, and then choose Save Tags.

CLI

You can add, list, or remove tags for a DB instance using the AWS CLI.

To learn more about how to construct the required ARN, see Constructing a New Amazon RDS ARN.

API

You can add, list, or remove tags for a DB instance using the Amazon RDS API.

To learn more about how to construct the required ARN, see Constructing a New Amazon RDS ARN.

When working with XML using the Amazon RDS API, tags use the following schema:

<Tagging>
  <TagSet>
  	<Tag>
  		<Key>Project</Key>
  		<Value>Trinity</Value>
  	</Tag>
  	<Tag>
  		<Key>User</Key>
  		<Value>Jones</Value>
  	</Tag>
  </TagSet>
</Tagging> 

The following table provides a list of the allowed XML tags and their characteristics. Note that values for Key and Value are case dependent. For example, project=Trinity and PROJECT=Trinity are two distinct tags.

Tagging elementDescription
TagSetA tag set is a container for all tags assigned to an Amazon RDS resource. There can be only one tag set per resource. You work with a TagSet only through the Amazon RDS API.
TagA tag is a user-defined key-value pair. There can be from 1 to 10 tags in a tag set.
Key

A key is the required name of the tag. The string value can be from 1 to 128 Unicode characters in length and cannot be prefixed with "rds:" or "aws:". The string may only contain only the set of Unicode letters, digits, white-space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$").

Keys must be unique to a tag set. For example, you cannot have a key-pair in a tag set with the key the same but with different values, such as project/Trinity and project/Xanadu.

Value

A value is the optional value of the tag. The string value can be from 1 to 256 Unicode characters in length and cannot be prefixed with "rds:" or "aws:". The string may only contain only the set of Unicode letters, digits, white-space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$").

Values do not have to be unique in a tag set and can be null. For example, you can have a key-value pair in a tag set of project/Trinity and cost-center/Trinity.