This is Chapter 1 of the Infrastructure as Code with AWS CDK series. Before writing any stack code, the project needs to be initialised and the AWS account needs to be bootstrapped. This covers both.

Prerequisites

  • Python 3.9+
  • Node.js 18+ (CDK CLI is a Node package)
  • AWS CLI v2 configured with valid credentials - see Connect to AWS SSO and SSH into EC2 Instance
  • An AWS account with permissions to create IAM roles, S3 buckets, and CloudFormation stacks

Install the CDK CLI globally:

npm install -g aws-cdk
cdk --version

Initialise project

Create a new directory and initialise a CDK Python project inside it:

mkdir my-cdk-app && cd my-cdk-app
cdk init app --language python

This scaffolds the project with a virtual environment, a sample stack, and a cdk.json config file.

Activate the virtual environment and install dependencies:

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\activate.ps1

pip install -r requirements.txt

Directory structure

After initialisation the project looks like this:

my-cdk-app/
├── app.py                  # CDK app entry point
├── cdk.json                # CDK config and context
├── requirements.txt        # Python dependencies
├── requirements-dev.txt    # Dev dependencies (e.g. pytest)
├── .venv/                  # Python virtual environment
└── my_cdk_app/
    ├── __init__.py
    └── my_cdk_app_stack.py # Default stack

app.py is where the CDK app is defined and stacks are instantiated. my_cdk_app_stack.py is where resources are defined. The folder and class names match the project name passed to cdk init.

Bootstrap AWS account

CDK needs a one-time setup in each AWS account and region it deploys to. Bootstrapping creates an S3 bucket (for assets) and IAM roles (for deployments) in the account:

cdk bootstrap aws://123456789012/us-east-1

Replace 123456789012 with your account ID and us-east-1 with your target region. If credentials are already configured via AWS CLI or SSO, the account ID can be omitted:

cdk bootstrap

This only needs to run once per account/region combination. Re-running it is safe - it updates the bootstrap stack if needed.

Synth and deploy

CDK compiles Python into CloudFormation before deploying. Run synth to see the generated CloudFormation template:

cdk synth

This outputs a CloudFormation template to cdk.out/. Use it to verify what CDK will create before deploying.

Deploy the stack:

cdk deploy

CDK shows a diff of changes and prompts for confirmation before creating or modifying any IAM resources.

Verify

After deploying, the stack appears in CloudFormation in the AWS console. Check:

  • CloudFormation > Stacks > MyCdkAppStack - status should be CREATE_COMPLETE
  • S3 > Buckets - the CDK bootstrap bucket should be visible (cdk-hnb659fds-assets-...)

To tear down the stack:

cdk destroy

Notes

  1. The bootstrap stack itself is a CloudFormation stack - it can be viewed and managed in the console under CDKToolkit
  2. Each AWS account + region combination needs its own bootstrap - e.g. deploying to both us-east-1 and ap-southeast-2 requires bootstrapping both
  3. cdk synth is useful for debugging - the generated CloudFormation is in cdk.out/ and can be inspected directly
  4. The .venv/ folder and cdk.out/ should be in .gitignore - they are added automatically by cdk init