AWS CDK: Infrastructure as Code with Programming Languages

You've been burned by a 10,000-line CloudFormation template that no one dares to touch. A single typo in YAML took down production for 45 minutes. You're not alone—teams everywhere are ditching brittle templates for AWS CDK. CDK lets you define infrastructure in TypeScript, Python, Java, or C#, compiling down to CloudFormation. But it's not just syntax sugar: it's a paradigm shift. With constructs, you encapsulate best practices into reusable components. With unit tests, you validate infrastructure logic before deployment. And with the ability to use loops and conditionals, you eliminate copy-paste errors. This isn't about avoiding YAML—it's about treating infrastructure as real software. In this article, we'll cover CDK's core concepts, common pitfalls (like stateful resource deletion), and production patterns that keep your stacks safe.

Why AWS CDK Over Plain CloudFormation

AWS CloudFormation is powerful but verbose. A typical VPC with subnets, route tables, and NAT gateways can exceed 500 lines of YAML. The AWS Cloud Development Kit (CDK) replaces that with ~50 lines of TypeScript, Python, or Java. More importantly, CDK brings software engineering practices to infrastructure: loops, conditionals, functions, and unit tests. You can define reusable constructs, enforce policies with custom rules, and version your infrastructure alongside your application code. The trade-off is that CDK synthesizes to CloudFormation, so you inherit its deployment model and limits. But for teams that already write code, CDK reduces boilerplate and improves maintainability. In production, we've seen CDK cut infrastructure provisioning time by 60% and eliminate copy-paste errors across environments.

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

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

    const vpc = new ec2.Vpc(this, 'TheCodeForgeVpc', {
      maxAzs: 2,
      natGateways: 1,
      subnetConfiguration: [
        { cidrMask: 24, name: 'public', subnetType: ec2.SubnetType.PUBLIC },
        { cidrMask: 24, name: 'private', subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
      ],
    });

    new cdk.CfnOutput(this, 'VpcId', { value: vpc.vpcId });
  }
}

Core Concepts: App, Stack, and Construct

Every CDK project starts with an App, which contains one or more Stacks. A Stack maps to a CloudFormation stack and is the unit of deployment. Constructs are the building blocks: they can be low-level (like CfnBucket) or high-level (like Bucket with auto-configuration). The L2 constructs (e.g., s3.Bucket) provide sensible defaults and helper methods. L3 constructs are patterns like ecs.Patterns.ApplicationLoadBalancedFargateService. You compose constructs to build your infrastructure. In production, we always use L2 constructs unless we need raw CloudFormation resources. They handle permissions, dependencies, and resource names automatically. Never use L1 constructs unless you're extending an unsupported service.

import * as cdk from 'aws-cdk-lib';
import { VpcStack } from './vpc-stack';
import { WebAppStack } from './webapp-stack';

const app = new cdk.App();
const vpcStack = new VpcStack(app, 'VpcStack', {
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
});
new WebAppStack(app, 'WebAppStack', {
  vpc: vpcStack.vpc,
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
});
app.synth();

Setting Up a CDK Project for Production

Initialize a CDK project with cdk init app --language typescript. This creates a standard structure with bin/, lib/, and test/ directories. For production, add cdk-nag for compliance checks, eslint for code quality, and jest for unit tests. Configure cdk.json with context variables for environment-specific settings (e.g., dev, prod). Use cdk.context.json for runtime context like AZs. Always pin the CDK version in package.json to avoid breaking changes. In CI/CD, run cdk synth and cdk deploy with --require-approval never only after manual approval. We use cdk watch for development but never in production pipelines.

mkdir my-cdk-app && cd my-cdk-app
cdk init app --language typescript
npm install @aws-cdk/aws-s3 @aws-cdk/aws-ec2 cdk-nag eslint jest @types/jest
# Add cdk-nag to bin/app.ts: require('cdk-nag').AwsSolutionsChecks.addChecks(app);
echo '{
  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
  "context": {
    "@aws-cdk/core:enableStackNameDuplicates": true,
    "aws-cdk:enableDiffNoFail": true
  }
}' > cdk.json

Writing Reusable Constructs

Reusable constructs are the heart of CDK. Create a construct by extending cdk.Construct and accepting scope, id, and props. Expose properties like vpc or bucket for other constructs to consume. For example, a SecureBucket construct that enforces encryption, versioning, and access logging. Use Grant methods to manage permissions instead of raw IAM policies. In production, we maintain a library of internal constructs shared across teams via a private npm registry. This ensures consistency: every S3 bucket has the same security posture. Avoid over-parameterization — expose only what's necessary. Too many props make constructs hard to use.

import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as kms from 'aws-cdk-lib/aws-kms';

export interface SecureBucketProps {
  encryptionKey?: kms.IKey;
  versioned?: boolean;
}

export class SecureBucket extends cdk.Construct {
  public readonly bucket: s3.Bucket;

  constructor(scope: cdk.Construct, id: string, props?: SecureBucketProps) {
    super(scope, id);

    const key = props?.encryptionKey || new kms.Key(this, 'Key', {
      enableKeyRotation: true,
    });

    this.bucket = new s3.Bucket(this, 'Bucket', {
      encryption: s3.BucketEncryption.KMS,
      encryptionKey: key,
      versioned: props?.versioned ?? true,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      enforceSSL: true,
      serverAccessLogsPrefix: 'access-logs/',
    });
  }
}

Managing Environments with Context and Stages

Use CDK context to pass environment-specific values like account IDs, domain names, or feature flags. Define context in cdk.json or pass via -c key=value during synthesis. For multi-environment deployments (dev, staging, prod), use a Stage construct that groups stacks. Each stage can have different context. Use cdk deploy --context env=prod to select the environment. In production, we use a PipelineStack that deploys stages sequentially with manual approval gates. Never hardcode environment values in stack code — always use context or SSM Parameter Store.

import * as cdk from 'aws-cdk-lib';
import * as pipelines from 'aws-cdk-lib/pipelines';
import { WebAppStage } from './webapp-stage';

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

    const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
      synth: new pipelines.ShellStep('Synth', {
        input: pipelines.CodePipelineSource.gitHub('myorg/myapp', 'main'),
        commands: ['npm ci', 'npm run build', 'npx cdk synth'],
      }),
    });

    const devStage = new WebAppStage(this, 'Dev', {
      env: { account: '111111111111', region: 'us-east-1' },
    });
    pipeline.addStage(devStage);

    const prodStage = new WebAppStage(this, 'Prod', {
      env: { account: '222222222222', region: 'us-east-1' },
    });
    pipeline.addStage(prodStage, {
      pre: [new pipelines.ManualApprovalStep('PromoteToProd')],
    });
  }
}

Testing CDK Infrastructure

CDK supports three testing levels: unit tests with @aws-cdk/assertions, snapshot tests, and integration tests. Unit tests verify that constructs create the expected CloudFormation resources. Snapshot tests catch unintended changes. Integration tests deploy real resources and validate behavior. In production, we write unit tests for every custom construct. Use Template.fromStack(stack) to get the synthesized template and assert on resource counts, properties, and policies. Snapshot tests are useful but brittle — use them sparingly. Integration tests run in a separate AWS account and are triggered by pull requests. Never skip tests for infrastructure changes.

import { Template } from '@aws-cdk/assertions';
import * as cdk from 'aws-cdk-lib';
import { SecureBucket } from '../lib/secure-bucket';

test('SecureBucket enforces encryption', () => {
  const app = new cdk.App();
  const stack = new cdk.Stack(app, 'TestStack');
  new SecureBucket(stack, 'TestBucket');

  const template = Template.fromStack(stack);
  template.hasResourceProperties('AWS::S3::Bucket', {
    BucketEncryption: {
      ServerSideEncryptionConfiguration: [{
        ServerSideEncryptionByDefault: {
          SSEAlgorithm: 'aws:kms',
        },
      }],
    },
  });
});

Deploying with CI/CD Pipelines

CDK Pipelines (formerly CDK Pipelines) is the recommended way to deploy CDK apps. It creates a self-mutating pipeline: the pipeline definition is itself CDK code. When you update the pipeline stack, it updates itself. Use CodePipeline or CodeBuild for the synth action. For production, add a ShellStep that runs cdk synth and cdk deploy. Use --require-approval never only after manual approval gates. Store pipeline configuration in context. Never use cdk deploy from a developer's machine for production — always use the pipeline. We've seen too many 'works on my machine' failures.

import * as cdk from 'aws-cdk-lib';
import * as pipelines from 'aws-cdk-lib/pipelines';
import { MyApplication } from './my-app';

const app = new cdk.App();

const pipelineStack = new cdk.Stack(app, 'PipelineStack', {
  env: { account: '111111111111', region: 'us-east-1' },
});

const pipeline = new pipelines.CodePipeline(pipelineStack, 'Pipeline', {
  pipelineName: 'MyAppPipeline',
  synth: new pipelines.ShellStep('Synth', {
    input: pipelines.CodePipelineSource.gitHub('myorg/myapp', 'main'),
    commands: ['npm ci', 'npm run build', 'npx cdk synth'],
  }),
});

const devStage = new MyApplication(app, 'Dev', {
  env: { account: '111111111111', region: 'us-east-1' },
});
pipeline.addStage(devStage);

app.synth();

Handling Secrets and Sensitive Data

Never hardcode secrets in CDK code. Use AWS Secrets Manager or SSM Parameter Store. CDK has built-in support for referencing secrets: Secret.fromSecretNameV2 or StringParameter.fromStringParameterName. For database passwords, use rds.DatabaseSecret which auto-generates and rotates passwords. In production, we use cdk-secrets-manager construct to create secrets with rotation. Always grant least-privilege access to secrets. Use secret.grantRead(lambda) instead of wildcard IAM policies. Rotate secrets regularly. We've seen teams embed API keys in context files committed to git — that's a breach waiting to happen.

import * as cdk from 'aws-cdk-lib';
import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
import * as lambda from 'aws-cdk-lib/aws-lambda';

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

    const dbSecret = new secretsmanager.Secret(this, 'DbSecret', {
      secretName: 'prod/db/password',
      generateSecretString: {
        secretStringTemplate: JSON.stringify({ username: 'admin' }),
        generateStringKey: 'password',
        excludePunctuation: true,
      },
    });

    const fn = new lambda.Function(this, 'MyFunction', {
      runtime: lambda.Runtime.NODEJS_18_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      environment: {
        DB_SECRET_ARN: dbSecret.secretArn,
      },
    });

    dbSecret.grantRead(fn);
  }
}

Cost Management and Tagging

Tagging is essential for cost allocation. Use cdk.Tags.of(scope).add('key', 'value') to apply tags to all resources in a stack. For production, enforce tagging with cdk-nag rules. Use AwsSolutions-Tagging rule to require specific tags like Environment, CostCenter, and Owner. Also set removal policies: RemovalPolicy.DESTROY for non-production, RemovalPolicy.RETAIN for production data. Use cdk destroy for ephemeral environments. We've seen teams forget to tag resources and then struggle to identify cost spikes. Automate tagging with a custom aspect that applies tags to all constructs.

import * as cdk from 'aws-cdk-lib';
import { IConstruct } from 'constructs';

export class TaggingAspect implements cdk.IAspect {
  constructor(private readonly tags: Record<string, string>) {}

  visit(node: IConstruct): void {
    if (cdk.CfnResource.isCfnResource(node)) {
      Object.entries(this.tags).forEach(([key, value]) => {
        node.tags.setTag(key, value);
      });
    }
  }
}

// Usage in app:
// const app = new cdk.App();
// cdk.Aspects.of(app).add(new TaggingAspect({ Environment: 'prod', CostCenter: '12345' }));

Advanced Patterns: Custom Resources and Escape Hatches

Sometimes CDK doesn't support a feature. Use escape hatches: (resource.node.defaultChild as CfnBucket).addPropertyOverride('VersioningConfiguration.Status', 'Suspended'). For custom logic, use CustomResource backed by a Lambda function. This is useful for tasks like DNS validation or database seeding. In production, we use custom resources to register SSL certificates with DNS validation. Be careful: custom resources are hard to debug. Always set a timeout and handle rollbacks. Use Provider framework for idempotency. We've seen custom resources fail silently and leave infrastructure in an inconsistent state.

import * as cdk from 'aws-cdk-lib';
import * as cr from 'aws-cdk-lib/custom-resources';
import * as lambda from 'aws-cdk-lib/aws-lambda';

export class DnsValidationRecord extends cdk.Construct {
  constructor(scope: cdk.Construct, id: string, props: { domain: string; zoneId: string }) {
    super(scope, id);

    const onEvent = new lambda.Function(this, 'OnEvent', {
      runtime: lambda.Runtime.NODEJS_18_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda/custom-resource'),
    });

    const provider = new cr.Provider(this, 'Provider', {
      onEventHandler: onEvent,
    });

    new cdk.CustomResource(this, 'Resource', {
      serviceToken: provider.serviceToken,
      properties: {
        Domain: props.domain,
        ZoneId: props.zoneId,
      },
    });
  }
}

Monitoring and Observability

CDK can set up monitoring as part of your infrastructure. Use aws-cloudwatch constructs to create dashboards, alarms, and logs. For example, create an alarm when a Lambda function errors exceed a threshold. Use aws-ec2 flow logs for VPC traffic. In production, we use cdk-dashboards to create a unified dashboard per stack. Set up AWS::Lambda::Function with ReservedConcurrentExecutions to limit concurrency. Use aws-s3 server access logs. Never skip monitoring — it's the only way to detect issues before customers do. We've seen teams deploy without alarms and only discover outages from support tickets.

import * as cdk from 'aws-cdk-lib';
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
import * as lambda from 'aws-cdk-lib/aws-lambda';

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

    const fn = new lambda.Function(this, 'MyFunction', {
      runtime: lambda.Runtime.NODEJS_18_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
    });

    const errorAlarm = new cloudwatch.Alarm(this, 'ErrorAlarm', {
      metric: fn.metricErrors(),
      threshold: 5,
      evaluationPeriods: 1,
      alarmDescription: 'Lambda function errors exceeded threshold',
    });

    const dashboard = new cloudwatch.Dashboard(this, 'Dashboard', {
      dashboardName: 'MyAppDashboard',
    });
    dashboard.addWidgets(new cloudwatch.GraphWidget({
      title: 'Lambda Errors',
      left: [fn.metricErrors()],
    }));
  }
}

Migration from CloudFormation to CDK

Migrating existing CloudFormation stacks to CDK requires care. Use cdk import to bring existing resources under CDK management. First, write a CDK stack that matches the current template exactly. Then run cdk import to sync state. After import, you can refactor. For large migrations, use cdk diff to compare. In production, we migrated a 50-stack environment by importing one stack at a time. Never delete and recreate resources — use import. We've seen teams try to recreate stacks and accidentally delete production databases. Always test migration in a non-production account first.

# 1. Write CDK stack that matches existing CloudFormation
# 2. Run cdk import
cdk import --stack-name ExistingStack
# 3. Verify no diff
cdk diff --stack-name ExistingStack
# 4. Now you can refactor the CDK code and deploy changes
cdk deploy --stack-name ExistingStack