This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and will now receive only critical bug fixes and security patches. New features will be developed for CDK v2 exclusively. Support for CDK v1 will end entirely on June 1, 2023.
Tagging
Tags are informational key-value elements that you can add to constructs in your AWS CDK app. A tag applied to a given construct also applies to all of its taggable children. Tags are included in the AWS CloudFormation template synthesized from your app and are applied to the AWS resources it deploys. You can use tags to identify and categorize resources for the following purposes:
-
Simplifying management
-
Cost allocation
-
Access control
-
Any other purposes that you devise
Tip
For more information about how you can use tags with your AWS resources, see the
whitepaper Tagging Best Practices
The Tags
class includes the static method of()
, through which
you can add tags to, or remove tags from, the specified construct.
-
Tags.of(
applies a new tag to the given construct and all of its children.SCOPE
).add() -
Tags.of(
removes a tag from the given construct and any of its children, including tags a child construct may have applied to itself.SCOPE
).remove()
Note
Tagging is implemented using Aspects. Aspects are a way to apply an operation (such as tagging) to all constructs in a given scope.
The following example applies the tag key with the value value to a construct.
The following example deletes the tag key from a construct.
If you are using Stage
constructs, apply the tag at the Stage
level or below. Tags are not applied across Stage
boundaries.
Tag priorities
The AWS CDK applies and removes tags recursively. If there are conflicts, the tagging
operation with the highest priority wins. (Priorities are set using the optional
priority
property.) If the priorities of two operations are the same, the
tagging operation closest to the bottom of the construct tree wins. By default, applying a tag
has a priority of 100 (except for tags added directly to an AWS CloudFormation resource, which has a
priority of 50). The default priority for removing a tag is 200.
The following applies a tag with a priority of 300 to a construct.
Optional properties
Tags support properties
that fine-tune how tags are applied to, or removed from,
resources. All properties are optional.
applyToLaunchedInstances
(Python:apply_to_launched_instances
)-
Available for add() only. By default, tags are applied to instances launched in an Auto Scaling group. Set this property to false to ignore instances launched in an Auto Scaling group.
includeResourceTypes
/excludeResourceTypes
(Python:include_resource_types
/exclude_resource_types
)-
Use these to manipulate tags only on a subset of resources, based on AWS CloudFormation resource types. By default, the operation is applied to all resources in the construct subtree, but this can be changed by including or excluding certain resource types. Exclude takes precedence over include, if both are specified.
priority
-
Use this to set the priority of this operation with respect to other
Tags.add()
andTags.remove()
operations. Higher values take precedence over lower values. The default is 100 for add operations (50 for tags applied directly to AWS CloudFormation resources) and 200 for remove operations.
The following example applies the tag tagname with the value value and priority 100 to resources of type AWS::Xxx::Yyy in the construct. It doesn't apply the tag to instances launched in an Amazon EC2 Auto Scaling group or to resources of type AWS::Xxx::Zzz. (These are placeholders for two arbitrary but different AWS CloudFormation resource types.)
The following example removes the tag tagname with priority 200 from resources of type AWS::Xxx::Yyy in the construct, but not from resources of type AWS::Xxx::Zzz.
Example
The following example adds the tag key StackType with
value TheBest to any resource created within the
Stack
named MarketingSystem
. Then it removes it again from all
resources except Amazon EC2 VPC subnets. The result is that only the subnets have the tag
applied.
The following code achieves the same result. Consider which approach (inclusion or exclusion) makes your intent clearer.
Tagging single constructs
Tags.of(scope).add(key, value)
is the standard way to add tags to constructs
in the AWS CDK. Its tree-walking behavior, which recursively tags all taggable resources under
the given scope, is almost always what you want. Sometimes, however, you need to tag a
specific, arbitrary construct (or constructs).
One such case involves applying tags whose value is derived from some property of the construct being tagged. The standard tagging approach recursively applies the same key and value to all matching resources in the scope. However, here the value could be different for each tagged construct.
Tags are implemented using aspects, and the CDK
calls the tag's visit()
method for each construct under the scope you specified
using Tags.of(scope)
. We can call Tag.visit()
directly to apply a
tag to a single construct.
You can tag all constructs under a scope but let the values of the tags derive from
properties of each construct. To do so, write an aspect and apply the tag in the aspect's
visit()
method as shown in the preceding example. Then, add the aspect to the
desired scope using Aspects.of(scope).add(aspect)
.
The following example applies a tag to each resource in a stack containing the resource's path.
Tip
The logic of conditional tagging, including priorities, resource types, and so on, is
built into the Tag
class. You can use these features when applying tags to
arbitrary resources; the tag is not applied if the conditions aren't met. Also, the
Tag
class only tags taggable resources, so you don't need to test whether a
construct is taggable before applying a tag.