AWS CDK Bootstrapping

To Nha Notes | April 25, 2022, 2:08 p.m.

Deploying AWS CDK apps into an AWS environment (a combination of an AWS account and region) may require that you provision resources the AWS CDK needs to perform the deployment. These resources include an Amazon S3 bucket for storing files and IAM roles that grant permissions needed to perform deployments. The process of provisioning these initial resources is called bootstrapping.

An environment needs to be bootstrapped if any of the following apply.

• An AWS CDK stack being deployed uses Assets.

• An AWS CloudFormation template generated by the app exceeds 50 kilobytes.

The required resources are defined in a AWS CloudFormation stack, called the bootstrap stack, which is usually named CDKToolkit. Like any AWS CloudFormation stack, it appears in the AWS CloudFormation console once it has been deployed.

If you attempt to deploy an AWS CDK application that requires bootstrap resources into an environment that does not have them, you receive an error message telling you that you need to bootstrap the environment.

If you are using CDK Pipelines to deploy into another account's environment, and you receive a message like the following:

Policy contains a statement with one or more invalid principals

This error message means that the appropriate IAM roles do not exist in the other environment, which is most likely caused by a lack of bootstrapping.

Note:

Do not delete and recreate an account's bootstrap stack if you are using CDK Pipelines to deploy into that account. The pipeline will stop working. To update the bootstrap stack to a new version, instead re-run cdk bootstrap to update the bootstrap stack in place.

How to bootstrap

Bootstrapping with the AWS CDK Toolkit:

cdk bootstrap aws://ACCOUNT-NUMBER-1/REGION-1 aws://ACCOUNT-NUMBER-2/REGION-2 ...
cdk bootstrap aws://123456789012/us-east-1
cdk bootstrap 123456789012/us-east-1 123456789012/us-west-1
cdk bootstrap --profile <PROFILE>

Bootstrapping from the AWS CloudFormation template:

cdk bootstrap --show-template > bootstrap-template.yaml
aws cloudformation create-stack \
  --stack-name CDKToolkit \
  --template-body file://bootstrap-template.yaml

The template is also available in the AWS CDK GitHub repository

Notes:

Some time, we may get below errors, run rebootstrap to fix it.

• "Building assets failed: Error: Building Assets Failed: Error: Need to perform AWS calls for account"
• "current credentials could not be used to assume 'arn:aws:iam::<ACCOUNT_NUMBER>:role/cdk-xxx-deploy-role-<ACCOUNT_NUMBER>-ap-northeast-1', but are for the right account. Proceeding anyway."

cdk bootstrap --profile <PROFILE>

References

https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html