CDK Deployment Patterns for Enterprise Applications

The AWS Cloud Development Kit brings the full power of programming languages to infrastructure definition. But using CDK effectively at enterprise scale requires more than translating CloudFormation templates into TypeScript. This guide covers the deployment patterns that make CDK manageable across teams, accounts, and environments.

Custom L3 Constructs

CDK organizes constructs into three levels: L1 (CloudFormation resources), L2 (opinionated defaults), and L3 (patterns combining multiple resources). Building custom L3 constructs encapsulates your organization's infrastructure standards.

import { Construct } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as logs from 'aws-cdk-lib/aws-logs';
import * as iam from 'aws-cdk-lib/aws-iam';

export interface SecureFunctionProps {
  entry: string;
  handler?: string;
  memorySize?: number;
  environment?: Record<string, string>;
  reservedConcurrency?: number;
}

export class SecureFunction extends Construct {
  public readonly function: lambda.Function;

  constructor(scope: Construct, id: string, props: SecureFunctionProps) {
    super(scope, id);

    this.function = new lambda.Function(this, 'Function', {
      runtime: lambda.Runtime.NODEJS_20_X,
      architecture: lambda.Architecture.ARM_64,
      handler: props.handler ?? 'index.handler',
      code: lambda.Code.fromAsset(props.entry),
      memorySize: props.memorySize ?? 512,
      timeout: Duration.seconds(30),
      tracing: lambda.Tracing.ACTIVE,
      insightsVersion: lambda.LambdaInsightsVersion.VERSION_1_0_229_0,
      environment: {
        NODE_OPTIONS: '--enable-source-maps',
        POWERTOOLS_SERVICE_NAME: id,
        ...props.environment,
      },
      reservedConcurrentExecutions: props.reservedConcurrency,
    });

    // Enforce log retention (don't keep logs forever)
    new logs.LogGroup(this, 'LogGroup', {
      logGroupName: `/aws/lambda/${this.function.functionName}`,
      retention: logs.RetentionDays.THIRTY_DAYS,
      removalPolicy: RemovalPolicy.DESTROY,
    });
  }
}

This construct encodes organizational decisions: ARM64 architecture, active tracing, Lambda Insights, structured logging, and 30-day log retention. Every Lambda function in the organization inherits these defaults, and they can be updated in one place.

CDK Aspects for Compliance

Aspects visit every construct in a tree and can inspect or modify them. Use Aspects to enforce compliance rules organization-wide.

import { IAspect, Annotations } from 'aws-cdk-lib';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';
import { CfnFunction } from 'aws-cdk-lib/aws-lambda';
import { IConstruct } from 'constructs';

class SecurityComplianceAspect implements IAspect {
  visit(node: IConstruct): void {
    // Ensure S3 buckets have encryption enabled
    if (node instanceof CfnBucket) {
      if (!node.bucketEncryption) {
        Annotations.of(node).addError(
          'S3 buckets must have encryption enabled'
        );
      }
    }

    // Ensure Lambda functions don't use x86 architecture
    if (node instanceof CfnFunction) {
      if (!node.architectures || !node.architectures.includes('arm64')) {
        Annotations.of(node).addWarning(
          'Lambda functions should use ARM64 architecture for cost savings'
        );
      }
    }
  }
}

// Apply to the entire application
const app = new App();
Aspects.of(app).add(new SecurityComplianceAspect());

Aspects run during synthesis. Using addError causes synthesis to fail, blocking deployment. Using addWarning emits a warning but allows deployment to proceed. This pattern is particularly useful for platform teams that provide shared libraries to application teams.

CDK Pipelines

CDK Pipelines provides a self-mutating CI/CD pipeline. When you change the pipeline definition in your CDK code, the pipeline updates itself on the next run.

import { Stack, Stage } from 'aws-cdk-lib';
import { CodePipeline, CodePipelineSource, ShellStep } from 'aws-cdk-lib/pipelines';

class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props: StageProps) {
    super(scope, id, props);
    new ApiStack(this, 'Api');
    new DatabaseStack(this, 'Database');
  }
}

class PipelineStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

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

    // Deploy to staging first
    const staging = pipeline.addStage(new ApplicationStage(this, 'Staging', {
      env: { account: '111111111111', region: 'us-east-1' },
    }));

    staging.addPost(new ShellStep('IntegrationTests', {
      commands: ['npm run test:integration'],
    }));

    // Deploy to production after staging succeeds
    pipeline.addStage(new ApplicationStage(this, 'Production', {
      env: { account: '222222222222', region: 'us-east-1' },
    }), {
      pre: [new ManualApprovalStep('PromoteToProd')],
    });
  }
}

Cross-Stack References

When your application spans multiple stacks, you need to share resources between them. CDK handles this automatically when you pass constructs across stack boundaries, but understanding the mechanism matters for troubleshooting.

class NetworkStack extends Stack {
  public readonly vpc: ec2.Vpc;

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.vpc = new ec2.Vpc(this, 'Vpc', { maxAzs: 2 });
  }
}

class ApiStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps & { vpc: ec2.Vpc }) {
    super(scope, id, props);

    new lambda.Function(this, 'ApiHandler', {
      vpc: props.vpc,  // CDK creates a CloudFormation Export/Import
      // ...
    });
  }
}

// Wire them together
const network = new NetworkStack(app, 'Network');
new ApiStack(app, 'Api', { vpc: network.vpc });

CDK generates CloudFormation exports and imports automatically. Be aware that once a stack exports a value, you cannot change or delete it while another stack imports it. For complex dependency graphs, consider using SSM Parameter Store for loose coupling:

// In the producing stack
new ssm.StringParameter(this, 'VpcIdParam', {
  parameterName: '/myapp/vpc-id',
  stringValue: this.vpc.vpcId,
});

// In the consuming stack
const vpcId = ssm.StringParameter.valueFromLookup(this, '/myapp/vpc-id');
const vpc = ec2.Vpc.fromLookup(this, 'ImportedVpc', { vpcId });

Environment-Specific Configuration

Avoid hardcoding environment-specific values. Use CDK context or a configuration pattern:

interface EnvironmentConfig {
  account: string;
  region: string;
  instanceType: ec2.InstanceType;
  minCapacity: number;
  maxCapacity: number;
  domainName: string;
}

const environments: Record<string, EnvironmentConfig> = {
  staging: {
    account: '111111111111',
    region: 'us-east-1',
    instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MEDIUM),
    minCapacity: 1,
    maxCapacity: 4,
    domainName: 'staging.example.com',
  },
  production: {
    account: '222222222222',
    region: 'us-east-1',
    instanceType: ec2.InstanceType.of(ec2.InstanceClass.M6G, ec2.InstanceSize.LARGE),
    minCapacity: 2,
    maxCapacity: 20,
    domainName: 'api.example.com',
  },
};

const envName = app.node.tryGetContext('env') ?? 'staging';
const config = environments[envName];

Testing CDK with Assertions

CDK provides a testing library that lets you verify synthesized CloudFormation templates. Test at two levels: fine-grained assertions and snapshot tests.

import { Template, Match } from 'aws-cdk-lib/assertions';

describe('ApiStack', () => {
  const app = new App();
  const stack = new ApiStack(app, 'TestStack', { env: stagingConfig });
  const template = Template.fromStack(stack);

  test('creates a Lambda function with correct runtime', () => {
    template.hasResourceProperties('AWS::Lambda::Function', {
      Runtime: 'nodejs20.x',
      Architectures: ['arm64'],
      TracingConfig: { Mode: 'Active' },
    });
  });

  test('creates exactly one DynamoDB table', () => {
    template.resourceCountIs('AWS::DynamoDB::Table', 1);
  });

  test('DynamoDB table has encryption enabled', () => {
    template.hasResourceProperties('AWS::DynamoDB::Table', {
      SSESpecification: {
        SSEEnabled: true,
      },
    });
  });

  test('Lambda function has bounded concurrency', () => {
    template.hasResourceProperties('AWS::Lambda::Function', {
      ReservedConcurrentExecutions: Match.anyValue(),
    });
  });
});

Snapshot tests catch unintended changes:

test('stack matches snapshot', () => {
  const template = Template.fromStack(stack);
  expect(template.toJSON()).toMatchSnapshot();
});

Update snapshots intentionally when making infrastructure changes: npm test -- --updateSnapshot. Review snapshot diffs in pull requests to catch accidental changes to security groups, IAM policies, or resource configurations.

These patterns compose well together. Custom L3 constructs encode your standards, Aspects enforce them, CDK Pipelines deploy them safely, and assertions verify them in CI. The result is infrastructure code that is as reviewable, testable, and maintainable as any application code.