This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

AWS CDK Toolkit (cdkcommand)

The AWS CDK Toolkit, the CLI commandcdk,is the primary tool for interacting with your AWS CDK app. It executes your app, interrogates the application model you defined, and produces and deploys the AWS CloudFormation templates generated by the AWS CDK. It also provides other features useful for creating and working with AWS CDK projects. This topic contains information about common use cases of the CDK Toolkit.

The AWS CDK Toolkit is installed with the Node Package Manager. In most cases, we recommend installing it globally.

npm install -g aws-cdk # install latest version
npm install -g [email protected] # install specific version

Toolkit commands

All CDK Toolkit commands start withcdk,which is followed by a subcommand (list, synthesize,deploy,etc.). Some subcommands have a shorter version (ls, synth,etc.) that is equivalent. Options and arguments follow the subcommand in any order.

For a description of all subcommands, options, and arguments, seeAWS CDK CLI command reference.

Specifying options and their values

Command line options begin with two hyphens (--). Some frequently used options have single-letter synonyms that begin with a single hyphen (for example,--apphas a synonym-a). The order of options in an AWS CDK Toolkit command is not important.

All options accept a value, which must follow the option name. The value may be separated from the name by white space or by an equals sign=.The following two options are equivalent.

--toolkit-stack-name MyBootstrapStack
--toolkit-stack-name=MyBootstrapStack

Some options are flags (Booleans). You may specifytrueorfalseas their value. If you do not provide a value, the value is taken to betrue.You may also prefix the option name with no-to implyfalse.

# sets staging flag to true
--staging
--staging=true
--staging true

# sets staging flag to false
--no-staging
--staging=false
--staging false

A few options, namely--context,--parameters,--plugin, --tags,and--trust,may be specified more than once to specify multiple values. These are noted as having[array]type in the CDK Toolkit help. For example:

cdk bootstrap --tags costCenter=0123 --tags responsibleParty=jdoe

Built-in help

The AWS CDK Toolkit has integrated help. You can see general help about the utility and a list of the provided subcommands by issuing:

cdk --help

To see help for a particular subcommand, for exampledeploy,specify it before the--help flag.

cdk deploy --help

Issuecdk versionto display the version of the AWS CDK Toolkit. Provide this information when requesting support.

Version reporting

To gain insight into how the AWS CDK is used, the constructs used by AWS CDK applications are collected and reported by using a resource identified asAWS::CDK::Metadata.This resource is added to AWS CloudFormation templates, and can easily be reviewed. This information can also be used by AWS to identify stacks using a construct with known security or reliability issues. It can also be used to contact their users with important information.

By default, the AWS CDK reports the use of constructs in the following NPM modules that are used in the stack:

TheAWS::CDK::Metadataresource looks something like the following.

CDKMetadata:
Type: "AWS::CDK::Metadata"
Properties:
Analytics: "v2:deflate64:H4sIAND9SGAAAzXKSw5AMBAA0L1b2PdzBYnEAdio3RglglY60zQi7u6TWL/XKmNUlxeQSOKwaPTBqrNhwEWU3hGHiCzK0dWWfAxoL/Fd8mvk+QkS/0X6BdjnCdgmOOQKWz+AqqLDt2Y3YMnLYWwAAAA="

TheAnalyticsproperty is a gzipped, base64-encoded, prefix-encoded list of the constructs in the stack.

To opt out of version reporting, use one of the following methods:

Authentication with AWS

There are different ways in which you can configure programmatic access to AWS resources, depending on the environment and the AWS access available to you.

To choose your method of authentication and configure it for the CDK Toolkit, seeAuthentication and accessin the AWS SDKs and Tools Reference Guide.

The recommended approach for new users developing locally, who are not given a method of authentication by their employer, is to set up AWS IAM Identity Center. This method includes installing the AWS CLI for ease of configuration and for regularly signing in to the AWS access portal. If you choose this method, your environment should contain the following elements after you complete the procedure forIAM Identity Center authenticationin theAWS SDKs and Tools Reference Guide:

Start an AWS access portal session

Before accessing AWS services, you need an active AWS access portal session for the CDK Toolkit to use IAM Identity Center authentication to resolve credentials. Depending on your configured session lengths, your access will eventually expire and the CDK Toolkit will encounter an authentication error. Run the following command in the AWS CLI to sign in to the AWS access portal.

aws sso login

If your SSO token provider configuration is using a named profile instead of the default profile, the command is aws sso login --profileNAME.Also specify this profile when issuing cdkcommands using the--profileoption or theAWS_PROFILE environment variable.

To test if you already have an active session, run the following AWS CLI command.

aws sts get-caller-identity

The response to this command should report the IAM Identity Center account and permission set configured in the shared configfile.

Specifying Region and other configuration

The CDK Toolkit needs to know the AWS Region that you're deploying into and how to authenticate with AWS. This is needed for deployment operations and to retrieve context values during synthesis. Together, your account and Region make up theenvironment.

Region may be specified using environment variables or in configuration files. These are the same variables and files used by other AWS tools such as the AWS CLI and the various AWS SDKs. The CDK Toolkit looks for this information in the following order.

Besides specifying AWS authentication and a Region in the[default]section, you can also add one or more[profileNAME]sections, whereNAMEis the name of the profile. For more information about named profiles, seeShared config and credentials filesin theAWS SDKs and Tools Reference Guide.

The standard AWSconfigfile is located at~/.aws/config(macOS/Linux) or%USERPROFILE%\.aws\config(Windows). For details and alternate locations, seeLocation of the shared config and credentials filesin the AWS SDKs and Tools Reference Guide

The environment that you specify in your AWS CDK app by using the stack'senvproperty is used during synthesis. It's used to generate an environment-specific AWS CloudFormation template, and during deployment, it overrides the account or Region specified by one of the preceding methods. For more information, seeEnvironments.

You may optionally use the--role-arn(or-r) option to specify the ARN of an IAM role that should be used for deployment. This role must be assumable by the AWS account being used.

Specifying the app command

Many features of the CDK Toolkit require one or more AWS CloudFormation templates be synthesized, which in turn requires running your application. The AWS CDK supports programs written in a variety of languages. Therefore, it uses a configuration option to specify the exact command necessary to run your app. This option can be specified in two ways.

First, and most commonly, it can be specified using theappkey inside the file cdk.json.This is in the main directory of your AWS CDK project. The CDK Toolkit provides an appropriate command when creating a new project withcdk init.Here is thecdk.json from a fresh TypeScript project, for instance.

{
"app": "npx ts-node bin/hello-cdk.ts"
}

The CDK Toolkit looks forcdk.jsonin the current working directory when attempting to run your app. Because of this, you might keep a shell open in your project's main directory for issuing CDK Toolkit commands.

The CDK Toolkit also looks for the app key in~/.cdk.json(that is, in your home directory) if it can't find it in./cdk.json.Adding the app command here can be useful if you usually work with CDK code in the same language.

If you are in some other directory, or to run your app using a command other than the one in cdk.json,use the--app(or-a) option to specify it.

cdk --app "npx ts-node bin/hello-cdk.ts" ls

When deploying, you may also specify a directory containing synthesized cloud assemblies, such as cdk.out,as the value of--app.The specified stacks are deployed from this directory; the app is not synthesized.

Specifying stacks

Many CDK Toolkit commands (for example,cdk deploy) work on stacks defined in your app. If your app contains only one stack, the CDK Toolkit assumes you mean that one if you don't specify a stack explicitly.

Otherwise, you must specify the stack or stacks you want to work with. You can do this by specifying the desired stacks by ID individually on the command line. Recall that the ID is the value specified by the second argument when you instantiate the stack.

cdk synth PipelineStack LambdaStack

You may also use wildcards to specify IDs that match a pattern.

You may also use the--alloption to specify all stacks.

If your app usesCDK Pipelines,the CDK Toolkit understands your stacks and stages as a hierarchy. Also, the--alloption and the*wildcard only match top-level stacks. To match all the stacks, use**.Also use**to indicate all the stacks under a particular hierarchy.

When using wildcards, enclose the pattern in quotes, or escape the wildcards with\.If you don't, your shell may try to expand the pattern to the names of files in the current directory. At best, this won't do what you expect; at worst, you could deploy stacks you didn't intend to. This isn't strictly necessary on Windows because cmd.exedoes not expand wildcards, but is good practice nonetheless.

cdk synth "*Stack" # PipelineStack, LambdaStack, etc.
cdk synth 'Stack?' # StackA, StackB, Stack1, etc.
cdk synth \* # All stacks in the app, or all top-level stacks in a CDK Pipelines app
cdk synth '**' # All stacks in a CDK Pipelines app
cdk synth 'PipelineStack/Prod/**' # All stacks in Prod stage in a CDK Pipelines app

Bootstrapping your AWS environment

Deploying stacks with the CDK requires special dedicated AWS CDK resources to be provisioned. Thecdk bootstrapcommand creates the necessary resources for you. You only need to bootstrap if you are deploying a stack that requires these dedicated resources. SeeBootstrappingfor details.

cdk bootstrap

If issued with no arguments, as shown here, thecdk bootstrapcommand synthesizes the current app and bootstraps the environments its stacks will be deployed to. If the app contains environment-agnostic stacks, which don't explicitly specify an environment, the default account and Region are bootstrapped, or the environment specified using--profile.

Outside of an app, you must explicitly specify the environment to be bootstrapped. You may also do so to bootstrap an environment that's not specified in your app or local AWS profile. Credentials must be configured (e.g. in ~/.aws/credentials) for the specified account and Region. You may specify a profile that contains the required credentials.

cdk bootstrapACCOUNT-NUMBER/REGION# e.g.
cdk bootstrap 1111111111/us-east-1
cdk bootstrap --profile test 1111111111/us-east-1

You may incur AWS charges for what the AWS CDK stores in the bootstrapped resources. Additionally, if you use -bootstrap-customer-key,an AWS KMS key will be created, which also incurs charges per environment.

Creating a new app

To create a new app, create a directory for it, then, inside the directory, issuecdk init.

mkdir my-cdk-app
cd my-cdk-app
cdk initTEMPLATE--languageLANGUAGE

The supported languages (LANGUAGE) are:

TEMPLATEis an optional template. If the desired template isapp, the default, you may omit it. The available templates are:

The templates use the name of the project folder to generate names for files and classes inside your new app.

Listing stacks

To see a list of the IDs of the stacks in your AWS CDK application, enter one of the following equivalent commands:

cdk list
cdk ls

If your application containsCDK Pipelinesstacks, the CDK Toolkit displays stack names as paths according to their location in the pipeline hierarchy. (For example, PipelineStack,PipelineStack/Prod,and PipelineStack/Prod/MyService.)

If your app contains many stacks, you can specify full or partial stack IDs of the stacks to be listed. For more information, seeSpecifying stacks.

Add the--longflag to see more information about the stacks, including the stack names and their environments (AWS account and Region).

Synthesizing stacks

Thecdk synthesizecommand (almost always abbreviatedsynth) synthesizes a stack defined in your app into a CloudFormation template.

cdk synth # if app contains only one stack
cdk synth MyStack
cdk synth Stack1 Stack2
cdk synth "*" # all stacks in app

Seecdk synth --helpfor all available options. A few of the most frequently used options are covered in the following section.

Specifying context values

Use the--contextor-coption to passruntime context values to your CDK app.

# specify a single context value
cdk synth --context key=value MyStack

# specify multiple context values (any number)
cdk synth --context key1=value1 --context key2=value2 MyStack

When deploying multiple stacks, the specified context values are normally passed to all of them. If you want, you can specify different values for each stack by prefixing the stack name to the context value.

# different context values for each stack
cdk synth --context Stack1:key=value Stack2:key=value Stack1 Stack2

Specifying display format

By default, the synthesized template is displayed in YAML format. Add the--jsonflag to display it in JSON format instead.

cdk synth --json MyStack

Specifying output directory

Add the--output(-o) option to write the synthesized templates to a directory other thancdk.out.

cdk synth --output=~/templates

Deploying stacks

Thecdk deploysubcommand deploys one or more specified stacks to your AWS account.

cdk deploy # if app contains only one stack
cdk deploy MyStack
cdk deploy Stack1 Stack2
cdk deploy "*" # all stacks in app

Seecdk deploy --helpfor all available options. A few of the most useful options are covered in the following section.

Skipping synthesis

Thecdk deploycommand normally synthesizes your app's stacks before deploying to make sure that the deployment reflects the latest version of your app. If you know that you haven't changed your code since your lastcdk synth,you can suppress the redundant synthesis step when deploying. To do so, specify your project'scdk.outdirectory in the--appoption.

cdk deploy --app cdk.out StackOne StackTwo

Disabling rollback

AWS CloudFormation has the ability to roll back changes so that deployments are atomic. This means that they either succeed or fail as a whole. The AWS CDK inherits this capability because it synthesizes and deploys AWS CloudFormation templates.

Rollback makes sure that your resources are in a consistent state at all times, which is vital for production stacks. However, while you're still developing your infrastructure, some failures are inevitable, and rolling back failed deployments can slow you down.

For this reason, the CDK Toolkit lets you disable rollback by adding--no-rollbackto your cdk deploycommand. With this flag, failed deployments are not rolled back. Instead, resources deployed before the failed resource remain in place, and the next deployment starts with the failed resource. You'll spend a lot less time waiting for deployments and a lot more time developing your infrastructure.

Hot swapping

Use the--hotswapflag withcdk deployto attempt to update your AWS resources directly instead of generating an AWS CloudFormation change set and deploying it. Deployment falls back to AWS CloudFormation deployment if hot swapping is not possible.

Currently hot swapping supports Lambda functions, Step Functions state machines, and Amazon ECS container images. The --hotswapflag also disables rollback (i.e., implies--no-rollback).

Watch mode

The CDK Toolkit's watch mode (cdk deploy --watch,orcdk watchfor short) continuously monitors your CDK app's source files and assets for changes. It immediately performs a deployment of the specified stacks when a change is detected.

By default, these deployments use the--hotswapflag, which fast-tracks deployment of changes to Lambda functions. It also falls back to deploying through AWS CloudFormation if you have changed infrastructure configuration. To havecdk watchalways perform full AWS CloudFormation deployments, add the--no-hotswapflag to cdk watch.

Any changes made whilecdk watchis already performing a deployment are combined into a single deployment, which begins as soon as the in-progress deployment is complete.

Watch mode uses the"watch"key in the project'scdk.jsonto determine which files to monitor. By default, these files are your application files and assets, but this can be changed by modifying the"include"and"exclude"entries in the"watch"key. The following cdk.jsonfile shows an example of these entries.

{
"app": "mvn -e -q compile exec:java",
"watch":{
"include": "src/main/**",
"exclude": "target/*"
}
}

cdk watchexecutes the"build"command fromcdk.jsonto build your app before synthesis. If your deployment requires any commands to build or package your Lambda code (or anything else that's not in your CDK app), add it here.

Git-style wildcards, both*and**,can be used in the"watch"and "build"keys. Each path is interpreted relative to the parent directory of cdk.json.The default value ofincludeis**/*,meaning all files and directories in the project root directory.excludeis optional.

Specifying AWS CloudFormation parameters

The AWS CDK Toolkit supports specifying AWS CloudFormationparametersat deployment. You may provide these on the command line following the--parametersflag.

cdk deploy MyStack --parameters uploadBucketName=UploadBucket

To define multiple parameters, use multiple--parametersflags.

cdk deploy MyStack --parameters uploadBucketName=UpBucket --parameters downloadBucketName=DownBucket

If you are deploying multiple stacks, you can specify a different value of each parameter for each stack. To do so, prefix the name of the parameter with the stack name and a colon. Otherwise, the same value is passed to all stacks.

cdk deploy MyStack YourStack --parameters MyStack:uploadBucketName=UploadBucket --parameters YourStack:uploadBucketName=UpBucket

By default, the AWS CDK retains values of parameters from previous deployments and uses them in later deployments if they are not specified explicitly. Use the--no-previous-parametersflag to require all parameters to be specified.

Specifying outputs file

If your stack declares AWS CloudFormation outputs, these are normally displayed on the screen at the conclusion of deployment. To write them to a file in JSON format, use the--outputs-fileflag.

cdk deploy --outputs-file outputs.json MyStack

Security-related changes

To protect you against unintended changes that affect your security posture, the AWS CDK Toolkit prompts you to approve security-related changes before deploying them. You can specify the level of change that requires approval:

cdk deploy --require-approvalLEVEL

LEVELcan be one of the following:

The setting can also be configured in thecdk.jsonfile.

{
"app": "...",
"requireApproval": "never"
}

Comparing stacks

Thecdk diffcommand compares the current version of a stack (and its dependencies) defined in your app with the already-deployed versions, or with a saved AWS CloudFormation template, and displays a list of changes.

Stack HelloCdkStack
IAM Statement Changes
┌───┬──────────────────────────────┬────────┬──────────────────────────────┬──────────────────────────────┬───────────┐
│ │ Resource │ Effect │ Action │ Principal │ Condition │
├───┼──────────────────────────────┼────────┼──────────────────────────────┼──────────────────────────────┼───────────┤
│ + │ ${Custom::S3AutoDeleteObject │ Allow │ sts:AssumeRole │ Service:lambda.amazonaws.com │ │
│ │ sCustomResourceProvider/Role │ │ │ │ │
│ │.Arn} │ │ │ │ │
├───┼──────────────────────────────┼────────┼──────────────────────────────┼──────────────────────────────┼───────────┤
│ + │ ${MyFirstBucket.Arn} │ Allow │ s3:DeleteObject* │ AWS:${Custom::S3AutoDeleteOb │ │
│ │ ${MyFirstBucket.Arn}/* │ │ s3:GetBucket* │ jectsCustomResourceProvider/ │ │
│ │ │ │ s3:GetObject* │ Role.Arn} │ │
│ │ │ │ s3:List* │ │ │
└───┴──────────────────────────────┴────────┴──────────────────────────────┴──────────────────────────────┴───────────┘
IAM Policy Changes
┌───┬────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────┐
│ │ Resource │ Managed Policy ARN │
├───┼────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ + │ ${Custom::S3AutoDeleteObjectsCustomResourceProvider/Ro │{"Fn::Sub": "arn:${AWS::Partition}:iam::aws:policy/serv │
│ │ le} │ ice-role/AWSLambdaBasicExecutionRole "} │
└───┴────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────┘
(NOTE: There may be security-related changes not in this list. See https://github.com/aws/aws-cdk/issues/1299)

Parameters
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3Bucket AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3BucketBF7A7F3F:{"Type": "String", "Description": "S3 bucket for asset \" 4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\ "" }
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3VersionKey AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3VersionKeyFAF93626:{"Type": "String", "Description": "S3 key for asset version \" 4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\ "" }
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/ArtifactHash AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392ArtifactHashE56CD69A:{"Type": "String", "Description": "Artifact hash for asset \" 4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\ "" }

Resources
[+] AWS::S3::BucketPolicy MyFirstBucket/Policy MyFirstBucketPolicy3243DEFD
[+] Custom::S3AutoDeleteObjects MyFirstBucket/AutoDeleteObjectsCustomResource MyFirstBucketAutoDeleteObjectsCustomResourceC52FCF6E
[+] AWS::IAM::Role Custom::S3AutoDeleteObjectsCustomResourceProvider/Role CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092
[+] AWS::Lambda::Function Custom::S3AutoDeleteObjectsCustomResourceProvider/Handler CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184F
[~] AWS::S3::Bucket MyFirstBucket MyFirstBucketB8884501
├─ [~] DeletionPolicy
│ ├─ [-] Retain
│ └─ [+] Delete
└─ [~] UpdateReplacePolicy
├─ [-] Retain
└─ [+] Delete

To compare your app's stacks with the existing deployment:

cdk diff MyStack

To compare your app's stacks with a saved CloudFormation template:

cdk diff --template ~/stacks/MyStack.old MyStack

Importing existing resources into a stack

You can use thecdk importcommand to bring resources under the management of CloudFormation for a particular AWS CDK stack. This is useful if you are migrating to AWS CDK, or are moving resources between stacks or changing their logical id.cdk importusesCloudFormation resource imports.See thelist of resources that can be imported here.

To import an existing resource into a AWS CDK stack, follow the following steps:

This feature currently does not support importing resources into nested stacks.

Configuration (cdk.json)

Default values for many CDK Toolkit command line flags can be stored in a project'scdk.json file or in the.cdk.jsonfile in your user directory. Following is an alphabetical reference to the supported configuration settings.