AWS CDK Guide

Define AWS infrastructure using real programming languages — TypeScript, Python, Java, C#, or Go. AWS CDK synthesizes your code into CloudFormation and deploys it with a single command.

What is AWS CDK?

AWS Cloud Development Kit (CDK) is an open-source infrastructure-as-code framework that lets you define cloud resources using general-purpose programming languages instead of YAML or JSON. Released by AWS in 2019 and now at v2, CDK compiles your code into CloudFormation templates during a synthesis step, then uses CloudFormation's battle-tested engine to provision and update resources. This means you get all the safety guarantees of CloudFormation (drift detection, rollbacks, change sets) plus the developer ergonomics of modern languages: type safety, IDE auto-complete, loops, conditionals, unit tests, and package management via npm or pip.

The core abstraction in CDK is the Construct — a reusable cloud component that can represent a single resource (like an S3 bucket) or a complex pattern (like a load-balanced ECS service with autoscaling, logging, and IAM). Constructs are organized into Stacks, which map 1:1 to CloudFormation stacks. Stacks live inside an App, the root of every CDK project.

Key Features

• Constructs Library — 300+ L2 constructs with secure defaults and helper methods (grant*, metric*, addToPolicy)
• L1 / L2 / L3 Construct Levels — raw CloudFormation → opinionated abstractions → full architectural patterns
• cdk synth / diff / deploy — synthesize templates, preview changes, and deploy with one command
• CDK Pipelines — self-mutating CI/CD pipelines with multi-stage, multi-account deployments
• Assets — bundle Lambda code, Docker images, and S3 files automatically during synthesis
• Escape Hatches — override any CloudFormation property via addOverride() when needed
• Aspects — apply cross-cutting logic (tagging, security checks) across an entire app tree
• Unit Testing — test infrastructure with Jest or pytest using assertions against synthesized templates

Getting Started: Your First CDK App

Install the CDK CLI and scaffold a new TypeScript project:

npm install -g aws-cdk
cdk init app --language typescript
npm install

Define a stack with an S3 bucket and Lambda function:

// lib/my-app-stack.ts
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 s3n from 'aws-cdk-lib/aws-s3-notifications';
import { Construct } from 'constructs';

export class MyAppStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // L2 construct — S3 bucket with secure defaults
    const bucket = new s3.Bucket(this, 'DataBucket', {
      bucketName: `my-app-data-${this.account}`,
      versioned: true,
      encryption: s3.BucketEncryption.S3_MANAGED,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      removalPolicy: cdk.RemovalPolicy.RETAIN,
    });

    // L2 construct — Lambda function with bundled code
    const processor = new lambda.Function(this, 'Processor', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      environment: {
        BUCKET_NAME: bucket.bucketName,
      },
      timeout: cdk.Duration.seconds(30),
      memorySize: 512,
    });

    // Grant Lambda read/write access to the bucket (manages IAM automatically)
    bucket.grantReadWrite(processor);

    // Trigger Lambda on S3 object uploads
    bucket.addEventNotification(
      s3.EventType.OBJECT_CREATED,
      new s3n.LambdaDestination(processor)
    );

    // Output the bucket name
    new cdk.CfnOutput(this, 'BucketName', { value: bucket.bucketName });
  }
}

Synthesize and deploy:

cdk bootstrap aws://ACCOUNT_ID/us-east-1   # one-time setup
cdk synth                                   # generate CloudFormation template
cdk diff                                    # preview changes
cdk deploy                                  # deploy to AWS

Using L3 Pattern Constructs

import * as ecs_patterns from 'aws-cdk-lib/aws-ecs-patterns';
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ec2 from 'aws-cdk-lib/aws-ec2';

// One L3 construct provisions: VPC, ECS cluster, Fargate service,
// Application Load Balancer, target group, IAM roles, CloudWatch logs
const loadBalancedService = new ecs_patterns.ApplicationLoadBalancedFargateService(
  this, 'ApiService', {
    cluster: new ecs.Cluster(this, 'Cluster', { vpc }),
    cpu: 512,
    memoryLimitMiB: 1024,
    desiredCount: 2,
    taskImageOptions: {
      image: ecs.ContainerImage.fromRegistry('nginx:latest'),
      containerPort: 80,
    },
    publicLoadBalancer: true,
  }
);

// Add autoscaling
const scaling = loadBalancedService.service.autoScaleTaskCount({ maxCapacity: 10 });
scaling.scaleOnCpuUtilization('CpuScaling', { targetUtilizationPercent: 70 });

CDK vs Alternatives

Use Cases

• Teams already using TypeScript or Python who want IaC in the same language as their application code
• Complex infrastructure requiring loops, conditionals, and dynamic resource generation
• AWS-native shops wanting tight integration with CloudFormation, CodePipeline, and AWS services
• Building internal platform modules — encapsulate security baselines as reusable L3 constructs
• Serverless applications where CDK handles Lambda bundling, API Gateway config, and IAM permissions automatically
• Multi-account, multi-region deployments managed via CDK Pipelines with environment promotion gates

Pros and Cons