Constructs¶
Constructs are the building blocks of AWS CDK applications. Constructs can have child constructs, which in turn can have child constructs, forming a hierarchical tree structure.
The AWS CDK includes two different levels of constructs:
CloudFormation Resource
These constructs are low-level constructs that provide a direct, one-to-one, mapping to an AWS CloudFormation resource, as listed in the AWS CloudFormation topic AWS Resource Types Reference.
All CloudFormation Resource members are found in the
@aws-cdk/resources
package.
AWS Construct Library
These constructs have been handwritten by AWS and come with convenient defaults and additional knowledge about the inner workings of the AWS resources they represent. In general, you will be able to express your intent without worrying about the details too much, and the correct resources will automatically be defined for you.
AWS Construct Library members are found in the
@aws-cdk/NAMESPACE
packages, where NAMESPACE is the short name for the associated service, such as SQS for the AWS Construct Library for the Amazon SQS service. See the Packages section for descriptions of the AWS CDK packages and constructs.
Construct Structure¶
The construct tree structure is a powerful design pattern for composing high-level
abstractions. For example, you can define a StorageLayer
construct that
represents your application’s storage layer and include all the AWS resources,
such as DynamoDB tables and Amazon S3 buckets, needed to implement your storage layer in
this construct. When your higher-level code uses this construct, it only needs
to instantiate the StorageLayer
construct.
When you initialize a construct, add the construct to the construct tree by specifying the parent construct as the first initializer parameter, an identifier for the construct as the second parameter, and an set of properties for the final parameter, as shown in the following example.
new SomeConstruct(parent, name[, props]);
In almost all cases, you should pass the keyword this
for the parent
argument, because you will generally initialize new constructs in the context of
the parent construct. Any descriptive string will do for the name
argument,
and an in-line object for the set of properties.
new BeautifulConstruct(this, 'Foo', {
applicationName: 'myApp',
timeout: 300
});
Note
Associating the construct to its parent as part of initialization is necessary because the construct occasionally needs contextual information from its parent, such as to which the region the stack is deployed.
Use the following operations to inspect the construct tree.
aws-cdk.Construct.parent
- Gets the construct’s parent construct.
aws-cdk.Construct.getChildren()
- Gets an array of all of the contruct’s children.
aws-cdk.Construct.getChild()
- Gets the child construct with the specified ID.
aws-cdk.Construct.toTreeString()
Gets a string representing the construct’s tree.
Construct Names¶
Every construct in a CDK app must have a name unique among its siblings. Names are used to track constructs in the construct hierarchy, and to allocate logical IDs so that AWS CloudFormation can keep track of the generated resources.
When a construct is created, its name is specified as the second initializer argument:
const c1 = new MyBeautifulConstruct(this, 'OneBeautiful');
const c2 = new MyBeautifulConstruct(this, 'TwoBeautiful');
assert(c1.name === 'OneBeautiful');
assert(c2.name === 'TwoBeautiful');
Use the aws-cdk.Construct.path
property to get the path of this
construct from the root of the tree.
Note that the name of a construct does not directly map onto the physical name
of the resource when it is created! If you want to give a physical name to a bucket or table,
specify the physical name using use the appropriate
property, such as bucketName
or tableName
. Example:
new Bucket(this, 'MyBucket', {
bucketName: 'physical-bucket-name'
});
Avoid specifying physical names. Instead, let AWS CloudFormation generate names for you. Use attributes, such as bucket.bucketName, to discover the generated names.
When you synthesize an AWS CDK tree into an AWS CloudFormation template, the AWS CloudFormation logical ID for each resource in the template is allocated according to the path of that resource in the construct tree. For more information, see Logical IDs.
Construct Properties¶
Customize constructs by passing a property object as the third parameter (props). Every construct has its own set of parameters, defined as an interface. You can pass a property object to your construct in two ways:
// Inline (recommended)
new Queue(this, 'MyQueue', {
visibilityTimeout: 300
});
// Instantiate separate property object
const props: QueueProps = {
visibilityTimeout: 300
};
new Queue(this, 'MyQueue', props);
Construct Metadata¶
You can attach metadata to a construct using the
aws-cdk.Construct.addMetadata()
operation. Metadata entries
automatically include the stack trace from which the metadata entry was added.
Therefore, at any level of a construct you can find the code location, even if metadata
was created by a lower-level library that you don’t own.