Bootstraping your CDK environment is the foundational step before you can deploy any infrastructure.
Imagine you’ve written your first CDK app, you’re ready to cdk deploy, and you hit a wall. The CDK is trying to provision resources into your AWS account to manage your infrastructure, and it needs a place to store things like deployed CloudFormation stacks, asset manifests, and even the actual compiled CloudFormation templates. This bootstrapping process sets up that essential infrastructure. Without it, the CDK has nowhere to put the pieces it needs to orchestrate your deployments.
Let’s walk through what happens when you run cdk bootstrap.
First, the CDK CLI checks if a bootstrap bucket already exists in your target AWS account and region. If not, it’ll try to create one. This bucket is crucial for storing your application assets (like Lambda function code or container images) that will be uploaded during deployment.
Here’s a typical command you’d run:
cdk bootstrap aws://111122223333/us-east-1
This command tells the CDK to bootstrap your account 111122223333 in the us-east-1 region.
When it runs, you’ll see output similar to this:
✨ Found AWS account ID 111122223333 and region us-east-1
Executing bootstrap stack for account 111122223333 region us-east-1
✨ CFN_STACK_NAME: CDKToolkit
✨ S3_BUCKET_NAME: cdk-hnb659mfk-us-east-1-111122223333
✨ KMS_KEY_ARN: arn:aws:kms:us-east-1:111122223333:key/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
✨ IAM_ROLE_ARN: arn:aws:iam::111122223333:role/cdk-hnb659mfk-cloudformation-role-us-east-1-111122223333
✨ ASSET_BUCKET_NAME: cdk-hnb659mfk-assets-us-east-1-111122223333
The CDKToolkit CloudFormation stack is created. This stack is the heart of the bootstrap setup. It provisions several key resources:
- An S3 bucket (e.g.,
cdk-hnb659mfk-assets-us-east-1-111122223333): This is where your application assets (files, Docker images) are uploaded before being deployed. - A KMS encryption key: This key is used to encrypt the assets stored in the S3 bucket. By default, it’s an AWS-managed KMS key, but you can specify your own.
- An IAM role: This role grants the CDK Toolkit permission to deploy resources into your account. It’s essential for the CDK to create and manage your infrastructure.
- A CloudFormation-managed S3 bucket (e.g.,
cdk-hnb659mfk-us-east-1-111122223333): This bucket stores the CloudFormation templates themselves. When you deploy, the CDK uploads the generated CloudFormation template to this bucket, and then CloudFormation uses it to create or update your stack.
You can customize the bootstrap process. For instance, you might want to specify a custom KMS key for encryption, or a particular S3 bucket name.
cdk bootstrap \
--bucket-name my-custom-cdk-bucket \
--kms-key-arn arn:aws:kms:us-east-1:111122223333:key/my-kms-key-id \
aws://111122223333/us-east-1
This allows you to enforce specific security policies or naming conventions for your bootstrap resources.
The most surprising thing about the bootstrap process is that it’s not a one-time event for a given account/region pair. If you update the CDK CLI version significantly, you might need to re-bootstrap. The CDK CLI uses a specific "lookout version" for bootstrapping, and if your local CLI version’s lookout version is newer than what’s currently deployed in your CDKToolkit stack, the CLI will prompt you to re-bootstrap to ensure compatibility with the latest features and security patches. This ensures that the underlying infrastructure managed by the CDKToolkit stack keeps pace with the capabilities of your CDK CLI.
After bootstrapping, you can confidently run cdk deploy. The CDK will now have the necessary S3 buckets and IAM roles in place to upload your assets and deploy your CloudFormation stacks.
The next thing you’ll likely encounter is managing multiple environments, which often involves bootstrapping each one.