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.
Identifiers
The AWS CDK deals with many types of identifiers and names. To use the AWS CDK effectively and avoid errors, you need to understand the types of identifiers.
Identifiers must be unique within the scope in which they are created; they do not need to be globally unique in your AWS CDK application.
If you attempt to create an identifier with the same value within the same scope, the AWS CDK throws an exception.
Construct IDs
The most common identifier, id
, is the identifier passed as the second
argument when instantiating a construct object. This identifier, like all identifiers, only
needs to be unique within the scope in which it is created, which is the first argument when
instantiating a construct object.
Note
The id
of a stack is also the identifier that you use to refer to it in the
AWS CDK Toolkit (cdk command).
Let's look at an example where we have two constructs with the identifier
MyBucket
in our app. The first is defined in the scope of the stack with the
identifier Stack1
. The second is defined in the scope of a stack with the
identifier Stack2
. Because they're defined in different scopes, this doesn't
cause any conflict, and they can coexist in the same app without issues.
Paths
The constructs in an AWS CDK application form a hierarchy rooted in the App
class. We refer to the collection of IDs from a given construct, its parent construct, its
grandparent, and so on to the root of the construct tree, as a
path.
The AWS CDK typically displays paths in your templates as a string. The IDs from the levels
are separated by slashes, starting at the node immediately under the root App
instance, which is usually a stack. For example, the paths of the two Amazon S3 bucket resources in
the previous code example are Stack1/MyBucket
and
Stack2/MyBucket
.
You can access the path of any construct programmatically, as shown in the following
example. This gets the path of myConstruct
(or my_construct
, as
Python developers would write it). Since IDs must be unique within the scope they are created,
their paths are always unique within an AWS CDK application.
Unique IDs
AWS CloudFormation requires that all logical IDs in a template be unique. Because of this, the AWS CDK
must be able to generate a unique identifier for each construct in an application. Resources
have paths that are globally unique (the names of all scopes from the stack to a specific
resource). Therefore, the AWS CDK generates the necessary unique identifiers by concatenating
the elements of the path and adding an 8-digit hash. (The hash is necessary to distinguish
distinct paths, such as A/B/C
and A/BC
, that would result in the
same AWS CloudFormation identifier. AWS CloudFormation identifiers are alphanumeric and cannot contain slashes or other
separator characters.) The AWS CDK calls this string the unique ID of the
construct.
In general, your AWS CDK app should not need to know about unique IDs. You can, however, access the unique ID of any construct programmatically, as shown in the following example.
The address is another kind of unique identifier that uniquely distinguishes CDK resources. Derived from the SHA-1 hash of the path, it is not human-readable. However, its constant, relatively short length (always 42 hexadecimal characters) makes it useful in situations where the "traditional" unique ID might be too long. Some constructs may use the address in the synthesized AWS CloudFormation template instead of the unique ID. Again, your app generally should not need to know about its constructs' addresses, but you can retrieve a construct's address as follows.
Logical IDs
Unique IDs serve as the logical identifiers (or logical names) of resources in the generated AWS CloudFormation templates for constructs that represent AWS resources.
For example, the Amazon S3 bucket in the previous example that is created within
Stack2
results in an AWS::S3::Bucket
resource. The resource's
logical ID is Stack2MyBucket4DD88B4F
in the resulting AWS CloudFormation template. (For
details on how this identifier is generated, see Unique IDs.)
Logical ID stability
Avoid changing the logical ID of a resource after it has been created. AWS CloudFormation identifies resources by their logical ID. Therefore, if you change the logical ID of a resource, AWS CloudFormation creates a new resource with the new logical ID, then deletes the existing one. Depending on the type of resource, this might cause service interruption, data loss, or both.