Sign In to the Console
AWS Cloud Development Kit (AWS CDK)
Developer Guide

AWS Documentation » AWS Cloud Development Kit » Developer Guide » Concepts » Tagging

Tagging

The Tag class includes two methods that you can use to create and delete tags:

  • Tag.add() applies a new tag to a construct and all of its children.

  • Tag.remove() removes a tag from a construct and any of its children, including tags a child construct may have applied to itself.

Note

Tagging is implemented using Aspects. Aspects are a way to apply an operation (such as tagging) to all constructs in a given scope.

Let's look at a couple of examples. The following example applies the tag key with the value value to a construct.

TypeScriptPython
TypeScript
Tag.add(myConstruct, 'key', 'value');
Python
Tag.add(my_construct, "key", "value")

The following example deletes the tag key from a construct.

TypeScriptPython
TypeScript
Tag.remove(my_construct, 'key');
Python
Tag.remove(my_construct, "key")

The AWS CDK applies and removes tags recursively. If there are conflicts, the tagging operation with the highest priority wins. If the priorities 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 and removing a tag has a priority of 200. To change the priority of applying a tag, pass a priority property to Tag.add() or Tag.remove().

The following applies a tag with a priority of 300 to a construct.

TypeScriptPython
TypeScript
Tag.add(myConstruct, 'key', 'value', {
  priority: 300
});
Python
Tag.add(my_construct, "key", "value", priority=300)

Tag.add()

Tag.add() supports properties that fine-tune how tags are applied to resources. All properties are optional.

The following example applies the tag tagname with the value value and priority 100 to resources of type AWS::Xxx::Yzz in the construct, but not to instances launched in an Amazon EC2 Auto Scaling group or to resources of type AWS::Xxx::Zss.

TypeScriptPython
TypeScript
Tag.add(myConstruct, 'tagname', 'value', {
  applyToLaunchedInstances: false,
  includeResourceTypes: ['AWS::Xxx::Yyy'],
  excludeResourceTypes: ['AWS::Xxx::Zzz'],
  priority: 100,
});
Python
Tag.add(my_construct, "tagname", "value",
    apply_to_launched_instances=False,
    include_resource_types=["AWS::Xxx::Yyy"],
    exclude_resource_types=["AWS::Xxx::Zzz"],
    priority=100,)

These properties have the following meanings.

applyToLaunchedInstances (Python: apply_to_launched_instances)

By default, tags are applied to instances launched in an Auto Scaling group. Set this property to false to not apply tags to instances launched in an Auto Scaling group.

includeResourceTypes/excludeResourceTypes (Python: include_resource_types, exclude_resource_types)

Use these to apply tags only to a subset of resources, based on AWS CloudFormation resource types. By default, the tag 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 Tag.add() and Tag.remove() operations. Higher values take precedence over lower values. The default is 100.

Tag.remove()

Tag.remove() supports properties to fine-tune how tags are removed from resources. All properties are optional.

The following example removes the tag tagname with priority 200 from resources of type AWS::Xxx::Yzz in the construct, but not from resources of type AWS::Xxx::Zzz.

TypeScriptPython
TypeScript
Tag.remove(myConstruct, 'tagname', {
  includeResourceTypes: ['AWS::Xxx::Yyy'],
  excludeResourceTypes: ['AWS::Xxx::Zzz'],
  priority: 200,
});
Python
Tag.remove(my_construct, "tagname",
    include_resource_types=["AWS::Xxx::Yyy"],
    exclude_resource_types=["AWS::Xxx::Zzz"],
    priority=200,)

These properties have the following meanings.

includeResourceTypes/excludeResourceTypes

(Python: include_resource_types/exclude_resource_types) Use these properties to remove tags only from subset of resources based on AWS CloudFormation resource types. By default, the tag is removed from 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 property to specify the priority of this operation with respect to other Tag.add() and Tag.remove() operations. Higher values take precedence over lower values. The default is 200.

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.

TypeScriptPython
TypeScript
import { App, Stack, Tag } from require('@aws-cdk/core');

const app = new App();
const theBestStack = new Stack(app, 'MarketingSystem');

// Add a tag to all constructs in the stack
Tag.add(theBestStack, 'StackType', 'TheBest');

// Remove the tag from all resources except subnet resources
Tag.remove(theBestStack, 'StackType', {
  excludeResourceTypes: ['AWS::EC2::Subnet']
});
Python
from aws_cdk.core import App, Stack, Tag

app = App();
the_best_stack = Stack(app, 'MarketingSystem')

# Add a tag to all constructs in the stack
Tag.add(the_best_stack, "StackType", "TheBest")

# Remove the tag from all resources except subnet resources
Tag.remove(the_best_stack, "StackType", 
    exclude_resource_types=["AWS::EC2::Subnet"])

Note

The following code achieves the same result. Consider which approach (inclusion or exclusion) makes your intent clearer.

TypeScriptPython
TypeScript
Tag.add(theBestStack, 'StackType', 'TheBest', 
  { includeResourceTypes: ['AWS::EC2::Subnet']});
Python
Tag.add(the_best_stack, "StackType", "TheBest", 
    include_resource_types=["AWS::EC2::Subnet"])