What is AWS CDK? A Complete Guide for Developers

If you've ever spent an afternoon wrestling with a 1,500-line CloudFormation YAML file, only to realize you had a missing comma on line 847, you already understand why AWS CDK exists.

The AWS Cloud Development Kit (AWS CDK) is an open-source framework that lets you define your entire cloud infrastructure using real programming languages like TypeScript, Python, Java, C#, or Go. No more raw YAML or JSON templates. No more copy-pasting resource definitions. Just code, the kind you already know how to write, test, and reuse.

Under the hood, CDK still uses AWS CloudFormation to actually deploy your resources. But instead of writing CloudFormation directly, you write code that generates that CloudFormation for you. The result is infrastructure that's faster to write, easier to maintain, and far less error-prone.

What is Infrastructure as Code (IaC)?

Before diving into CDK, it's worth understanding the concept it's built on. Infrastructure as Code (IaC) means treating your cloud resources, servers, databases, networking, and storage exactly like application code. You describe what you want in a file, commit it to version control, and deploy it repeatably.

The benefits are significant: you get a full history of infrastructure changes, the ability to spin up identical environments on demand, and a way to review and approve changes before they go live, the same workflow you'd apply to any other code PR.

AWS CDK is one of the most developer-friendly IaC tools available today. According to Gartner, 80% of technology products will be built by non-traditional developers by 2026, and tools like CDK are a big part of what's making that possible.

How AWS CDK Works?

The CDK workflow has three stages:

1. Write - You define your infrastructure in code using CDK constructs (more on those shortly). This is where you spend most of your time.

2. Synthesize - Running cdk synth converts your code into one or more AWS CloudFormation templates. This step happens locally before anything touches your AWS account.

3. Deploy - Running cdk deploy hands those CloudFormation templates to AWS, which handles the actual provisioning of resources.

This synthesis step is powerful; you can inspect the generated CloudFormation before deploying, catch issues early, and even use CDK in CI/CD pipelines where the template gets reviewed before production goes near it.

The Core Building Blocks: Constructs, Stacks, and Apps

1.  Constructs

Constructs are the fundamental units of a CDK application. Think of them as reusable cloud components; they can represent a single AWS resource (like an S3 bucket) or a group of resources wired together to perform a specific function.

What most articles miss is that CDK has three levels of constructs, each offering a different trade-off between control and convenience:

2. L1 Constructs (Direct CloudFormation mapping)

L1 constructs (identifiable by the Cfn prefix, like CfnBucket) are auto-generated directly from the CloudFormation resource specification. Every property maps 1:1 to a CloudFormation property. 

This gives you maximum control, but requires you to configure everything manually, including things like IAM permissions that L2 constructs handle for you automatically.

Use L1 when you need a CloudFormation feature that hasn't been wrapped into an L2 construct yet.

// L1: Low-level, verbose, you configure everything yourself
const bucket = new s3.CfnBucket(this, 'MyBucket', {
  versioningConfiguration: {
    status: 'Enabled'
  }
});

3. L2 Constructs (The sweet spot)

L2 constructs are hand-crafted by the CDK team. They wrap individual AWS services with sensible defaults, built-in security policies, and an intent-based API. Most of the time, this is what you'll be working with. The CDK team has already applied AWS best practices, so you don't have to.

// L2: Cleaner, safer, opinionated defaults applied for you
const bucket = new s3.Bucket(this, 'MyBucket', {
  versioned: true,
  encryption: s3.BucketEncryption.S3_MANAGED,
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
});

4. L3 Constructs (High-level patterns)

L3 constructs (also called patterns) bundle multiple AWS services together into a ready-to-use architecture. For example, ApplicationLoadBalancedFargateService from the aws-ecs-patterns library creates a VPC, ECS cluster, Fargate service, load balancer, and the IAM roles connecting them, in about 10 lines of code.

A practical rule of thumb: start with L2, drop to L1 when you hit a wall, and promote repeated L2 patterns into L3 constructs when you find yourself copy-pasting across stacks.

Stacks

A Stack is the deployable unit in CDK, it maps directly to a CloudFormation stack. All the constructs you define live inside a Stack. One CDK app can contain multiple stacks, which is useful for separating concerns (a networking stack, an app stack, a data stack) or deploying the same infrastructure across multiple environments.

export class MyAppStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    // All your constructs go here
    new s3.Bucket(this, 'AppStorage', {
      versioned: true,
    });
  }
}

Apps

An App is the root of your CDK project; it's the container that holds one or more stacks. You instantiate your stacks inside an App, and the App orchestrates synthesis and deployment.

Getting Started: Installation and First Deploy

You'll need Node.js installed. Then:

npm install -g aws-cdk

Create a new CDK project:

mkdir my-cdk-app && cd my-cdk-app
cdk init app --language=typescript

Bootstrap your AWS environment (sets up the S3 bucket and IAM roles CDK needs to deploy):

cdk bootstrap aws://<YOUR_ACCOUNT_ID>/<YOUR_REGION>

You only need to run bootstrap once per account/region. After that, it's just cdk deploy every time you want to push changes.

A Practical Example: S3 + Lambda + API Gateway

Here's what a real-world CDK stack looks like: an S3 bucket for storage, a Lambda function to process requests, and an API Gateway to expose it:

import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import { Construct } from 'constructs';
export class MyApiStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    // Storage bucket
    const bucket = new s3.Bucket(this, 'DataBucket', {
      versioned: true,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });
    // Lambda function with env var injection
    const handler = new lambda.Function(this, 'ApiHandler', {
      runtime: lambda.Runtime.NODEJS_18_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      environment: {
        BUCKET_NAME: bucket.bucketName,
      },
    });
    // Grant Lambda read/write access — one line, no manual IAM policies
    bucket.grantReadWrite(handler);
    // API Gateway wired to Lambda
    const api = new apigateway.RestApi(this, 'MyApi');
    api.root
      .addResource('items')
      .addMethod('GET', new apigateway.LambdaIntegration(handler));
  }
}

Notice bucket.grantReadWrite(handler), that single line creates and attaches the correct IAM policy automatically. In raw CloudFormation, this would be 20+ lines of JSON. This is what L2 constructs for you.

AWS CDK vs CloudFormation vs Terraform

Understanding where CDK fits in the IaC landscape helps you pick the right tool.

CDK vs CloudFormation

CDK generates CloudFormation, so you're not replacing it, you're adding a better authoring experience on top.

The key advantage is that CDK gives you loops, conditionals, type safety, IDE autocomplete, and unit testing, none of which you get with raw YAML. If you're already using CloudFormation, adopting CDK is an upgrade, not a migration.

CDK vs Terraform

Terraform supports over 3,000 providers as of 2026, making it the go-to choice for multi-cloud infrastructure. CDK is the stronger pick for AWS-native teams; the L2/L3 constructs, automatic state management via CloudFormation, and deep AWS service integration are hard to match.

If your entire stack lives in AWS and your team writes TypeScript or Python, CDK will likely feel more natural and move faster day-to-day.

When to Use AWS CDK?

CDK is a great fit when:

• Your team writes TypeScript, Python, Java, or another CDK-supported language and wants to stay in that ecosystem
• You're building on AWS exclusively and want to leverage L2/L3 constructs for faster development
• You need reusable infrastructure components shared across teams or multiple environments
• You want to apply software practices (unit tests, code reviews, CI/CD) to your infrastructure

CDK isn’t a great fit when:

• Your infrastructure spans multiple cloud providers, Terraform's breadth wins here
• Your team is more comfortable with YAML and doesn't want to introduce a new language context
• You need constructs for a very new AWS service that CDK hasn't added L2 support for yet (you can still use L1, but it loses some of the key benefits)

Frequently Asked Questions

What programming languages does AWS CDK support?

TypeScript, JavaScript, Python, Java, C#/.Net, and Go. TypeScript is the most widely used and has the richest community resources, but all six languages have full framework support.

Does AWS CDK replace CloudFormation?

No — it works with it. CDK synthesizes your code into CloudFormation templates, which AWS then uses to provision your resources. You still get all of CloudFormation's reliability and rollback capabilities underneath.

What's the difference between CDK v1 and v2?

CDK v1 entered maintenance in June 2022 and ended support in June 2023. CDK v2 is the current version. The main change is that all AWS service constructs are bundled into a single aws-cdk-lib package, simplifying dependency management.

Can I use CDK with existing CloudFormation templates?

Yes. CDK can import existing CloudFormation resources, and you can also use the CfnInclude class to include existing CloudFormation templates directly inside a CDK stack.

Is AWS CDK open source?

Yes, the full AWS CDK source is available on GitHub. The community actively contributes constructs, and the Construct Hub is where you can find and share reusable CDK libraries.

Final Thoughts

AWS CDK closes the gap between how developers write application code and how they manage infrastructure. Instead of learning CloudFormation's YAML quirks or manually managing IAM policies, you write infrastructure the same way you write everything else, in a typed, testable, version-controlled programming language.

The L1/L2/L3 construct model is the real unlock: start with L2 constructs, and you'll be surprised how little code it takes to build production-grade, secure infrastructure. As your patterns mature, promote them into L3 constructs that your whole team can reuse.

If you're building on AWS and planning to scale your cloud team or hire developers for infrastructure projects, AWS CDK can help standardize deployments and speed up development from the start.