Amazon Relational Database Service
User Guide (API Version 2014-09-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

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

  • Read replicas

  • DB snapshots

  • Reserved DB instances

  • Event subscriptions

  • DB option groups

  • DB parameter groups

  • DB security groups

  • DB subnet groups

For information on managing access to tagged resources with IAM policies, see Using AWS Identity and Access Management (IAM) to Manage Access to Amazon RDS Resources.

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. AWS does not automatically set any tags on Amazon RDS resources.

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:" or "rds:". 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 an Amazon RDS Amazon Resource Name (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.

AWS Management Console

The process to tag an Amazon RDS resource is similar for all resources. The following example 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, 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 check box for the DB instance that you want to tag.

  4. Click the details icon.

    Console Tags edit db

  5. In the details pane, scroll down to Tags.

    Console Tag

  6. Click Add/Edit Tags.

    Console Tags edit db

  7. Type a name and value for the tag. Click 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 check box for the DB instance from which you want to remove a tag.

  4. Click the details icon.

    Console Tags edit db
  5. In the details pane, scroll down to Tags.

    Console Tag

  6. Click the red "X" in the Remove column next to the tag you want to delete.

    Console Tag

  7. Click the Save Tags button.

CLI

To add, list, or remove tags for a DB instance

To learn more about how to construct the required ARN, see Constructing an Amazon RDS Amazon Resource Name (ARN)

API

To add, list, or remove tags for a DB instance

To learn more about how to construct the required ARN, see Constructing an Amazon RDS Amazon Resource Name (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.

Constructing an Amazon RDS Amazon Resource Name (ARN)

Resources that are created in Amazon Web Services are identified by a unique identifier call an Amazon Resource Name (ARN). If you use the CLI or Amazon RDS API to add, modify, or delete tags, you must supply the ARN of the resource you want to work with.

An ARN for an Amazon RDS resource uses the following syntax:

arn:aws:rds:<region>:<account number>:<resourcetype>:<name>

  • <region> is the AWS region ID where the Amazon RDS resource was created, such as us-west-2.

    The following table shows AWS region names and the value you should use when constructing an ARN.

    RegionNameEndpoint
    US East (N. Virginia) regionus-east-1https://rds.us-east-1.amazonaws.com
    US West (N. California) regionus-west-1https://rds.us-west-1.amazonaws.com
    US West (Oregon) regionus-west-2https://rds.us-west-2.amazonaws.com
    EU (Ireland) regioneu-west-1https://rds.eu-west-1.amazonaws.com
    EU (Frankfurt) Regioneu-central-1https://rds.eu-central-1.amazonaws.com
    Asia Pacific (Tokyo) Regionap-northeast-1https://rds.ap-northeast-1.amazonaws.com
    Asia Pacific (Singapore) Regionap-southeast-1https://rds.ap-southeast-1.amazonaws.com
    Asia Pacific (Sydney) Regionap-southeast-2https://rds.ap-southeast-2.amazonaws.com
    South America (Sao Paulo) Regionsa-east-1https://rds.sa-east-1.amazonaws.com
    AWS GovCloud (US) Regionus-gov-west-1https://rds.us-gov-west-1.amazonaws.com

  • <account number> is your account number with dashes omitted. To find your account number, log into your AWS account at http://aws.amazon.com, click My Account/Console, and then click My Account.

  • <resourcetype> is the type of Amazon RDS resource.

    The following table shows the resource type you should use when constructing an ARN for a particular Amazon RDS resource.

    Resource TypeARN Format
    DB instance arn:aws:rds:<region>:<account>:db:<dbinstance name>
    Event subscription arn:aws:rds:<region>:<account>:es:<subscription name>
    DB option group arn:aws:rds:<region>:<account>:og:<option group name>
    DB parameter group arn:aws:rds:<region>:<account>:pg:<parameter group name>
    Reserved DB instance arn:aws:rds:<region>:<account>:ri:<reserve instance name>
    DB security group arn:aws:rds:<region>:<account>:secgrp:<security group name>
    DB snapshot arn:aws:rds:<region>:<account>:snapshot:<snapshot name>
    DB subnet group arn:aws:rds:<region>:<account>:subgrp:<subnet group name>
  • <name> is the resource identifier for the Amazon RDS resource.

The following table shows examples of ARNs for RDS resources with an AWS account of 123456789012, that were created in the US East (Northern Virginia) region, and that have a resource name that begins with "my-":

Resource TypeSample ARN
DB instance arn:aws:rds:us-east-1:123456789012:db:my-mysql-instance
Event subscription arn:aws:rds:us-east-1:123456789012:es:my-subscription
DB option group arn:aws:rds:us-east-1:123456789012:og:my-option-group-oracle-tde
DB parameter group arn:aws:rds:us-east-1:123456789012:pg:my-param-enable-logs
Reserved DB instance arn:aws:rds:us-east-1:123456789012:ri:my-reserved-multiaz
DB security group arn:aws:rds:us-east-1:123456789012:secgrp:my-public
DB snapshot arn:aws:rds:us-east-1:123456789012:snapshot:my-mysql-snap-20130507
DB subnet group arn:aws:rds:us-east-1:123456789012:subgrp:my-subnet-10