cdk bootstrap - AWS Cloud Development Kit (AWS CDK) v2
UsageArgumentsOptionsExamples

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.

cdk bootstrap

Prepare an AWS environment for CDK deployments by deploying the CDK bootstrap stack, named CDKToolkit, into the AWS environment.

The bootstrap stack is a CloudFormation stack that provisions an Amazon S3 bucket and Amazon ECR repository in the AWS environment. The AWS CDK CLI uses these resources to store synthesized templates and related assets during deployment.

Usage

$ cdk bootstrap <arguments> <options>

Arguments

AWS environment

The target AWS environment to deploy the bootstrap stack to in the following format: aws://<account-id>/<region>.

Example: aws://123456789012/us-east-1

This argument can be provided multiple times in a single command to deploy the bootstrap stack to multiple environments.

By default, the CDK CLI will bootstrap all environments referenced in the CDK app or will determine an environment from default sources. This could be an environment specified using the --profile option, from environment variables, or default AWS CLI sources.

Options

For a list of global options that work with all CDK CLI commands, see Global options.

--bootstrap-bucket-name, --toolkit-bucket-name, -b STRING

The name of the CDK Toolkit bucket. The bucket will be created and must not currently exist.

Default value: Undefined

--bootstrap-customer-key BOOLEAN

Create a Customer Master Key (CMK) for the bootstrap bucket (you will be charged but can customize permissions, modern bootstrapping only).

This option is not compatible with --bootstrap-kms-key-id.

Default value: Undefined

--bootstrap-kms-key-id STRING

The AWS KMS master key ID to use for the SSE-KMS encryption.

This option is not compatible with --bootstrap-customer-key.

Default value: Undefined

--cloudformation-execution-policies ARRAY

The managed IAM policy ARNs that should be attached to the role performing deployments into this environment.

You can provide this option multiple times in a single command.

This option applies to modern bootstrapping only.

Default value: []

--custom-permissions-boundary, -cpb STRING

Specify the name of a permissions boundary to use.

This option is not compatible with --example-permissions-boundary.

Default value: Undefined

--example-permissions-boundary, -epb BOOLEAN

Use the example permissions boundary, supplied by the AWS CDK.

This option is not compatible with --custom-permissions-boundary.

The CDK supplied permissions boundary policy should be regarded as an example. Edit the content and reference the example policy if you are testing out the feature. Convert it into a new policy for actual deployments, if one does not already exist. The concern is to avoid drift. Most likely, a permissions boundary is maintained and has dedicated conventions, naming included.

For more information on configuring permissions, including using permissions boundaries, see the Security and Safety Dev Guide.

Default value: Undefined

--execute BOOLEAN

Configure whether to execute the change set.

Default value: true

--force, -f BOOLEAN

Always bootstrap, even if it would downgrade the bootstrap template version.

Default value: false

--help, -h BOOLEAN

Show command reference information for the cdk bootstrap command.

--previous-parameters BOOLEAN

Use previous values for existing parameters.

Once a bootstrap template is deployed with a set of parameters, you must set this option to false to change any parameters on future deployments. When false, you must re-supply all previously supplied parameters.

Default value: true

--public-access-block-configuration BOOLEAN

Block public access configuration on the Amazon S3 bucket that is created and used by the CDK CLI.

Default value: true

--qualifier STRING

String value that is unique for each bootstrap stack. This value is appended to resources created during bootstrapping.

When you use this option to change default behavior, you must configure your CDK app.

Default value: Undefined

--show-template BOOLEAN

Instead of bootstrapping, print the current bootstrap template to the standard output (stdout). You can then copy and customize the template as necessary.

Default value: false

--tags, -t ARRAY

Tags to add to the bootstrap stack in the format of KEY=VALUE.

Default value: []

--template STRING

Use the template from the given file instead of the built-in one.

--termination-protection BOOLEAN

Toggle AWS CloudFormation termination protection on the bootstrap stack.

When true, termination protection is enabled. This prevents the bootstrap stack from being accidentally deleted.

To learn more about termination protection, see Protecting a stack from being deleted in the AWS CloudFormation User Guide.

Default value: Undefined

--toolkit-stack-name STRING

The name of the bootstrap stack to create.

By default, cdk bootstrap deploys a stack named CDKToolkit into the specified AWS environment. Use this option to provide a different name for your bootstrap stack.

Default value: CDKToolkit

Required: Yes

--trust ARRAY

The AWS account IDs that should be trusted to perform deployments into this environment.

You can provide this option multiple times in a single command.

This option applies to modern bootstrapping only.

Default value: []

--trust-for-lookup ARRAY

The AWS account IDs that should be trusted to look up values in this environment.

You can provide this option multiple times in a single command.

This option applies to modern bootstrapping only.

Default value: []

Examples

Bootstrap the AWS environment specified in the prod profile

$ cdk bootstrap --profile prod

Deploy the bootstrap stack to environments foo and bar

$ cdk bootstrap --app='node bin/main.js' foo bar

Export the bootstrap template to customize it

If you have specific requirements that are not met by the bootstrap template, you can customize it to fit your needs.

You can export the bootstrap template, modify it, and deploy it using AWS CloudFormation. The following is an example of exporting the existing template:

$ cdk bootstrap --show-template > bootstrap-template.yaml

You can also tell the CDK CLI to use a custom template. The following is an example:

$ cdk bootstrap --template my-bootstrap-template.yaml

Bootstrap with a permissions boundary. Then, remove that permissions boundary

To bootstrap with a custom permissions boundary, we run the following:

$ cdk bootstrap --custom-permissions-boundary my-permissions-boundary

To remove the permissions boundary, we run the following:

$ cdk bootstrap --no-previous-parameters

Use a qualifier to distinguish resources that are created for a development environment

$ cdk bootstrap --qualifier dev2024