Bootstrapping Your AWS Environment
Relevant source files
The following files were used as context for generating this wiki page:
Bootstrapping is the process of provisioning resources in an AWS environment (a specific account and region combination) that the AWS CDK needs to perform deployments. The cdk bootstrap command is used to launch a CloudFormation stack, named CDKToolkit by default, which creates these foundational resources. This one-time setup per environment enables the CDK CLI to deploy stacks that are larger than the CloudFormation template size limit (51,200 bytes) or that use assets (like Lambda function code or Docker images).
The bootstrap process is essential for most real-world CDK applications. It creates an S3 bucket for storing file assets and synthesized templates, and an ECR repository for Docker image assets. It also sets up IAM roles with specific permissions required for asset publishing and CloudFormation deployments, especially in cross-account CI/CD scenarios.
Sources: design/cdk-bootstrap.md:3-6, packages/aws-cdk/README.md:214-217
The cdk bootstrap Command
The primary tool for bootstrapping is the cdk bootstrap command provided by the AWS CDK Toolkit. It deploys the CDKToolkit CloudFormation stack into one or more specified environments.
Sources: packages/aws-cdk/README.md:214-215
Command-Line Options
The behavior of the cdk bootstrap command can be customized with several options.
| Option | Description |
|---|---|
--toolkit-stack-name | Specifies a custom name for the bootstrap CloudFormation stack. |
--template | Use a custom CloudFormation template for bootstrapping instead of the default one. |
--show-template | Dumps the built-in bootstrap template to standard output, which can be saved and customized. |
--trust <accountId> | Grants cross-account permissions to the specified AWS account(s) to publish assets and deploy to the bootstrapped environment. Required for CI/CD pipelines. |
--cloudformation-execution-policies <policyArn> | A list of managed policy ARNs to attach to the CloudFormation Execution Role. Required when --trust is used. |
--termination-protection | Protects the bootstrap stack from accidental termination. Enabled by default. Can be disabled with --no-termination-protection. |
--public-access-block-configuration | Allows explicit configuration of the S3 bucket's public access block. Enabled by default. |
Sources: design/cdk-bootstrap.md:16-24, packages/aws-cdk/README.md:216, 224-230
Bootstrap Process Flow
The following diagram illustrates the sequence of actions when a user executes the cdk bootstrap command.
This diagram shows the user initiating the bootstrap command, the CDK CLI preparing and sending the request to AWS, and CloudFormation provisioning the resources.
Sources: packages/aws-cdk/lib/api/bootstrap/deploy-bootstrap.ts:25-78
Bootstrap Resources
The CDKToolkit stack provisions several key resources in the target environment. The exact resources depend on the options provided to the cdk bootstrap command.
The diagram below shows the core resources created by the bootstrap stack.
*Sources: design/cdk-bootstrap.md:27-46, packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml
Key Resources Summary
| Resource | Logical ID in Template | Description |
|---|---|---|
| S3 Bucket | StagingBucket | Stores file assets (e.g., Lambda code) and synthesized CloudFormation templates. |
| ECR Repository | ContainerAssetsRepository | Stores Docker image assets built by the CDK. |
| File Publishing Role | FilePublishingRole | IAM role with permissions to publish assets to the S3 bucket. |
| Image Publishing Role | ImagePublishingRole | IAM role with permissions to publish images to the ECR repository. |
| Deployment Action Role | DeploymentActionRole | IAM role assumed to execute CloudFormation deployment actions (Create/ExecuteChangeSet). |
| CloudFormation Execution Role | CloudFormationExecutionRole | IAM role assumed by the CloudFormation service to perform stack deployments. |
| Bootstrap Version Output | BootstrapVersion | A CloudFormation Output named AwsCdkBootstrapVersion that stores the version of the bootstrap stack. |
Sources: packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml:20, 116, 131, 172, 213, 254, 303, design/cdk-bootstrap.md:90-92
Below is a snippet from the bootstrap template defining the S3 Staging Bucket.
StagingBucket:
Type: AWS::S3::Bucket
Properties:
AccessControl: Private
BucketEncryption:
ServerSideEncryptionConfiguration:
- ServerSideEncryptionByDefault:
SSEAlgorithm: AES256
PublicAccessBlockConfiguration:
BlockPublicAcls: !Ref BlockPublicAccess
BlockPublicPolicy: !Ref BlockPublicAccess
IgnorePublicAcls: !Ref BlockPublicAccess
RestrictPublicBuckets: !Ref BlockPublicAccess
Sources: packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml:20-31
Cross-Account Trust for CI/CD
A primary motivation for the modern bootstrap stack is to enable secure cross-account deployments, a common pattern in CI/CD pipelines. The --trust option is used to establish a trust relationship between the environment being bootstrapped (e.g., production) and another AWS account (e.g., a tools/CI/CD account).
When --trust is used, the IAM roles created by the bootstrap stack (Publishing and Deployment roles) are configured to be assumable by principals from the trusted account. The --cloudformation-execution-policies option must also be provided to attach necessary permissions to the CloudFormationExecutionRole.
Sources: design/cdk-bootstrap.md:10-24
The following diagram illustrates the trust relationship established for a CI/CD pipeline.
Sources: design/cdk-bootstrap.md:38-46
Versioning and Compatibility
To manage changes to the bootstrap resources over time and ensure compatibility with the CDK CLI, the bootstrap stack includes a versioning mechanism. A CloudFormation output named AwsCdkBootstrapVersion is exported from the stack, containing a simple version number.
Before operations like cdk deploy, the CDK CLI checks this version:
- No Stack Found: Fails with a message that the environment needs to be bootstrapped.
- No Version Export: Assumes an old bootstrap version and fails, prompting the user to update by re-running
cdk bootstrap. - Version is Older than CLI: Fails, prompting the user to update.
- Version is Newer than CLI: Proceeds with a warning, as the bootstrap stack is more recent than the CLI.
This version check ensures that the necessary resources and permissions required by the current CDK version are present in the environment before attempting a deployment.
Sources: design/cdk-bootstrap.md:88-115
Customizing the Bootstrap Template
For advanced use cases with specific security or policy requirements, the default bootstrap template can be customized.
- Export the default template to a file using
cdk bootstrap --show-template > my-bootstrap-template.yaml. - Modify the
my-bootstrap-template.yamlfile as needed. - Deploy the customized template using
cdk bootstrap --template my-bootstrap-template.yaml.
This allows organizations to enforce their own standards for the resources that the CDK relies on for deployment.
Sources: packages/aws-cdk/README.md:224-230