Tagging in AWS CDK

Tags are key/value metadata that enable users to categorize their AWS infrastructure. This is useful for identifying groups of resources, monitoring cloud spending, creating reports, etc.

In this post, we’ll explore different methods for tagging infrastructure using the AWS CDK. The code samples are in Python, but the techniques are applicable to all languages.

Tagging constructs

Constructs are the basic “building blocks” of the AWS CDK. They act as components and encapsulate necessary information for CloudFormation. Fortunately, the AWS CDK provides an easy-to-use API.

The standard method for tagging resources is:

1Tags.of(construct).add("key", "value")

Tag resources in AWS CDK

As shown above, tagging an individual resource is easy.

 1from aws_cdk import App, Stack, Tags
 2from aws_cdk import aws_iam as iam
 3
 4
 5class MyStack(Stack):
 6    def __init__(self, scope: App, construct_id: str, **kwargs) -> None:
 7        super().__init__(scope, construct_id, **kwargs)
 8
 9        my_role = iam.Role(self, "role", assumed_by=iam.AnyPrincipal())
10        Tags.of(my_role).add("owner", "team@example.com")

A tag with “owner” and “team@example.com” was added to the role construct.

Tag stacks in AWS CDK

Tagging a stack will apply tags to the stack construct and all resources within it.

 1from aws_cdk import App, Tags
 2
 3from stack import MyStack
 4
 5app = App()
 6my_stack = MyStack(app, "Stack")
 7
 8Tags.of(my_stack).add("owner", "team@example.com")
 9
10app.synth()

A tag with “owner” and “team@example.com” was added to the stack construct and all constructs within the stack.

Tag apps using AWS CDK

Like the previous example, tagging an app will auto tag the sub-constructs as well.

 1from aws_cdk import App, Tags
 2
 3from stack import MyStack
 4
 5app = App()
 6my_stack = MyStack(app, "Stack")
 7
 8Tags.of(app).add("owner", "team@example.com")
 9
10app.synth()

A tag with “owner” and “team@example.com” was added to the app construct and all constructs within the app.

Tag stacks using AWS CDK CLI

If you prefer specifying a tag at cdk deploy time, the --tags flag is available:

1cdk deploy Stack \
2    --tags owner=team@example.com \
3    --tags department=engineering

With the command above, two tags were applied to a stack named Stack.

Tag stacks using AWS CDK cdk.json file

An alternative to the command line flag is using the cdk.json file to specify deploy time tags.

Simply add the tags key to your cdk.json file with your tags defined in an array:

 1{
 2  "app": "python3 app.py",
 3  "tags": [
 4    {
 5      "Key": "owner",
 6      "Value": "team@example.com"
 7    },
 8    {
 9      "Key": "department",
10      "Value": "engineering"
11    }
12  ]
13}

Duplicate tags in AWS CDK

Occasionally, there may be duplicate tags applied to the same resource.

To control which tags overwrite others, a priority parameter can be supplied to the add method. By default, all tags applied have a 100 priority.

 1from aws_cdk import App, Tags
 2
 3from stack import MyStack
 4
 5app = App()
 6my_stack = MyStack(app, "Stack")
 7
 8Tags.of(my_stack).add("owner", "team2@example.com", priority=101)
 9Tags.of(my_stack).add("owner", "team@example.com")
10
11app.synth()

If both stacks have a priority of 100 – the bottom-most tag on the construct tree wins. In this case, the 101 priority superseded the bottom-most call.