AWS CDK Toolkit (cdk command)
The AWS CDK Toolkit, the CLI command cdk, 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 aws-cdk@X.YY.Z # install specific version
If you regularly work with multiple versions of the AWS CDK, you may want to install
a
matching version of the AWS CDK Toolkit in individual CDK projects. To do this, omit
-g from the npm install command. Then use npx cdk to
invoke it; this will run the local version if one exists, falling back to a global
version if
not.
Toolkit commands
All CDK Toolkit commands start with cdk, 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. The available commands are summarized
here.
|
Command |
Function |
|---|---|
|
|
Lists the stacks in the app |
|
|
Synthesizes and prints the CloudFormation template for the specified stack(s) |
|
|
Deploys the CDK Toolkit stack; see Bootstrapping |
|
|
Deploys the specified stack(s) |
|
|
Destroys the specified stack(s) |
|
|
Compares the specified stack with the deployed stack or a local CloudFormation template |
|
|
Displays metadata about the specified stack |
|
|
Creates a new CDK project in the current directory from a specified template |
|
|
Manages cached context values |
|
|
Opens the CDK API reference in your browser |
|
|
Checks your CDK project for potential problems |
For the options available for each command, see Toolkit reference or Built-in help.
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,
--app has 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 whitespace 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 specify true or false
as their value. If you do not provide a value, the value is taken to be true. You
may also prefix the option name with no- to imply false.
# sets staging flag to true --staging --staging=true --staging true # sets staging flag to false --no-staging --staging=false --staging false
A few flags, 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.
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 example deploy, specify it
before the --help flag.
cdk deploy --help
Issue cdk version to 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 versions of libraries used by AWS
CDK
applications are collected and reported by using a resource identified as
AWS::CDK::Metadata. This resource is added to AWS CloudFormation templates, and can easily
be reviewed. This information can also be used to identify stacks using a package
with known
serious security or reliability issues, and to contact their users with important
information.
By default, the AWS CDK reports the name and version of the following NPM modules that are loaded at synthesis time:
-
AWS CDK core module
-
AWS Construct Library modules
-
AWS Solutions Constructs module
-
AWS Render Farm Deployment Kit module
The AWS::CDK::Metadata resource looks something like the following.
CDKMetadata:
Type: "AWS::CDK::Metadata"
Properties:
Modules: "@aws-cdk/core=X.YY.Z,@aws-cdk/s3=X.YY.Z,@aws-solutions-constrccts/aws-apigateway-lambda=X.YY.Z,aws-rfdk=X.YY.Z"
To opt out of version reporting, use one of the following methods:
-
Use the cdk command with the --no-version-reporting argument to opt out for a single command.
cdk --no-version-reporting synthRemember, the AWS CDK Toolkit synthesizes fresh templates before deploying, so you should also add
--no-version-reportingtocdk deploycommands. -
Set versionReporting to false in
./cdk.jsonor~/.cdk.json. This opts out unless you opt in by specifying--version-reportingon an individual command.{ "app": "...", "versionReporting": false }
Specifying the environment
In AWS CDK terms, the environment consists of a region and AWS credentials valid in that region. The CDK Toolkit needs credentials in order to query your AWS account and to deploy CloudFormation templates.
We strongly recommend against using your AWS root account for day-to-day tasks. Instead, create a user in IAM and use its credentials with the CDK.
If you have the AWS CLI installed, the easiest way to satisfy this requirement is to install the AWS CLI and issue the following command:
aws configure
Provide your AWS access key ID, secret access key, and default region when prompted.
You may also manually create or edit the ~/.aws/config and
~/.aws/credentials (Mac OS X or Linux) or
%USERPROFILE%\.aws\config and
%USERPROFILE%\.aws\credentials (Windows) files to contain credentials
and a default region, in the following format.
-
In
~/.aws/configor%USERPROFILE%\.aws\config[default] region=us-west-2 -
In
~/.aws/credentialsor%USERPROFILE%\.aws\credentials[default] aws_access_key_id=AKIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Besides specifying AWS credentials and a region under the [default]
section, you can also put them in a [profile
section, where NAME]NAME is the name of the profile. You can add any
number of named profiles, with or without a [default] section. Be sure to add the
same profile sections to both the configuration and credentials files.
Don't name a profile default. That's just confusing.
Use the --profile flag to choose a set of credentials and default region from
these configuration files for a given command.
cdk deploy --profile test PipelineStack
Instead of using the configuration files, you can set the environment variables
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and
AWS_DEFAULT_REGION to appropriate values.
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. Since the AWS CDK supports programs written in a variety of languages, 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 the app key inside the
file cdk.json, which is in the main directory of your AWS CDK project. The
CDK Toolkit provides an appropriate command when creating a new project with cdk
init. Here is the cdk.json from a fresh TypeScript project, for
instance.
{ "app": "npx ts-node bin/hello-cdk.ts" }
The CDK Toolkit looks for cdk.json in the current working directory
when attempting to run your app, so 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, as it does
not
require you to be in the app's main directory when you run a cdk command.
If you are in some other directory, or if you want to run your app via a command other
than the one in cdk.json, you can use the --app (or
-a) option to specify it.
cdk --app "npx ts-node bin/hello-cdk.ts" ls
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.
-
? matches any single character
-
* matches any number of characters
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.exe does not expand wildcards, but is good practice regardless.
cdk synth "*Stack" # PipelineStack, LambdaStack, etc. cdk synth 'Stack?' # StackA, StackB, Stack1, etc. cdk synth \* # All stacks in the app
The order in which you specify the stacks is not necessarily the order in which they
will be processed. The AWS CDK Toolkit takes into account dependencies between stacks
when
deciding the order in which to process them. For example, if one stack uses a value
produced
by another (such as the ARN of a resource defined in the second stack), the second
stack is
synthesized before the first one because of this dependency. You can add dependencies
between stacks manually using the stack's addDependency() method.
Bootstrapping your AWS environment
Deploying stacks that contain assets, synthesize to large
templates, or use CDK Pipelines require special dedicated
AWS CDK resources to be provisioned. The cdk bootstrap command creates the
necessary resources for you. You only need to bootstrap if you are deploying a stack
that
requires these dedicated resources. See Bootstrapping for details.
cdk bootstrap # bootstraps default account/region cdk bootstrap --profile test # bootstraps test environment
You may also bootstrap a specific environment. 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
Each environment (account/region combination) to which you deploy such a stack must be bootstrapped separately.
You may incur AWS charges for what the AWS CDK stores in the bootstrapped resources.
Additionally, if you use -bootstrap-customer-key, a Customer Master Key (CMK)
will be created, which also incurs charges per environment.
Older versions of the modern template created a Customer Master Key by default. To
avoid
charges, re-bootstrap using --no-bootstrap-customer-key.
Creating a new app
To create a new app, create a directory for it, then, inside the directory, issue
cdk init.
mkdir my-cdk-app cd my-cdk-app cdk initTEMPLATE--languageLANGUAGE
The supported languages (LANGUAGE) are:
|
Code |
Language |
|---|---|
|
|
TypeScript |
|
|
JavaScript |
|
|
Python |
|
|
Java |
|
|
C# |
TEMPLATE is an optional template. If the desired template is
app, the default, you may omit it. The available templates are:
|
Template |
Description |
|---|---|
|
|
Creates an empty AWS CDK app. |
|
|
Creates an AWS CDK app with a stack containing an Amazon SQS queue and an Amazon SNS topic. |
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 app contains many stacks, you can specify full or partial stack IDs of the stacks to be listed; see Specifying stacks.
Add the --long flag to see more information about the stacks, including the
stack names and their environments (AWS account and region).
Synthesizing stacks
The cdk synthesize command (almost always abbreviated synth)
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
The CDK Toolkit actually runs your app and synthesizes fresh templates before most
operations (e.g. when deploying or comparing stacks). These templates are stored by
default
in the cdk.out directory. The cdk synth command simply
prints the generated templates for the specified stack(s).
See cdk synth --help for all available options. A few of the
most-frequently-used options are covered below.
Specifying context values
Use the --context or -c option to pass runtime 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 wish, you may 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
--json flag 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 than cdk.out.
cdk synth --output=~/templates
Deploying stacks
The cdk deploy subcommand deploys the specified stack(s) 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
The CDK Toolkit runs your app and synthesizes fresh AWS CloudFormation templates before
deploying
anything. Therefore, most command line options you can use with cdk synth (for
example, --context) can also be used with cdk deploy.
See cdk deploy --help for all available options. A few of the
most-frequently-used options are covered below.
Specifying AWS CloudFormation parameters
The AWS CDK Toolkit supports specifying AWS CloudFormation parameters
at deployment. You may provide these on the command line following the
--parameters flag.
cdk deploy MyStack --parameters uploadBucketName=UploadBucket
To define multiple parameters, use multiple --parameters flags.
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 by prefixing 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-parameters flag 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-file flag.
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
LEVEL can be one of the following:
|
Term |
Meaning |
|---|---|
|
|
Approval is never required |
|
|
Requires approval on any IAM or security-group-related change |
|
|
Requires approval when IAM statements or traffic rules are added; removals don't require approval |
The setting can also be configured in the cdk.json file.
{ "app": "...", "requireApproval": "never" }
Comparing stacks
The cdk diff command compares the current version of a stack defined in your
app with the already-deployed version, or with a saved AWS CloudFormation template,
and displays a list of
changes .
Stack HelloCdkStack
IAM Statement Changes
┌───┬────────────────────────┬────────┬──────────────┬───────────┬───────────┐
│ │ Resource │ Effect │ Action │ Principal │ Condition │
├───┼────────────────────────┼────────┼──────────────┼───────────┼───────────┤
│ + │ ${MyFirstBucket.Arn}/* │ Allow │ s3:GetObject │ * │ │
└───┴────────────────────────┴────────┴──────────────┴───────────┴───────────┘
(NOTE: There may be security-related changes not in this list. See https://github.com/aws/aws-cdk/issues/1299)
Resources
[+] AWS::S3::BucketPolicy MyFirstBucket/Policy MyFirstBucketPolicy3243DEFD
[~] AWS::S3::Bucket MyFirstBucket MyFirstBucketB8884501
├─ [~] DeletionPolicy
│ ├─ [-] Retain
│ └─ [+] Delete
└─ [~] UpdateReplacePolicy
├─ [-] Retain
└─ [+] Delete
To compare your app's stack(s) with the existing deployment:
cdk diff MyStack
To compare your app's stack(s) with a saved CloudFormation template:
cdk diff --template ~/stacks/MyStack.old MyStack
Toolkit reference
This section provides a reference for the AWS CDK Toolkit derived from its help, first a general reference with the options available with all commands, then (in collapsible sections) specific references with options available only with specific subcommands.
Usage: cdk -a <cdk-app> COMMAND
Commands:
cdk list [STACKS..] Lists all stacks in the app [aliases: ls]
cdk synthesize [STACKS..] Synthesizes and prints the CloudFormation
template for this stack [aliases: synth]
cdk bootstrap [ENVIRONMENTS..] Deploys the CDK toolkit stack into an AWS
environment
cdk deploy [STACKS..] Deploys the stack(s) named STACKS into your
AWS account
cdk destroy [STACKS..] Destroy the stack(s) named STACKS
cdk diff [STACKS..] Compares the specified stack with the deployed
stack or a local template file, and returns
with status 1 if any difference is found
cdk metadata [STACK] Returns all metadata associated with this
stack
cdk init [TEMPLATE] Create a new, empty CDK project from a
template.
cdk context Manage cached context values
cdk docs Opens the reference documentation in a browser
[aliases: doc]
cdk doctor Check your set-up for potential problems
Options:
-a, --app REQUIRED: command-line for executing your app or a
cloud assembly directory (e.g. "node bin/my-app.js")
[string]
-c, --context Add contextual string parameter (KEY=VALUE) [array]
-p, --plugin Name or path of a node package that extend the CDK
features. Can be specified multiple times [array]
--trace Print trace for stack warnings [boolean]
--strict Do not construct stacks with warnings [boolean]
--lookups Perform context lookups (synthesis fails if this is
disabled and context lookups need to be performed)
[boolean] [default: true]
--ignore-errors Ignores synthesis errors, which will likely produce
an invalid output [boolean] [default: false]
-j, --json Use JSON output instead of YAML when templates are
printed to STDOUT [boolean] [default: false]
-v, --verbose Show debug logs (specify multiple times to increase
verbosity) [count] [default: false]
--debug Enable emission of additional debugging information,
such as creation stack traces of tokens
[boolean] [default: false]
--profile Use the indicated AWS profile as the default
environment [string]
--proxy Use the indicated proxy. Will read from HTTPS_PROXY
environment variable if not specified [string]
--ca-bundle-path Path to CA certificate to use when validating HTTPS
requests. Will read from AWS_CA_BUNDLE environment
variable if not specified [string]
-i, --ec2creds Force trying to fetch EC2 instance credentials.
Default: guess EC2 instance status [boolean]
--version-reporting Include the "AWS::CDK::Metadata" resource in
synthesized templates (enabled by default) [boolean]
--path-metadata Include "aws:cdk:path" CloudFormation metadata for
each resource (enabled by default)
[boolean] [default: true]
--asset-metadata Include "aws:asset:*" CloudFormation metadata for
resources that user assets (enabled by default)
[boolean] [default: true]
-r, --role-arn ARN of Role to use when invoking CloudFormation
[string]
--toolkit-stack-name The name of the CDK toolkit stack [string]
--staging Copy assets to the output directory (use
--no-staging to disable, needed for local debugging
the source files with SAM CLI)
[boolean] [default: true]
-o, --output Emits the synthesized cloud assembly into a
directory (default: cdk.out) [string]
--no-color Removes colors and other style from console output
[boolean] [default: false]
--fail Fail with exit code 1 in case of diff
[boolean] [default: false]
--version Show version number [boolean]
-h, --help Show help [boolean]
If your app has a single stack, there is no need to specify the stack name
If one of cdk.json or ~/.cdk.json exists, options specified there will be used
as defaults. Settings in cdk.json take precedence.
cdk list [STACKS..]
Lists all stacks in the app
Options:
-l, --long Display environment information for each stack
[boolean] [default: false]cdk synthesize [STACKS..]
Synthesizes and prints the CloudFormation template for this stack
Options:
-e, --exclusively Only synthesize requested stacks, don't include
dependencies [boolean]cdk bootstrap [ENVIRONMENTS..]
Deploys the CDK toolkit stack into an AWS environment
Options:
-b, --bootstrap-bucket-name, The name of the CDK toolkit bucket;
--toolkit-bucket-name bucket will be created and must not
exist [string]
--bootstrap-kms-key-id AWS KMS master key ID used for the
SSE-KMS encryption [string]
--bootstrap-customer-key Create a Customer Master Key (CMK)
for the bootstrap bucket (you will
be charged but can customize
permissions, modern bootstrapping
only) [boolean]
--qualifier Unique string to distinguish
multiple bootstrap stacks [string]
--public-access-block-configuration Block public access configuration
on CDK toolkit bucket (enabled by
default) [boolean]
-t, --tags Tags to add for the stack
(KEY=VALUE) [array] [default: []]
--execute Whether to execute ChangeSet
(--no-execute will NOT execute the
ChangeSet) [boolean] [default: true]
--trust The AWS account IDs that should be
trusted to perform deployments into
this environment (may be repeated,
modern bootstrapping only)
[array] [default: []]
--cloudformation-execution-policies The Managed Policy ARNs that should
be attached to the role performing
deployments into this environment
(may be repeated, modern
bootstrapping only)
[array] [default: []]
-f, --force Always bootstrap even if it would
downgrade template version
[boolean] [default: false]
--termination-protection Toggle CloudFormation termination
protection on the bootstrap stacks
[boolean]
--show-template Instead of actual bootstrapping,
print the current CLI's
bootstrapping template to stdout for
customization
[boolean] [default: false]
--template Use the template from the given file
instead of the built-in one (use
--show-template to obtain an
example) [string]cdk deploy [STACKS..]
Deploys the stack(s) named STACKS into your AWS account
Options:
--all Deploy all available stacks
[boolean] [default: false]
-E, --build-exclude Do not rebuild asset with the given ID. Can be
specified multiple times [array] [default: []]
-e, --exclusively Only deploy requested stacks, don't include
dependencies [boolean]
--require-approval What security-sensitive changes need manual
approval
[string] [choices: "never", "any-change", "broadening"]
--ci Force CI detection [boolean] [default: false]
--notification-arns ARNs of SNS topics that CloudFormation will notify
with stack related events [array]
-t, --tags Tags to add to the stack (KEY=VALUE), overrides
tags from Cloud Assembly (deprecated) [array]
--execute Whether to execute ChangeSet (--no-execute will NOT
execute the ChangeSet) [boolean] [default: true]
-f, --force Always deploy stack even if templates are identical
[boolean] [default: false]
--parameters Additional parameters passed to CloudFormation at
deploy time (STACK:KEY=VALUE) [array] [default: {}]
-O, --outputs-file Path to file where stack outputs will be written as
JSON [string]
--previous-parameters Use previous values for existing parameters (you
must specify all parameters on every deployment if
this is disabled) [boolean] [default: true]
--progress Display mode for stack activity events
[string] [choices: "bar", "events"]cdk destroy [STACKS..]
Destroy the stack(s) named STACKS
Options:
--all Destroy all available stacks
[boolean] [default: false]
-e, --exclusively Only destroy requested stacks, don't include
dependees [boolean]
-f, --force Do not ask for confirmation before destroying the
stacks [boolean]cdk diff [STACKS..]
Compares the specified stack with the deployed stack or a local template file,
and returns with status 1 if any difference is found
Options:
-e, --exclusively Only diff requested stacks, don't include
dependencies [boolean]
--context-lines Number of context lines to include in arbitrary JSON
diff rendering [number] [default: 3]
--template The path to the CloudFormation template to compare
with [string]cdk init [TEMPLATE]
Create a new, empty CDK project from a template.
Options:
-l, --language The language to be used for the new project (default
can be configured in ~/.cdk.json)
[string] [choices: "csharp", "fsharp", "java", "javascript", "python",
"typescript"]
--list List the available templates [boolean]
--generate-only If true, only generates project files, without
executing additional operations such as setting up a
git repo, installing dependencies or compiling the
project [boolean] [default: false]cdk context
Manage cached context values
Options:
-e, --reset The context key (or its index) to reset [string]
--clear Clear all context [boolean]