AWS CDK Infrastructure as Code

Introduction

In the modern cloud‑first world, the speed at which a team can spin up, modify, and retire infrastructure determines whether a product can keep pace with user demand, regulatory change, or a sudden surge of data. The AWS Cloud Development Kit (CDK) flips the traditional “write‑it‑once‑as‑JSON” model on its head by letting developers describe their entire stack in a real programming language. When the language of choice is TypeScript, you gain static typing, modern tooling, and a vibrant ecosystem that makes infrastructure feel like native application code.

For a platform like Apiary—where we monitor bee colonies, run AI agents that analyze hive health, and expose conservation data to researchers—the ability to treat cloud resources as versioned, testable code is not a luxury; it is a necessity. A single change to a sensor‑data pipeline, a new Lambda function that flags colony stress, or a cost‑saving tweak to an S3 lifecycle rule can be rolled out across dozens of environments with a single pull request. The CDK’s abstraction layers keep the underlying CloudFormation templates tidy (the CDK generated ~3.5 million lines of CloudFormation in 2022 alone) while preserving full access to every AWS service.

This article is a deep dive into building production‑grade, TypeScript‑based CDK stacks. We’ll walk through the mechanics, show concrete code, discuss testing, CI/CD, security, and cost‑control, and sprinkle in analogies to bee colonies and autonomous AI agents where they naturally fit. By the end, you’ll have a blueprint you can copy into your own repo and start deploying reliable, repeatable infrastructure in minutes.

1. What the AWS CDK Actually Is

The AWS CDK is an open‑source software development framework that synthesizes high‑level constructs into AWS CloudFormation templates. A construct is a reusable, opinionated piece of infrastructure—think of it as a class that knows how to create an S3 bucket, attach a policy, and configure logging.

• Language support – As of CDK v2 (released November 2021), the toolkit ships with bindings for TypeScript, JavaScript, Python, Java, and C#. TypeScript is the “first‑class citizen” because the CDK itself is written in it.
• Construct library – The aws-cdk-lib package bundles ~250 L2 constructs (e.g., Bucket, Function, Table) that hide the boilerplate of raw CloudFormation resources. In addition, the Construct Catalog hosts >1 500 community‑maintained L3/L4 constructs, such as aws-cdk-aws-s3-deployment for syncing local assets.
• Synthesis – Running cdk synth converts your TypeScript code into a CloudFormation JSON/YAML template. The output is deterministic; the same code always produces the same template, which is essential for reproducible builds.

Because the CDK ultimately produces CloudFormation, you retain all the safety nets AWS provides: drift detection, change sets, and stack policies. The difference is you write declarative intent in a imperative language. This hybrid approach lets you embed loops, conditionals, and reusable functions directly in your infrastructure definition—features that are impossible in raw CloudFormation without macros.

Analogy – Think of a bee colony: each worker follows a simple set of rules, yet the colony as a whole can adapt to weather, predators, and food availability. CDK constructs are the worker bees, and the stack you synthesize is the hive. By programming the workers, you shape the hive’s behavior without manually building every cell.

Key Numbers (as of Q2 2024)

If you’re already comfortable with TypeScript, the CDK feels like an extension of your existing toolchain rather than a separate “infrastructure language.”

2. Why TypeScript Is the Sweet Spot

2.1 Strong Typing & IDE Support

TypeScript’s static type system catches mismatched property names, missing required fields, and even invalid ARNs before you ever run cdk synth. In VS Code, you get intellisense for every construct:

import { Bucket, BucketEncryption } from 'aws-cdk-lib/aws-s3';

const dataBucket = new Bucket(this, 'DataBucket', {
  versioned: true,
  encryption: BucketEncryption.S3_MANAGED,
  lifecycleRules: [{ expiration: Duration.days(365) }],
});

Hovering over BucketEncryption instantly shows the three allowed enum values. This reduces runtime errors that would otherwise surface only during a CloudFormation deployment (often after a costly resource spin‑up).

2.2 Reusability Through Classes & Interfaces

Because TypeScript is a full‑featured language, you can create abstract base constructs that encapsulate common patterns across projects. For Apiary, we built a HiveMetricsStack base class that provisions a DynamoDB table, a Kinesis stream, and a Lambda consumer—all wired together with the correct IAM policies. Sub‑stacks for “temperature sensors” or “pest detection” simply extend this base and add their own resources.

export abstract class HiveMetricsStack extends Stack {
  protected readonly metricsTable: Table;
  protected readonly dataStream: Stream;

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.metricsTable = new Table(this, 'MetricsTable', { ... });
    this.dataStream = new Stream(this, 'MetricsStream', { ... });
  }
}

2.3 Ecosystem Integration

Most modern CI pipelines (GitHub Actions, GitLab CI, Bitbucket Pipelines) already run Node.js. Adding a CDK step is as simple as installing aws-cdk-lib and running npm run build && cdk deploy. Additionally, the AWS CDK CLI is itself a Node package, so you can pin it to an exact version in package.json and avoid “works on my machine” issues.

2.4 Performance

The CDK’s synthesis step is written in TypeScript and compiled to fast JavaScript. For a typical 30‑resource stack, cdk synth finishes in <1 second on a modest CI runner. This speed encourages frequent synth/check cycles, which aligns well with rapid iteration cycles for AI agents that need new data pipelines.

3. Getting Started: Installing, Bootstrapping, and First Stack

3.1 Prerequisites

Tip – Use nvm to lock Node versions per project; CDK v2 is not compatible with Node 12 or older.

3.2 Project Scaffold

mkdir apiary-infra && cd apiary-infra
npm init -y
npm i -D typescript ts-node @aws-cdk/assert@2 aws-cdk-lib constructs
npx cdk init app --language typescript

The cdk init command creates a minimal app:

apiary-infra/
├─ bin/
│  └─ apiary-infra.ts   # entry point (CDK App)
├─ lib/
│  └─ apiary-infra-stack.ts   # default stack
├─ test/
│  └─ apiary-infra.test.ts
├─ cdk.json
└─ tsconfig.json

3.3 Bootstrapping the Target Account

Before any CDK deployment, you must create the bootstrap stack that holds the S3 bucket for assets and the IAM roles used by the CDK during deployment:

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

The command creates a stack named CDKToolkit. It stores ~10 GB of assets (Docker images, Lambda zip files) across accounts, which is why you only need to run it once per region/account pair.

3.4 Writing Your First Resource

Edit lib/apiary-infra-stack.ts:

import { Stack, StackProps, Duration } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Bucket, BucketEncryption } from 'aws-cdk-lib/aws-s3';
import { Function, Runtime, Code } from 'aws-cdk-lib/aws-lambda';
import { Table, AttributeType } from 'aws-cdk-lib/aws-dynamodb';

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

    // 1️⃣ S3 bucket for raw sensor data
    const rawDataBucket = new Bucket(this, 'RawDataBucket', {
      encryption: BucketEncryption.S3_MANAGED,
      versioned: true,
      lifecycleRules: [{ expiration: Duration.days(730) }],
    });

    // 2️⃣ DynamoDB table for hive metrics
    const metricsTable = new Table(this, 'MetricsTable', {
      partitionKey: { name: 'hiveId', type: AttributeType.STRING },
      sortKey: { name: 'timestamp', type: AttributeType.NUMBER },
      billingMode: BillingMode.PAY_PER_REQUEST,
      pointInTimeRecovery: true,
    });

    // 3️⃣ Lambda that processes new objects in the bucket
    const ingestFn = new Function(this, 'IngestFunction', {
      runtime: Runtime.NODEJS_18_X,
      handler: 'handler.main',
      code: Code.fromAsset('lambda/ingest'), // local folder
      timeout: Duration.minutes(5),
      environment: {
        TABLE_NAME: metricsTable.tableName,
        BUCKET_NAME: rawDataBucket.bucketName,
      },
    });

    // Grant permissions
    rawDataBucket.grantRead(ingestFn);
    metricsTable.grantWriteData(ingestFn);
  }
}

Run cdk synth to see the generated CloudFormation (approx. 300 lines). Deploy with cdk deploy.

4. Core CDK Concepts: App, Stack, and Construct

4.1 The CDK App (cdk.App)

An App is the top‑level container for one or more stacks. In bin/apiary-infra.ts you’ll see:

#!/usr/bin/env node
import * as cdk from 'aws-cdk-lib';
import { ApiaryInfraStack } from '../lib/apiary-infra-stack';

const app = new cdk.App();

new ApiaryInfraStack(app, 'ApiaryProd', {
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: 'us-east-1' },
});

new ApiaryInfraStack(app, 'ApiaryStaging', {
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: 'us-west-2' },
});

Each stack can target a different region or account, enabling multi‑region deployments (critical for low‑latency sensor ingestion).

4.2 Stacks (cdk.Stack)

A Stack maps directly to a CloudFormation stack. All resources defined inside a Stack are deployed together. Stacks can depend on each other via stack.addDependency(otherStack), ensuring ordering (e.g., a VPC stack must exist before an RDS stack).

4.3 Constructs (constructs.Construct)

Every AWS resource is a construct. You can also create custom constructs that combine several L2 resources into a reusable component.

export class S3LoggingBucket extends Construct {
  public readonly bucket: Bucket;
  constructor(scope: Construct, id: string, props?: BucketProps) {
    super(scope, id);
    this.bucket = new Bucket(this, 'LogBucket', {
      encryption: BucketEncryption.S3_MANAGED,
      ...props,
    });
  }
}

Custom constructs can be published to the Construct Catalog under a namespace like @apiary/cdk-constructs. This is how large organizations share patterns without duplicating code.

4.4 Context & Parameters

CDK supports context values (cdk.json or --context key=value) for environment‑specific data that you don’t want to hard‑code. For example, you could store a map of region‑to‑VPC‑ID pairs:

{
  "context": {
    "vpcIds": {
      "us-east-1": "vpc-0a1b2c3d4e5f6g7h8",
      "us-west-2": "vpc-1a2b3c4d5e6f7g8h9"
    }
  }
}

Inside code:

const vpcId = this.node.tryGetContext('vpcIds')[this.region];

5. Defining Real‑World Resources for a Bee‑Conservation Platform

Below we walk through three core services that Apiary uses daily: S3 for sensor data, Lambda for processing, and DynamoDB for time‑series metrics. The same patterns apply to other services like Athena, SageMaker, or EventBridge.

5.1 S3 Bucket with Lifecycle & Replication

Bees generate massive streams of sensor data (temperature, humidity, audio). In 2023, Apiary collected ≈ 12 TB of raw JSON per month. To keep storage costs low, we configure a two‑tier lifecycle:

• Hot tier – 0‑30 days in Standard‑IA (cost $0.0125/GB‑month).
• Cold tier – 31‑365 days in Glacier Deep Archive ($0.00099/GB‑month).

import { Bucket, BucketEncryption, StorageClass } from 'aws-cdk-lib/aws-s3';

const rawDataBucket = new Bucket(this, 'RawDataBucket', {
  encryption: BucketEncryption.S3_MANAGED,
  versioned: true,
  lifecycleRules: [
    {
      id: 'TransitionToIA',
      transitions: [{ storageClass: StorageClass.INFREQUENT_ACCESS, transitionAfter: Duration.days(30) }],
    },
    {
      id: 'TransitionToGlacier',
      transitions: [{ storageClass: StorageClass.DEEP_ARCHIVE, transitionAfter: Duration.days(365) }],
    },
    { id: 'ExpireOld', expiration: Duration.days(1825) }, // 5‑year retention for compliance
  ],
});

Cross‑Region Replication (CRR) is enabled for disaster recovery: data from us-east-1 replicates to eu-central-1. The CDK automatically creates the required IAM role and replication configuration when you set replicationRegions.

5.2 Lambda Function for Real‑Time Ingestion

Each new object triggers a Lambda that parses the JSON, extracts metrics, and writes them to DynamoDB. The function runs on Node.js 18.x and uses AWS SDK v3 for better tree‑shaking.

import { Function, Runtime, Code, LayerVersion } from 'aws-cdk-lib/aws-lambda';
import { Duration } from 'aws-cdk-lib';

const ingestFn = new Function(this, 'IngestFn', {
  runtime: Runtime.NODEJS_18_X,
  handler: 'index.handler',
  code: Code.fromAsset('lambda/ingest'),
  memorySize: 1024,
  timeout: Duration.minutes(2),
  environment: {
    TABLE_NAME: metricsTable.tableName,
    BUCKET_NAME: rawDataBucket.bucketName,
  },
  layers: [
    // Optional: shared utilities layer (e.g., @aws-sdk/client-dynamodb)
    LayerVersion.fromLayerVersionArn(this, 'AwsSdkLayer', 'arn:aws:lambda:us-east-1:123456789012:layer:aws-sdk-v3:1')
  ],
});
rawDataBucket.addEventNotification(EventType.OBJECT_CREATED, new LambdaDestination(ingestFn));

Performance – With 500 K objects per day, the function processes ~6 objects/sec on average. By allocating 1 GB memory, we achieve ~200 ms execution per file, well within the 2‑minute timeout.

5.3 DynamoDB Table for Time‑Series Metrics

We store metrics in a partition‑key (hiveId) and sort‑key (timestamp). Using On‑Demand billing eliminates capacity planning—costs scale linearly with reads/writes. In 2023, Apiary’s table handled ≈ 4 M writes/month and ≈ 12 M reads/month, costing roughly $45 on the on‑demand model.

import { Table, AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';

const metricsTable = new Table(this, 'MetricsTable', {
  partitionKey: { name: 'hiveId', type: AttributeType.STRING },
  sortKey: { name: 'timestamp', type: AttributeType.NUMBER },
  billingMode: BillingMode.PAY_PER_REQUEST,
  pointInTimeRecovery: true, // enables 35‑day PITR for accidental deletes
  ttl: { attributeName: 'ttl' }, // automatic expiration after 2 years
});

Secondary Indexes – To support queries by sensor type, we add a Global Secondary Index (GSI):

metricsTable.addGlobalSecondaryIndex({
  indexName: 'SensorTypeIdx',
  partitionKey: { name: 'sensorType', type: AttributeType.STRING },
  sortKey: { name: 'timestamp', type: AttributeType.NUMBER },
  projectionType: ProjectionType.ALL,
});

The GSI costs an additional $0.25 per GB‑month of indexed data, which is negligible compared to the primary table’s cost.

6. Managing Environments, Stages, and Multi‑Region Deployments

6.1 The “Environment” Object

When you instantiate a stack, you can pass an env property that pins the AWS account and region. This is essential for separating production, staging, and development environments.

new ApiaryInfraStack(app, 'ApiaryProd', {
  env: { account: '123456789012', region: 'us-east-1' },
});

new ApiaryInfraStack(app, 'ApiaryDev', {
  env: { account: '210987654321', region: 'us-west-2' },
});

If env is omitted, the CDK performs a “look‑up” using the credentials of the CLI user at synth time. This can lead to accidental cross‑account deployments, so we always explicitly set it.

6.2 Stages with the CDK Pipelines Module

For CI/CD, the aws-cdk-lib/pipelines module provides a high‑level construct that builds a pipeline stack with CodePipeline, CodeBuild, and optional manual approvals.

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

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

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

    // Add stages (staging → production) with optional manual approval
    const devStage = pipeline.addStage(new ApiaryInfraStack(this, 'Dev', {
      env: { account: '210987654321', region: 'us-west-2' },
    }));
    const prodStage = pipeline.addStage(new ApiaryInfraStack(this, 'Prod', {
      env: { account: '123456789012', region: 'us-east-1' },
    }));
    prodStage.addPre(new ManualApprovalStep('ApproveProd'));
  }
}

The pipeline automatically creates change sets, runs unit tests (see Section 7), and promotes the same CloudFormation template across environments, guaranteeing consistency.

6.3 Parameter Store & Secrets Manager Integration

Environment‑specific configuration (e.g., API keys for external weather services) lives in AWS Systems Manager Parameter Store or Secrets Manager. In CDK you can reference them directly:

import { StringParameter } from 'aws-cdk-lib/aws-ssm';
import { Secret } from 'aws-cdk-lib/aws-secretsmanager';

const weatherApiKey = StringParameter.fromSecureStringParameterAttributes(this, 'WeatherKey', {
  parameterName: '/apiary/prod/weatherApiKey',
  version: 1,
});

const dbCredentials = Secret.fromSecretNameV2(this, 'DbCreds', 'apiary/prod/dbCredentials');

Because the references resolve at deployment time, you never store secrets in source control.

7. Testing