AWS Cloud Development Kit Library

The AWS CDK construct library provides APIs to define your CDK application and add CDK constructs to the application.

Usage

Upgrade from CDK 1.x

When upgrading from CDK 1.x, remove all dependencies to individual CDK packages from your dependencies file and follow the rest of the sections.

Installation

To use this package, you need to declare this package and the constructs package as dependencies.

According to the kind of project you are developing:

For projects that are CDK libraries in NPM, declare them both under the devDependencies and peerDependencies sections. To make sure your library is compatible with the widest range of CDK versions: pick the minimum aws-cdk-lib version that your library requires; declare a range dependency with a caret on that version in peerDependencies, and declare a point version dependency on that version in devDependencies.

For example, let's say the minimum version your library needs is 2.38.0. Your package.json should look like this:

{
  "peerDependencies": {
    "aws-cdk-lib": "^2.38.0",
    "constructs": "^10.5.0"
  },
  "devDependencies": {
    /* Install the oldest version for testing so we don't accidentally use features from a newer version than we declare */
    "aws-cdk-lib": "2.38.0"
  }
}

For CDK apps, declare them under the dependencies section. Use a caret so you always get the latest version:

{
  "dependencies": {
    "aws-cdk-lib": "^2.38.0",
    "constructs": "^10.5.0"
  }
}

Use in your code

Classic import

You can use a classic import to get access to each service namespaces:

from aws_cdk import Stack, App, aws_s3 as s3

app = App()
stack = Stack(app, "TestStack")

s3.Bucket(stack, "TestBucket")

Barrel import

Alternatively, you can use "barrel" imports:

from aws_cdk import App, Stack
from aws_cdk.aws_s3 import Bucket

app = App()
stack = Stack(app, "TestStack")

Bucket(stack, "TestBucket")

Stacks and Stages

A Stack is the smallest physical unit of deployment, and maps directly onto a CloudFormation Stack. You define a Stack by defining a subclass of Stack -- let's call it MyStack -- and instantiating the constructs that make up your application in MyStack's constructor. You then instantiate this stack one or more times to define different instances of your application. For example, you can instantiate it once using few and cheap EC2 instances for testing, and once again using more and bigger EC2 instances for production.

When your application grows, you may decide that it makes more sense to split it out across multiple Stack classes. This can happen for a number of reasons:

You could be starting to reach the maximum number of resources allowed in a single stack (this is currently 500).
You could decide you want to separate out stateful resources and stateless resources into separate stacks, so that it becomes easy to tear down and recreate the stacks that don't have stateful resources.
There could be a single stack with resources (like a VPC) that are shared between multiple instances of other stacks containing your applications.

As soon as your conceptual application starts to encompass multiple stacks, it is convenient to wrap them in another construct that represents your logical application. You can then treat that new unit the same way you used to be able to treat a single stack: by instantiating it multiple times for different instances of your application.

You can define a custom subclass of Stage, holding one or more Stacks, to represent a single logical instance of your application.

As a final note: Stacks are not a unit of reuse. They describe physical deployment layouts, and as such are best left to application builders to organize their deployments with. If you want to vend a reusable construct, define it as a subclasses of Construct: the consumers of your construct will decide where to place it in their own stacks.

Stack Synthesizers

Each Stack has a synthesizer, an object that determines how and where the Stack should be synthesized and deployed. The synthesizer controls aspects like:

How does the stack reference assets? (Either through CloudFormation parameters the CLI supplies, or because the Stack knows a predefined location where assets will be uploaded).
What roles are used to deploy the stack? These can be bootstrapped roles, roles created in some other way, or just the CLI's current credentials.

The following synthesizers are available:

DefaultStackSynthesizer: recommended. Uses predefined asset locations and roles created by the modern bootstrap template. Access control is done by controlling who can assume the deploy role. This is the default stack synthesizer in CDKv2.
LegacyStackSynthesizer: Uses CloudFormation parameters to communicate asset locations, and the CLI's current permissions to deploy stacks. This is the default stack synthesizer in CDKv1.
CliCredentialsStackSynthesizer: Uses predefined asset locations, and the CLI's current permissions.

Each of these synthesizers takes configuration arguments. To configure a stack with a synthesizer, pass it as one of its properties:

MyStack(app, "MyStack",
    synthesizer=DefaultStackSynthesizer(
        file_assets_bucket_name="amzn-s3-demo-bucket"
    )
)

For more information on bootstrapping accounts and customizing synthesis, see Bootstrapping in the CDK Developer Guide.

STS Role Options

You can configure STS options that instruct the CDK CLI on which configuration should it use when assuming the various roles that are involved in a deployment operation.

Refer to the bootstrapping guide for further context.

These options are available via the DefaultStackSynthesizer properties:

class MyStack(Stack):
    def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None, propertyInjectors=None):
        super().__init__(scope, id,
            (SpreadAssignment ...props
              description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation, propertyInjectors=propertyInjectors),
            synthesizer=DefaultStackSynthesizer(
                deploy_role_external_id="",
                deploy_role_additional_options={},
                file_asset_publishing_external_id="",
                file_asset_publishing_role_additional_options={},
                image_asset_publishing_external_id="",
                image_asset_publishing_role_additional_options={},
                lookup_role_external_id="",
                lookup_role_additional_options={}
            )
        )

Note that the *additionalOptions property does not allow passing ExternalId or RoleArn, as these options have dedicated properties that configure them.

Session Tags

STS session tags are used to implement Attribute-Based Access Control (ABAC).

See IAM tutorial: Define permissions to access AWS resources based on tags.

You can pass session tags for each role created during bootstrap via the *additionalOptions property:

class MyStack(Stack):
    def __init__(self, parent, id, *, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None, propertyInjectors=None):
        super().__init__(parent, id,
            (SpreadAssignment ...props
              description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation, propertyInjectors=propertyInjectors),
            synthesizer=DefaultStackSynthesizer(
                deploy_role_additional_options={
                    "Tags": [{"Key": "Department", "Value": "Engineering"}]
                },
                file_asset_publishing_role_additional_options={
                    "Tags": [{"Key": "Department", "Value": "Engineering"}]
                },
                image_asset_publishing_role_additional_options={
                    "Tags": [{"Key": "Department", "Value": "Engineering"}]
                },
                lookup_role_additional_options={
                    "Tags": [{"Key": "Department", "Value": "Engineering"}]
                }
            )
        )

This will cause the CDK CLI to include session tags when assuming each of these roles during deployment. Note that the trust policy of the role must contain permissions for the sts:TagSession action.

Refer to the IAM user guide on session tags.

If you are using a

aws-cdk-lib

Description