Forem: Thorsten Hoeger

CDK Environment Management: Static vs Dynamic Stack Creation

Thorsten Hoeger — Thu, 25 Sep 2025 00:07:54 +0000

A comprehensive guide to choosing the right environment strategy for your CDK applications

1. Introduction: The Environment Management Dilemma

If you're building applications with AWS CDK, you've faced this question: how should you structure your code to deploy to multiple environments? This fundamental architectural decision sparked an interesting discussion in the CDK community, leading us - Thorsten Höger and Kenta Goto - to collaborate on this comprehensive guide.

Between us, we've reviewed hundreds of CDK projects and noticed a pattern: about 90% of teams choose their environment management approach without fully understanding its implications. The decision seems simple at first: you need dev, staging, and production environments. But the way you structure your CDK code to achieve this has far-reaching consequences for your team's productivity, deployment pipeline, and application reliability.

What makes this topic particularly interesting is that both approaches we'll discuss are valid and widely used in production. There's no universal "right" answer. Instead, each approach offers distinct advantages that align with different team needs and project requirements. Through this collaboration, we aim to present both perspectives fairly, helping you make an informed decision based on your specific context.

This guide examines the two primary patterns for managing CDK environments, their trade-offs, and when to use each. By the end, you'll have a clear framework for making this architectural decision intentionally rather than defaulting to what seems easiest initially.

2. The Two Approaches at a Glance

2.1 Variant A: Dynamic Stack Creation

The dynamic approach uses runtime configuration to determine which environment to synthesize. You pass a context variable during synthesis, and your code branches based on this value:

// app.ts
const app = new cdk.App();
const stageName = app.node.tryGetContext('stage') || 'dev';

let config: EnvironmentConfig;

switch (stageName) {
  case 'dev':
    config = {
      account: '111111111111',
      instanceType: 't3.micro',
      minCapacity: 1,
      maxCapacity: 2,
      domainName: 'dev.example.com'
    };
    break;
  case 'prod':
    config = {
        account: '222222222222',
      instanceType: 'm5.large',
      minCapacity: 3,
      maxCapacity: 10,
      domainName: 'example.com'
    };
    break;
  default:
    throw new Error(`Unknown stage: ${stageName}`);
}

new ApplicationStack(app, `MyApp-${stageName}`, {
  env: { account: config.account, region: 'eu-central-1' },
  config
});

Teams typically reach for this approach because it feels intuitive. You run cdk deploy -c stage=prod when you want production, and cdk deploy -c stage=dev for development. The mental model is straightforward: one command, one environment.

2.2 Variant B: Static Stack Creation ("Synthesize Once")

The static approach instantiates all environments during synthesis, creating multiple stack instances with different configurations:

// app.ts
const app = new cdk.App();

// Development environment
new ApplicationStack(app, 'MyApp-dev', {
  env: { account: '111111111111', region: 'eu-central-1' },
  config: {
    instanceType: 't3.micro',
    minCapacity: 1,
    maxCapacity: 2,
    domainName: 'dev.example.com'
  }
});

// Production environment
new ApplicationStack(app, 'MyApp-prod', {
  env: { account: '222222222222', region: 'eu-central-1' },
  config: {
    instanceType: 'm5.large',
    minCapacity: 3,
    maxCapacity: 10,
    domainName: 'example.com'
  }
});

This approach synthesizes all environments into a single CDK assembly with multiple CloudFormation templates. You deploy specific stacks with cdk deploy MyApp-prod. The key insight: synthesis happens once, producing artifacts for all environments simultaneously.

3. Key Trade-offs: A Practical Comparison

3.1 Development Experience

Variant A: Dynamic Stack Creation

The dynamic approach offers flexibility that feels natural during development. Each developer can spin up their personal stack by simply changing the stage name:

switch (stageName) {
  case 'dev':
    config = {
      account: '111111111111',
      instanceType: 't3.micro',
      minCapacity: 1,
      maxCapacity: 2,
      domainName: 'dev.example.com'
    };
    break;
  case 'prod':
    config = {
        account: '222222222222',
      instanceType: 'm5.large',
      minCapacity: 3,
      maxCapacity: 10,
      domainName: 'example.com'
    };
    break;
  default:
    // for each developer
    config = {
      account: process.env.CDK_DEFAULT_ACCOUNT,
      instanceType: 't3.nano',
      minCapacity: 1,
      maxCapacity: 1,
      domainName: `${stageName}.example.com`
    };
}

# Developer Alice's stack
cdk deploy -c stage=alice

# Developer Bob's stack
cdk deploy -c stage=bob

This flexibility extends to configuration. Developers can override settings through context without modifying code, making experimentation straightforward.

For example, this approach allows each developer to create not just one but multiple personal stacks. They can freely create, update, and even destroy these stacks, enabling them to conduct multiple experiments concurrently.

Another benefit is that developers can create temporary environments for experimenting with application code, such as Lambda functions, and freely deploy and test their functionality. Since they don't have to worry about affecting a shared development environment used by multiple developers, this enables faster rapid prototyping.

Variant B: Static Stack Creation

The static approach provides immediate feedback about all environments during development. When you run cdk synth, TypeScript validates your configuration for every environment. You catch production issues during development, not during the production deployment.

For example, the following code allows you to also catch errors in the dev configuration when synthesizing for prod.

// Stack
export interface ApplicationStackProps extends cdk.StackProps {
  enforceSSL?: boolean;
  minimumTLSVersion?: number;
}

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: ApplicationStackProps) {
    super(scope, id, props);

    new Bucket(this, 'MyBucket', {
      enforceSSL: props.enforceSSL,
      minimumTLSVersion: props.minimumTLSVersion,
    });
  }
}

// App
const app = new cdk.App();

new ApplicationStack(app, 'MyApp-dev', {
  // ValidationError: 'enforceSSL' must be enabled for 'minimumTLSVersion' to be applied
  enforceSSL: false,
  minimumTLSVersion: 1.2,
});

new ApplicationStack(app, 'MyApp-prod', {
  enforceSSL: true,
  minimumTLSVersion: 1.2,
});

3.2 CI/CD Pipeline Design

Variant A: Dynamic Stack Creation

The dynamic approach allows CI/CD pipelines to perform only what's necessary for each environment. For instance, in a development environment pipeline, only that environment's synthesis is performed, without synthesizing the production environment. This minimizes synthesis time. Furthermore, if errors occur only in the development environment, they won't affect other environments, ensuring that production CI/CD won't fail as a result.

A notable advantage is also the ability to build separate environments for each developer's feature branch using CI/CD pipelines without modifying configurations.

Variant B: Static Stack Creation

The static approach enables true "synthesize once, deploy many" pipelines. Your CI/CD pipeline synthesizes once at the beginning, creating a single artifact that progresses through environments:

# GitHub Actions example
jobs:
  synthesize:
    runs-on: ubuntu-latest
    steps:
      - run: npm ci
      - run: npx cdk synth
      - uses: actions/upload-artifact@v3
        with:
          name: cdk-out
          path: cdk.out

  deploy-dev:
    needs: synthesize
    steps:
      - uses: actions/download-artifact@v3
      - run: npx cdk --app cdk.out deploy MyApp-dev

  deploy-prod:
    needs: deploy-dev
    steps:
      - uses: actions/download-artifact@v3
      - run: npx cdk --app cdk.out deploy MyApp-prod

This approach guarantees that what you tested in dev is exactly what deploys to production. No re-synthesis means no opportunity for environmental differences to creep in.

3.3 Team Collaboration

Variant A: Dynamic Stack Creation

The dynamic approach allows each developer to deploy their own personal stack. This gives them the freedom to use their environments independently, enabling them to test various scenarios without causing configuration conflicts with one another.

Variant B: Static Stack Creation

The static approach forces teams to think about all environments holistically. Code reviews naturally include production considerations because production configuration is always present in the changeset. This visibility helps junior developers understand production requirements from day one.

4. When to Use Each Approach

4.1 Variant A Shines When:

Multiple Developer Stacks in Single Account

When your team needs numerous ephemeral environments in a shared AWS account, the dynamic approach excels. Consider a team of 10 developers, each needing their own stack for testing. In the previous code example, we passed the developer's name as the stage. To enable more flexible combinations, let's now specify the stage and owner separately:

// app.ts
const app = new cdk.App();
const stage = app.node.tryGetContext('stage') || 'dev';
const owner = app.node.tryGetContext('owner');

const stackName = owner
  ? `MyApp-${stage}-${owner}`
  : `MyApp-${stage}`;

let config: EnvironmentConfig;

switch (stage) {
  case 'dev':
    config = { ... }; // If necessary, change a value such as the domain name depending on whether the `owner` is specified.
    break;
  case 'prod':
    config = { ... };
    break;
  default:
    throw new Error(`Unknown stage: ${stage}`);
}

new ApplicationStack(app, stackName, {
  // Stack configuration
});

# Developer Alice's stack
cdk deploy -c stage=dev -c owner=alice

# Developer Bob's stack
cdk deploy -c stage=dev -c owner=bob

With this approach, multiple developers can create their own instance of the same stack within a single AWS account. Since there is no need to hardcode the stack owner's information in the configuration beforehand, this enables more flexible testing for teams that share an account.

Rapid Prototyping

During early development, when environment requirements are fluid, the dynamic approach allows quick iteration without constant code changes.

Synthesis Performance Matters

For large applications where synthesis takes significant time, synthesizing only the needed environment can speed up development cycles.

4.2 Variant B Excels When:

Enterprise Applications

Production applications with strict compliance requirements benefit from the static approach's determinism. You know exactly what will deploy because you've already synthesized it.

Cross-Environment Dependencies

When your architecture includes dependencies between environments, the static approach makes these relationships explicit:

const devStack = new ApplicationStack(app, 'MyApp-dev', devConfig);
const prodStack = new ApplicationStack(app, 'MyApp-prod', prodConfig);

// Production monitoring stack depends on both environments
new MonitoringStack(app, 'MyApp-monitoring', {
  devApiUrl: devStack.apiUrl,
  prodApiUrl: prodStack.apiUrl
});

Explicit Multi-Account Deployments

When environments span different AWS accounts, the static approach makes account boundaries explicit:

new ApplicationStack(app, 'MyApp-dev', {
  env: { account: '111111111111', region: 'eu-central-1' },
  // ...
});

new ApplicationStack(app, 'MyApp-prod', {
  env: { account: '222222222222', region: 'eu-central-1' },
  // ...
});

5. Real-World Implementation Tips

5.1 Handling Context and Lookups

Regardless of your approach, context lookups should happen before the final synthesis and not during the deployment in your CI/CD pipeline. Never perform VPC lookups or other AWS API calls inside environment-specific code, this could lead to delayed detection of errors and missing lookup of values:

// ❌ Wrong: Lookup inside conditional
if (stageName === 'prod') {
  const vpc = Vpc.fromLookup(this, 'VPC', { vpcId: 'vpc-123' });
}

// ✅ Right: Lookup once, use configuration
const vpcId = props.vpcId;
const vpc = Vpc.fromLookup(this, 'VPC', { vpcId });

Store lookup results in cdk.context.json and commit them to version control. This ensures consistent synthesis across team members and CI/CD environments.

5.2 Migration Considerations

Moving from Variant A to Variant B requires careful planning. Start by extracting configuration:

The original code (Variant A)

const app = new cdk.App();

const stage = app.node.tryGetContext('stage') || 'dev';

interface EnvironmentConfig {
  account: string;
  region: string;
  exampleName: string;
}

let config: EnvironmentConfig;

switch (stage) {
  case 'dev':
    config = {
      account: '111111111111',
      region: 'eu-central-1',
      exampleName: 'This is dev',
    };
    break;
  case 'prod':
    config = {
      account: '222222222222',
      region: 'eu-central-1',
      exampleName: 'This is prod',
    };
    break;
  default:
    throw new Error(`Unknown stage: ${stage}`);
}

new ApplicationStack(app, `MyApp-${stage}`, {
  env: { account: config.account, region: config.region },
  ...config,
});

Migration steps from Variant A to Variant B

// Step 1: Extract configuration from switch statements
const configs = {
  dev: {
    account: '111111111111',
    region: 'eu-central-1',
    exampleName: 'This is dev',
  },
  prod: {
    account: '222222222222',
    region: 'eu-central-1',
    exampleName: 'This is prod',
  },
};

// Step 2: Define stacks with the same stack names using static approach
new ApplicationStack(app, `MyApp-dev`, {
  env: { account: configs.dev.account, region: configs.dev.region },
  ...configs.dev,
});
new ApplicationStack(app, `MyApp-prod`, {
  env: { account: configs.prod.account, region: configs.prod.region },
  ...configs.prod,
});

// Step 3: Remove the old stack definition and unnecessary code such as the switch statements and `tryGetContext`
// new ApplicationStack(app, `MyApp-${stage}`, {
//   env: { account: config.account, region: config.region },
//   ...config,
// });

// Step 4: Run `cdk diff --all` and confirm there are no differences
// Migration from dynamic approach to static approach is complete when there are no differences

6. Conclusion: Making the Right Choice

Quick Decision Matrix:

Choose Variant A (Dynamic) if:	Choose Variant B (Static) if:
Many ephemeral environments needed	Fixed set of environments
Team uses a shared development account	Multi-account strategy with explicit account config
Synthesis performance is critical	Deployment determinism is critical
Team prefers runtime flexibility	Team values compile-time checks of all environments at the same time

Key Questions for Your Team:

Do we need unlimited ephemeral environments, or is our environment set fixed?
How important is deployment determinism versus development flexibility?
Are our environments truly independent, or do they share dependencies?
What's our team's experience level with CDK and TypeScript?

Both approaches are valid tools in your CDK toolkit. The key is choosing intentionally based on your specific requirements rather than defaulting to what seems simplest initially. Start with your deployment pipeline requirements and work backward to the code structure that best supports them.

Code Examples Appendix

Complete Variant A Example

// app.ts
import * as cdk from 'aws-cdk-lib';
import { ApplicationStack } from './stacks/application-stack';

const app = new cdk.App();

const stage = app.node.tryGetContext('stage') || 'dev';
const owner = app.node.tryGetContext('owner');

interface StageConfig {
  account: string;
  region: string;
  instanceType: string;
  minCapacity: number;
  maxCapacity: number;
  domainName: string;
  certificateArn?: string;
}

const baseConfigs: Record<string, StageConfig> = {
  dev: {
    account: '111111111111',
    region: 'eu-central-1',
    instanceType: 't3.micro',
    minCapacity: 1,
    maxCapacity: 2,
    domainName: owner ? `${owner}.example.com` : 'dev.example.com'
  },
  staging: {
    account: '111111111111',
    region: 'eu-central-1',
    instanceType: 't3.small',
    minCapacity: 2,
    maxCapacity: 4,
    domainName: 'staging.example.com'
  },
  prod: {
    account: '222222222222',
    region: 'eu-central-1',
    instanceType: 'm5.large',
    minCapacity: 3,
    maxCapacity: 10,
    domainName: 'example.com',
    certificateArn: 'arn:aws:acm:...'
  }
};

const config = baseConfigs[stage];
if (!config) {
  throw new Error(`Unknown stage: ${stage}`);
}

const stackName = owner
  ? `MyApp-${stage}-${owner}`
  : `MyApp-${stage}`;

new ApplicationStack(app, stackName, {
  env: { account: config.account, region: config.region },
  description: `Application stack for ${stage} environment${owner ? ` (${owner})` : ''}`,
  ...config
});

Complete Variant B Example

// app.ts
import * as cdk from 'aws-cdk-lib';
import { ApplicationStack } from './stacks/application-stack';
import { MonitoringStack } from './stacks/monitoring-stack';
import { Stage } from 'aws-cdk-lib';

const app = new cdk.App();

class ApplicationStage extends Stage {
  public readonly apiUrl: string;

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

    const stack = new ApplicationStack(this, 'AppStack', props.config);
    this.apiUrl = stack.apiUrl;
  }
}

// Development Stage
const devStage = new ApplicationStage(app, 'Dev', {
  env: { account: '111111111111', region: 'eu-central-1' },
  config: {
    instanceType: 't3.micro',
    minCapacity: 1,
    maxCapacity: 2,
    domainName: 'dev.example.com'
  }
});

// Staging Stage
const stagingStage = new ApplicationStage(app, 'Staging', {
  env: { account: '111111111111', region: 'eu-central-1' },
  config: {
    instanceType: 't3.small',
    minCapacity: 2,
    maxCapacity: 4,
    domainName: 'staging.example.com'
  }
});

// Production Stage
const prodStage = new ApplicationStage(app, 'Prod', {
  env: { account: '222222222222', region: 'eu-central-1' },
  config: {
    instanceType: 'm5.large',
    minCapacity: 3,
    maxCapacity: 10,
    domainName: 'example.com',
    certificateArn: 'arn:aws:acm:...'
  }
});

// Centralized monitoring for all environments
new MonitoringStack(app, 'CentralMonitoring', {
  env: { account: '333333333333', region: 'eu-central-1' },
  environments: [
    { name: 'dev', apiUrl: devStage.apiUrl },
    { name: 'staging', apiUrl: stagingStage.apiUrl },
    { name: 'prod', apiUrl: prodStage.apiUrl }
  ]
});

Side-by-Side Feature Comparison

// Environment-specific feature flags
type Features = {
  betaFeature: boolean;
  debugMode: boolean;
};
interface StackConfig {
  features: Features;
}

// Variant A Approach
const features: Record<string, Features> = {
  dev: { betaFeature: true, debugMode: true },
  prod: { betaFeature: false, debugMode: false }
};
const config: StackConfig = {
  features: features[stage]
};

// Variant B Approach
const devConfig: StackConfig = {
  features: { betaFeature: true, debugMode: true }
};
const prodConfig: StackConfig = {
  features: { betaFeature: false, debugMode: false }
};

About the Authors:

Thorsten Höger is an AWS DevTools Hero and cloud automation consultant who has been working with AWS CDK since its early days. He regularly builds and reviews CDK architectures for enterprises.

Kenta Goto is an AWS DevTools Hero, as well as an AWS CDK Top Contributor and Community Reviewer. Additionally, he is an OSS developer of his own AWS tools, such as cls3 and delstack.

Have questions or want to share your approach? Reach out on SocialMedia [@hoegertn] or [@k_goto]

Shift Left Security: Reviewing AWS CDK Apps at Pull Request Time

Thorsten Hoeger — Wed, 27 Nov 2024 14:39:19 +0000

Discovering security issues during pre-deployment reviews can feel like finding a critical bug after your code has already been merged. It's costly, time-consuming, and often leads to deployment delays or, worse, security compromises. For teams using AWS CDK, there's a better way: conducting security reviews during the pull request phase by analyzing CloudFormation template diffs.

The Cost of Late-Stage Security Findings

Imagine: Your team has just finished a sprint's worth of infrastructure changes using AWS CDK. The code has been reviewed, tested, and merged. You're ready to deploy to production. Then, during the pre-deployment security review, a critical issue is discovered – perhaps an overly permissive IAM role or an unencrypted data store. Now you're faced with a difficult choice: delay the deployment to fix the security issue or accept the risk and deploy anyway.

This scenario plays out in organizations daily, leading to:

Deployment delays that impact business objectives
Rushed security fixes that may introduce new issues
Increased pressure on security teams to expedite reviews
Technical debt when teams choose to deploy with known issues

Breaking Free from Traditional Review Bottlenecks

Traditional infrastructure security reviews often happen too late because they're treated as a final gateway before production deployment. This approach made sense in the days of manual infrastructure provisioning, but with Infrastructure as Code (IaC) tools like AWS CDK, we can shift these reviews left – way left, to the pull request phase.

The challenge with CDK specifically is that reviewing the TypeScript/Python/Java code alone isn't sufficient. A seemingly innocent change in CDK code can result in significant security implications in the generated CloudFormation templates. This is where diff analysis comes into play.

The Power of CloudFormation Diff Analysis

By synthesizing and comparing CloudFormation templates between your PR branch and the latest commit on main, you can:

Identify security-relevant changes early in the development cycle
Review actual infrastructure changes rather than abstractions
Catch unintended consequences of CDK construct usage
Provide developers with immediate security feedback

Consider this example:

// What looks like a simple S3 bucket creation in CDK
new s3.Bucket(this, 'MyBucket', {
  bucketName: 'my-important-data',
  removalPolicy: cdk.RemovalPolicy.DESTROY
});

Could generate this CloudFormation change:

 {
   "Resources": {
     "MyBucket": {
       "Type": "AWS::S3::Bucket",
       "Properties": {
         "BucketName": "my-important-data",
+        "PublicAccessBlockConfiguration": null,
         "VersioningConfiguration": {
-          "Status": "Enabled"
+          "Status": "Suspended"
         }
       }
     }
   }
 }

Current State: The Limitations of CDK Code Reviews

When reviewing CDK code, several critical security aspects can slip through the cracks:

Abstract Nature of CDK Constructs

High-level constructs in CDK can mask underlying security configurations. For example, a simple DatabaseInstance construct might create multiple security groups, IAM roles, and KMS keys – all of which need security review. Reviewing the CDK code alone might not reveal:

Default security group rules
Automated backup configurations
Log retention settings
Default encryption settings

L1 Construct Complexity

When using L1 (low-level) constructs, developers have more direct control over CloudFormation properties, but this can lead to:

Inconsistent security configurations across similar resources
Missing security best practices that higher-level constructs provide
Unintended exposure of sensitive configurations
Complex property combinations that are difficult to audit

Cross-Stack Dependencies

Modern CDK applications often span multiple stacks with complex dependencies. Security implications can arise from:

Cross-stack references affecting resource policies
Shared security group rules
IAM role trust relationships

The Case for PR-Time Security Reviews

Shifting security reviews to the pull request phase transforms the development process in several ways:

Accelerated Mean Time to Remediation

When security issues are found during PR review:

Developers are still actively engaged with the code
Context is fresh and relevant
Changes are smaller and more focused
Fixes can be implemented before affecting other developers

Developer Security Empowerment

Regular exposure to security reviews during the PR phase:

Builds security awareness within development teams
Helps developers learn to spot common security issues
Creates a feedback loop for continuous improvement
Reduces dependency on dedicated security teams

Enhanced Deployment Velocity

By catching security issues early:

Pre-deployment reviews become confirmatory rather than exploratory
Deployment pipelines face fewer security-related blocks
Teams can maintain deployment schedules with confidence
Security fixes don't compete with new feature development

Implementing PR-Time Security Reviews

Shifting security reviews to the PR phase requires both technical tooling and process changes. Let's break down the implementation into actionable components.

Technical Setup

The foundation of effective PR-time security reviews is automated CDK synthesis and diff generation. Here's a complete setup using GitHub Actions:

name: CDK Security Review
on:
  pull_request_target:
    branches: [ main ]

jobs:
  security-diff:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Install dependencies
        run: npm ci

      - name: Synthesize main branch
        run: |
          git checkout main
          cdk synth -q
          mv cdk.out cdk.out.main

      - name: Synthesize PR branch
        run: |
          git checkout ${{ github.event.pull_request.head.sha }}
          cdk synth -q

      - name: Generate security diff
        run: |
          cdk diff --app cdk.out MyStack --template=cdk.out.main/mystack.template.json > diff.log

      - name: Comment on PR
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const diff = fs.readFileSync('diff.log', 'utf8');
            const comment = `## Security Review Required

            The following CloudFormation changes require security review:

            <details>
            <summary>Infrastructure Changes</summary>

            \\`\\`\\`diff
            ${diff}
            \\`\\`\\`
            </details>

            ### Key Changes to Review:
            - IAM changes: ${diff.includes('AWS::IAM::') ? '⚠️ Yes' : '✅ No'}
            - Security Group changes: ${diff.includes('AWS::EC2::SecurityGroup') ? '⚠️ Yes' : '✅ No'}
            - KMS changes: ${diff.includes('AWS::KMS::') ? '⚠️ Yes' : '✅ No'}
            - S3 Policy changes: ${diff.includes('AWS::S3::BucketPolicy') ? '⚠️ Yes' : '✅ No'}`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

This workflow automates several crucial steps:

Synthesizes CloudFormation templates from both the main branch and PR branch
Generates a detailed diff of the templates
Posts the results directly to the PR with highlighted areas requiring review
Provides a quick summary of high-risk changes

Security-Focused Diff Analysis

When reviewing the generated diffs, certain changes should trigger immediate attention. Here's a prioritized checklist:

High Priority Changes

# IAM Role Policy Changes
 {
   "Resources": {
     "ServiceRole": {
       "Type": "AWS::IAM::Role",
       "Properties": {
         "AssumeRolePolicyDocument": {
           "Statement": [{
             "Effect": "Allow",
             "Principal": {
-              "Service": "lambda.amazonaws.com"
+              "AWS": "*"
             }
           }]
         }
       }
     }
   }
 }

# Security Group Rule Changes
 {
   "Resources": {
     "DatabaseSecurityGroup": {
       "Type": "AWS::EC2::SecurityGroup",
       "Properties": {
         "SecurityGroupIngress": [{
-          "CidrIp": "10.0.0.0/16"
+          "CidrIp": "0.0.0.0/0"
           "FromPort": 5432
         }]
       }
     }
   }
 }

Changes Requiring Deeper Analysis

# KMS Key Policy Changes
 {
   "Resources": {
     "DataKey": {
       "Type": "AWS::KMS::Key",
       "Properties": {
+        "EnableKeyRotation": false,
         "KeyPolicy": {
           "Statement": [{
+            "Principal": {"AWS": "arn:aws:iam::*:root"}
           }]
         }
       }
     }
   }
 }

Integration with Security Scanning Tools

Complement your diff analysis with specialized security scanning tools. Here's how to integrate cdk-nag:

import { AwsSolutionsChecks } from 'cdk-nag';
import { App, Aspects } from 'aws-cdk-lib';

const app = new App();
const stack = new MyStack(app, 'SecurityStack');

// Add all AWS Solutions security checks
Aspects.of(app).add(new AwsSolutionsChecks());

Review Process Integration

To make security reviews effective, integrate them into your PR process:

Required Checks: Configure GitHub branch protection rules to require:
- Successful CDK synthesis
- Security baseline checks
- No high-severity findings

Review Templates: Create PR templates that highlight security considerations:

## Security Considerations
- [ ] IAM permissions follow least privilege
- [ ] Network access is appropriately restricted
- [ ] Data encryption is properly configured
- [ ] Security groups follow zero trust principles
- [ ] Logging and monitoring are enabled

## CloudFormation Changes
<!-- Automated diff will be added here -->

Documentation Requirements: For security-relevant changes, require:
- Justification for permission changes
- Risk assessment for network changes
- Compliance impact analysis
- Rollback procedures

This enables teams to catch security issues early while maintaining deployment velocity. The next sections will cover specific security patterns to watch for and advanced automation strategies.

Getting Started

To implement PR-time security reviews in your organization:

Team Preparation
- Schedule security review training sessions
- Document review procedures
- Establish escalation paths
- Define security champions
Progressive Implementation
- Start with high-risk changes only
- Gradually expand scope
- Collect feedback and iterate
- Automate common checks

Common Pitfalls to Avoid

Over-reliance on Automation
- Automated checks complement, not replace, human review
- Maintain balance between automation and manual review
- Regular updates to security rules
Review Fatigue
- Rotate security reviewers
- Focus on high-impact changes
- Clear escalation paths
- Regular training and knowledge sharing
Process Overhead
- Right-size the process for your team
- Automate routine checks
- Clear documentation
- Regular process review and optimization

Conclusion

Implementing PR-time security reviews for CDK applications is a journey, not a destination. Start small, focus on high-impact changes, and gradually expand your coverage.

Security reviews are most effective when integrated early
Automation supports but doesn't replace human judgment
Clear processes and documentation are crucial
Regular training and feedback improve outcomes

By following these practices and guidelines, you'll build a robust security review process that catches issues early while maintaining development velocity.

Additional Resources

For further reading and tools:

Three strategies for deploying container images to Amazon ECS using CDK

Thorsten Hoeger — Tue, 26 Nov 2024 23:58:37 +0000

As containers continue to shape the cloud computing landscape, Amazon Elastic Container Service (ECS) remains a go-to choice for running containerized applications on AWS. However, deploying container images to ECS isn't a one-size-fits-all process. In this post, we'll explore three effective strategies for deploying container images to Amazon ECS, each tailored to different scenarios and offering distinct advantages.

Introduction

Amazon ECS simplifies the process of running, stopping, and managing Docker containers on a cluster of EC2 instances or managed instances using Fargate.
As a fully managed container orchestration service, it allows you to focus on designing and building your applications rather than managing infrastructure.

When it comes to deploying container images to ECS, your chosen strategy can significantly impact your development workflow, deployment speed, and overall application lifecycle management.
We'll look into three strategies:

Using Pre-built Images
Custom Images from Separate Projects
Images Built Alongside CDK Code

Each of these strategies leverages the AWS Cloud Development Kit (CDK), enabling us to define our infrastructure as code and streamline our deployment processes.

Strategy 1: Using Pre-built Images

Overview and Use Cases

This strategy is ideal when working with existing images from public registries like Docker Hub, Artifactory, or public Amazon Elastic Container Registry (ECR). It's particularly useful when:

You're using third-party images that don't require customization
Your organization maintains a central repository of pre-approved images
You're in the early stages of containerizing your application and want to start with a known, working image

Implementation Using AWS CDK

Let's walk through how to implement this strategy using AWS CDK:

Ensure you have the AWS CDK installed and a CDK project set up.
Import the necessary modules:

import { aws_ecs, aws_ec2 } from 'aws-cdk-lib';

Create your ECS cluster:

const cluster = new aws_ecs.Cluster(this, 'MyCluster', {
  vpc: new aws_ec2.Vpc(this, 'MyVpc')
});

Define your task definition and use aws_ecs.ContainerImage.fromRegistry() to specify your pre-built image:

const taskDefinition = new aws_ecs.FargateTaskDefinition(this, 'TaskDef');

taskDefinition.addContainer('WebContainer', {
  image: aws_ecs.ContainerImage.fromRegistry('nginx:latest'),
  memoryLimitMiB: 512,
  cpu: 256,
});

Create your ECS service:

new aws_ecs.FargateService(this, 'MyService', {
  cluster,
  taskDefinition,
});

Pros and Cons

Pros:

Quick and straightforward to implement
No need to manage the image building process
Easy to use well-maintained, public images

Cons:

Limited control over the image contents
Potential security risks if not using trusted sources
May not be suitable for applications requiring custom configurations

Best Practices and Tips

Always specify an exact image tag rather than using 'latest' to ensure reproducibility and updatability
Regularly update your images to get the latest security patches
Consider using ECR for private, pre-built images to benefit from integration with AWS services
Consider SLAs and request limits from registries

Strategy 2: Custom Images from Separate Projects

Overview and Use Cases

This strategy is effective when you have custom images that are built in separate projects or CI/CD pipelines. It's particularly useful when:

You have a dedicated team or process for building and maintaining Docker images
Your images require complex build processes that are better managed separately
You want to decouple image building from infrastructure deployment

Implementation Using AWS CDK

Here's how to implement this strategy:

Ensure your custom image is built and pushed to a registry (e.g., ECR) in a separate process.
In your CDK project, create a folder with a one-line Dockerfile that references your custom image: This way we make sure the image is referenced from our account's ECR and not dependent on the source repository

FROM 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-app:1.2.3

In your CDK stack, use aws_cs.ContainerImage.fromAsset() to reference this Dockerfile:

const taskDefinition = new aws_ecs.FargateTaskDefinition(this, 'TaskDef');

taskDefinition.addContainer('MyAppContainer', {
  image: aws_ecs.ContainerImage.fromAsset('app'),
  memoryLimitMiB: 512,
  cpu: 256,
});

Create your ECS service as before:

new aws_ecs.FargateService(this, 'MyService', {
  cluster,
  taskDefinition,
});

Pros and Cons

Pros:

Separation of concerns between image building and infrastructure deployment
Allows for complex, custom image building processes
Enables use of specialized CI/CD pipelines for image building

Cons:

Requires coordination between image building and infrastructure deployment processes
May introduce complexity in version management
Potential for misalignment between image and infrastructure versions
More work to update the infrastructure when creating a new application version

Best Practices and Tips

Use semantic versioning for your images to clearly communicate changes
Implement a robust tagging strategy in your image building pipeline
Implement a PR process to automatically create pull requests when new image versions are published

Strategy 3: Images Built Alongside CDK Code

Overview and Use Cases

This strategy involves building your Docker images directly within your CDK project. It's particularly useful when:

You want tight integration between your application code and infrastructure definition
Your images are relatively simple and don't require a complex build process
You prefer a self-contained project where all components are managed together

Implementation Using AWS CDK

Here's how to implement this strategy:

In your CDK project, create a folder with a Dockerfile for your application:

FROM node:20
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
CMD [ "node", "server.js" ]

In your CDK stack, use aws_cs.ContainerImage.fromAsset() to build and use this image:

import { aws_ecs } from 'aws-cdk-lib';

const taskDefinition = new aws_ecs.FargateTaskDefinition(this, 'TaskDef');

taskDefinition.addContainer('MyAppContainer', {
  image: aws_ecs.ContainerImage.fromAsset('app'),
  memoryLimitMiB: 512,
  cpu: 256,
});

new ecs.FargateService(this, 'MyService', {
  cluster,
  taskDefinition,
});

In this setup, CDK will build the Docker image locally during synthesis and push it to ECR during deployment.

Pros and Cons

Pros:

Tight integration between application code and infrastructure
Self-contained project, easier to manage as a single unit
Automatic handling of image building and pushing by CDK

Cons:

May slow down CDK synthesis and deployment for complex images
Less suitable for images that require very complex build processes
Can make it harder to use specialized CI/CD tools for image building

Best Practices and Tips

Keep your Dockerfile optimized for faster builds
Use .dockerignore to exclude unnecessary files from the build context
Consider using multi-stage builds to keep final images small

Comparison of Strategies

Here's a quick comparison to help you choose the right strategy for your needs:

Aspect	Pre-built Images	Custom Images from Separate Projects	Images Built Alongside CDK Code
Complexity	Low	Medium	Low to Medium
Flexibility	Low	High	Medium
Build Speed	N/A	Fast (pre-built)	Can be slow for complex images
Integration with Infrastructure	Loose	Medium	Tight
Suitable for Complex Images	No	Yes	Depends on complexity
Version Control	Challenging	Good	Excellent

Advanced Considerations

Security Best Practices

Regardless of the strategy you choose, consider these security best practices:

Use minimal base images to reduce attack surface
Implement least privilege principles in your task execution roles
Regularly scan your images for vulnerabilities and include that in your pipeline
Use AWS Secrets Manager to handle sensitive data

Optimizing for Performance and Cost

To optimize your ECS deployments:

Use appropriate task sizes to avoid over-provisioning
Implement scaling based on your application's needs
Think about Spot instances for non-critical workloads
Optimize your Docker images for size and startup time

Integration with CI/CD Pipelines

Each strategy can be integrated into CI/CD pipelines:

For pre-built images, trigger automated pull requests and deployments when new versions are published
For separate projects, use a pipeline to build images and another to deploy infrastructure
For images built with CDK, include image building in your infrastructure deployment pipeline using fromAsset

Conclusion

Choosing the right strategy for deploying container images to Amazon ECS is crucial for efficient and effective cloud operations.
While each approach we've discussed has its merits, the third strategy - building images alongside CDK code - offers a compelling balance of integration and flexibility that's worth a closer look.

This approach shines in scenarios where you want to maintain a tight coupling between your application code and infrastructure definition.
It's particularly powerful for teams embracing the "infrastructure as code" philosophy, as it allows for versioning both your application and infrastructure in a single repository.
This can significantly streamline your CI/CD pipelines and make it easier to maintain consistency across environments.

However, remember that the best strategy is ultimately the one that aligns with your team's workflow and your application's specific requirements.
Don't hesitate to mix and match these approaches as needed for different components of your system.
The flexibility of containers and the AWS ecosystem allows for creative solutions to complex problems.

As container technologies continue to evolve, so too will these strategies. Stay engaged with the AWS community, keep an eye on new features and services, and be ready to adapt your approach as new best practices emerge.

Implementing these strategies effectively requires a deep understanding of both AWS services and container orchestration principles.
If you find yourself needing guidance on optimizing your ECS deployments or architecting robust, scalable container solutions, consider reaching out to experienced professionals in the field.

As the author of this post, I've helped numerous organizations navigate the complexities of container deployment on AWS.
If you're looking to elevate your container strategy or need assistance in implementing these approaches, feel free to connect.
Together, we can design a container deployment strategy that not only meets your current needs but also positions you for future growth and innovation.

Remember, in the world of cloud computing, the right expertise can make all the difference.

Additional Resources

Happy containerizing!

Deploying your CDK app to different stages and environments

Thorsten Hoeger — Fri, 29 Jan 2021 16:37:05 +0000

CDK recap

The AWS Cloud Development Kit (CDK) helps you define your Cloud infrastructure using a higher-level programming language that is then synthesized into AWS CloudFormation to create your infrastructure in the AWS environment. You can learn more about CDK from the community at cdk.dev

One of the big differences to classic CloudFormation templates is that the top-most object is the CDK app that contains multiple stacks versus on top-level stack in CloudFormation. Given this design, you can define all your stacks your application need in one CDK app.

Why do we need stages?

For every application, you would want to deploy not only one instance for production but also some pre-production setups for testing, QA, load testing, etc. These different sets of infrastructure components are called stages. Each of these stages is deployed into one or more AWS environments, defined by an AWS account id and a region.

We want these stages to be similar to each other, but there will always be differences in some settings like size and number of machines, software versions, 3rd party URLs, etc. So we need to design a way to make all these settings configurable.

Sample application

For this blog post, I want to show this based on a simple sample application that runs an nginx Webserver using ECS and Fargate and has an ApplicationLoadBalancer as an entry point. Using the ECS patterns library of the CDK, this is only one construct named ApplicationLoadBalancedFargateService and has a few settings like container image, number of containers and potentially fixed domain names.

class WebserverStack extends cdk.Stack {

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

        new ecsPatterns.ApplicationLoadBalancedFargateService(this, 'Service', {
            memoryLimitMiB: 1024,
            cpu: 512,
            taskImageOptions: {
                image: ecs.ContainerImage.fromRegistry('nginx:latest'),
            },
            desiredCount: 1,
        });
    }
}

const app = new cdk.App();
new WebserverStack(app, 'MyWebserver');

Extracting configuration

The first step is to generalize this code for all our environments by introducing a configuration object that extends the CDK stack properties with our image version and container count settings. We can then use this object to configure our Fargate setup.

interface WebserverStackProps extends cdk.StackProps {
    /**
     * container image tag
     * @default latest
     */
    readonly imageTag?: string;
    /**
     * number of containers
     */
    readonly containerCount: number;
}

class WebserverStack extends cdk.Stack {

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

        new ecsPatterns.ApplicationLoadBalancedFargateService(this, 'Service', {
            memoryLimitMiB: 1024,
            cpu: 512,
            taskImageOptions: {
                image: ecs.ContainerImage.fromRegistry(`nginx:${props.imageTag ?? 'latest'}`),
            },
            desiredCount: props.containerCount,
        });
    }
}

How does CDK handle environments?

In the AWS CDK, every stack has a property called env that defines this stack's target environment. This property receives the account id and the region for this stack. If you do not want to configure the real target data here, you can use the environment variables 'CDK_DEFAULT_ACCOUNT' and 'CDK_DEFAULT_REGION' to let AWS CDK use the account and region of your current AWS CLI credentials. I would not recommend doing this, as it poses the risk of deploying your application to whatever account you are currently logged in instead of a defined target environment. So our app definition should look more like this:

const app = new cdk.App();
new WebserverStack(app, 'MyWebserver', {
    env: {account: '111111111111', region: 'eu-central-1'},
});

Given this target definition and our WebserverStackProps interface, we can now define all the stages we want to deploy within our app.

We define the settings we want, like different version tags or the number of containers for every stage.

const app = new cdk.App();
// Development stage
new WebserverStack(app, 'MyWebserver-dev', {
    env: {account: '111111111111', region: 'eu-central-1'},
    imageTag: '1.19.6',
    containerCount: 1,
});

// QA stage
new WebserverStack(app, 'MyWebserver-qa', {
    env: {account: '111111111111', region: 'eu-central-1'},
    imageTag: '1.19.5',
    containerCount: 2,
});

// Production stage with two environments
new WebserverStack(app, 'MyWebserver-prod-frankfurt', {
    env: {account: '222222222222', region: 'eu-central-1'},
    imageTag: '1.19.3',
    containerCount: 4,
});
new WebserverStack(app, 'MyWebserver-prod-dublin', {
    env: {account: '222222222222', region: 'eu-west-1'},
    imageTag: '1.19.3',
    containerCount: 4,
});

Synthesizing and deploying the app

The AWS CDK deployment has several stages. Your application is synthesized into CloudFormation templates, and these are then finally deployed to the target accounts and regions. The synth step of this pipeline will always create the CloudFormation templates for all stages and environments, which is meant to be this way. The reasoning is that you synthesize once at the beginning of your pipeline and during the execution, which may take days or weeks, you only work with the so-called cloud assembly in the cdk.out folder.

So the workflow for deploying our stacks would be:

# Synthesize all templates to cdk.out
cdk synth

# Deploy our testing stage and reference the assembly
cdk deploy --app 'cdk.out/' MyWebserver-dev

# Do some tests here and approve test stage

# Deploy our qa stage
cdk deploy --app 'cdk.out/' MyWebserver-qa

# Do some tests here and approve QA stage

# Deploy our production stages and reference the assembly
cdk deploy --app 'cdk.out/' MyWebserver-prod-frankfurt
cdk deploy --app 'cdk.out/' MyWebserver-prod-dublin

Conclusion

I strongly recommend to define all your stages for your workload within the same CDK app and configure the differences using custom stack properties. You should also deploy all stages from the same branch and pipeline execution by synthesizing once and using the cloud assembly to run the same artifacts and with the same settings in all stages.

What's next?

To reduce the complexity of writing pipelines, the AWS CDK brings a package called CDK pipelines, which helps you creating deployment workflows using AWS CodePipeline. I recommend you read my post "Create a CI/CD Pipeline for your CDK App" to learn more about this.

Need help?

If you need help setting up multi-stage apps in AWS CDK, reach out to me via my AWS CDK Coaching program for individuals or teams.

CDK Coaching

Create a CI/CD Pipeline for your CDK App

Thorsten Hoeger — Mon, 14 Sep 2020 21:47:48 +0000

In the last post, we created a basic serverless application that was deployed into one prod environment. In this post, I will show you how to deploy your CDK application to multiple stages in multiple AWS accounts and regions to have real test environments before your code hits production.

Account setup

Using AWS Organizations we create three AWS accounts:

This account hosts the pipeline
This accounts contains the dev stage
This account contains the prod stage

For this blog post, we will refer to the accounts as "CI/CD" with account id 111111111111, "Serverless Dev" with id 222222222222, and "Serverless Prod" with id 333333333333.

We will deploy environments to the Frankfurt and to the Dublin region.

CDK bootstrapping

For CDK pipelines to work, we need to bootstrap all account/region pairs where we want to deploy something. Additionally, we need to bootstrap with the new bootstrap style.

To do this we log into each account and run the following commands:

# In CI/CD account
CDK_NEW_BOOTSTRAP=1 cdk bootstrap --cloudformation-execution-policies 'arn:aws:iam::aws:policy/AdministratorAccess' aws://111111111111/eu-central-1
CDK_NEW_BOOTSTRAP=1 cdk bootstrap --cloudformation-execution-policies 'arn:aws:iam::aws:policy/AdministratorAccess' aws://111111111111/eu-west-1

# In Dev account
CDK_NEW_BOOTSTRAP=1 cdk bootstrap --cloudformation-execution-policies 'arn:aws:iam::aws:policy/AdministratorAccess' --trust 111111111111 aws://222222222222/eu-central-1
CDK_NEW_BOOTSTRAP=1 cdk bootstrap --cloudformation-execution-policies 'arn:aws:iam::aws:policy/AdministratorAccess' --trust 111111111111 aws://222222222222/eu-west-1

# In Prod account
CDK_NEW_BOOTSTRAP=1 cdk bootstrap --cloudformation-execution-policies 'arn:aws:iam::aws:policy/AdministratorAccess' --trust 111111111111 aws://333333333333/eu-central-1
CDK_NEW_BOOTSTRAP=1 cdk bootstrap --cloudformation-execution-policies 'arn:aws:iam::aws:policy/AdministratorAccess' --trust 111111111111 aws://333333333333/eu-west-1

As you can see, we are bootstrapping both regions in all accounts, and for the workload accounts, we are establishing a trust relationship to the CI/CD account to allow cross-account deployments. CDK Bootstrap will create deployment roles that will be assumed by the pipeline in the CI/CD account. All these roles will have full administrative permissions as we added the admin policy.

For my AWS org, I created a small Python helper script to bootstrap accounts. You can find it here https://gist.github.com/hoegertn/390f80857f745f3487ecbf2ffbef137b

Add pipeline

In our CDK application, we now need to make some changes. First, we need to create a CDK pipeline and then we need to add stages to our pipeline containing our serverless application. I will be using GitHub as the location of my repo so we also need a personal access token that we store inside the SecretsManager in a new Secret called "GitHub".

If you forget to store the secret, you will get weird "Internal failure" errors when creating the Pipeline later.

We install the CDK pipeline library using npm install --save-exact @aws-cdk/pipelines

Now we need to modify our application inside the bin folder. Previously it looked like this:

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from '@aws-cdk/core';
import { ServerlessDemoStack } from '../lib/serverless-demo-stack';

const app = new cdk.App();
new ServerlessDemoStack(app, 'cdk-serverless-demo', {
  env: {account: 'XXXX', region: 'eu-central-1'},
});

First we create a new Stack for the pipeline and reference our GitHub repo and secret.

class PipelineStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props: cdk.StageProps) {
    super(scope, id, props);

    // Create CodePipeline artifact to hold source code from repo
    const sourceArtifact = new codepipeline.Artifact();
    // Create CodePipeline artifact to hold synthesized cloud assembly
    const cloudAssemblyArtifact = new codepipeline.Artifact();

    // Create the CDK pipeline
    const pipeline = new pipelines.CdkPipeline(this, 'Pipeline', {
      pipelineName: 'ServerlessPipelineDemo',
      cloudAssemblyArtifact,

      // Checkout source from GitHub
      sourceAction: new codepipeline_actions.GitHubSourceAction({
        actionName: 'Source',
        owner: 'taimos',
        repo: 'cdk-serverless-demo-pipeline',
        branch: 'main',
        oauthToken: cdk.SecretValue.secretsManager('GitHub'),
        output: sourceArtifact,
      }),
      // For synthesize we use the default NPM synth
      synthAction: pipelines.SimpleSynthAction.standardNpmSynth({
        sourceArtifact,
        cloudAssemblyArtifact,
        // We override the default install command to prepare our lambda too
        installCommand: 'npm ci && npm ci --prefix lambda',
        // As we may need Docker we create a privileged container
        environment: {
          privileged: true,
        },
      }),
    });
  }
}

Now we remove our application stack from the CDK app and replace it with our pipeline, as this will be the only stack in our app. It will then create our stages during the synthesize step.

const app = new cdk.App();
new PipelineStack(app, 'ServerlessPipelineDemo', {
  env: {account: '111111111111', region: 'eu-central-1'}
});

Deployment of the pipeline

We should now commit our code to the repository and push it to our source. In my case, I pushed it to GitHub. Now we login to the CI/CD account and run cdk deploy ServerlessPipelineDemo manually once to set up the pipeline. All further updates will be done through the repository.

Please make sure to push before deploying the first time, as CodePipeline starts the first execution immediately and will fail if the repo is not yet there.

Adding application stages

For our serverless application, we now define one stage by creating a new class that extends the Stage class.

class AppStage extends cdk.Stage {
  constructor(scope: cdk.Construct, id: string, props: cdk.StageProps) {
    super(scope, id, props);
    new ServerlessDemoStack(this, 'cdk-serverless-demo');
  }
}

We can now use this stage definition inside our pipeline to add environments in our AWS accounts and regions. So inside our pipeline stack, right after the definition of the pipeline, we add:

pipeline.addApplicationStage(new AppStage(this, 'app-dev-fra', { env: { account: '222222222222', region: 'eu-central-1' } }));
pipeline.addApplicationStage(new AppStage(this, 'app-dev-dub', { env: { account: '222222222222', region: 'eu-west-1' } }));
pipeline.addApplicationStage(new AppStage(this, 'app-prod-fra', { env: { account: '333333333333', region: 'eu-central-1' } }));
pipeline.addApplicationStage(new AppStage(this, 'app-prod-dub', { env: { account: '333333333333', region: 'eu-west-1' } }));

We can now commit and push these changes and the pipeline will pickup this commit and start a new execution. The moment it reaches the UpdatePipeline Stage it will self mutate and restart the pipeline to add the additional stages for assets, deployments, etc.

As you can see the pipeline deployed four environments of our serverless application into two different accounts and two different regions. In total, we deployed six CloudFormation stacks:

CI/CD account
- eu-central-1: ServerlessPipelineDemo - pipeline stack
- eu-west-1: ServerlessPipelineDemo-support-eu-west-1 - pipeline support stack for bucket replication of assets
Dev Account
- eu-central-1: app-dev-fra-cdk-serverless-demo - dev stage in Frankfurt
- eu-west-1: app-dev-dub-cdk-serverless-demo - dev stage in Dublin
Prod Account
- eu-central-1: app-prod-fra-cdk-serverless-demo - prod stage in Frankfurt
- eu-west-1: app-prod-dub-cdk-serverless-demo - prod stage in Dublin

To get the URLs of our stages we look into the CloudFormation outputs of our deployments. You can access them through the execution details of the action or using the CloudFormation console of the target account.

What's next?

The next steps would be to add manual approval actions to ask humans if the pipeline should proceed from one stage to the next one or to add integration tests that automatically test the deployed stage before proceeding to further environments. I will cover this in an upcoming blog post and in my talk at the CDK Day on September 30th.

Build a basic serverless application using AWS CDK

Thorsten Hoeger — Mon, 24 Aug 2020 20:18:15 +0000

In this blog post, I want to show you how to write a basic Serverless application using the AWS CDK to deploy an API Gateway, Lambda functions, and a DynamoDB table. We will be using the asset support of the CDK to bundle our business logic during the deployment.

What are we implementing?

Our application will be a straightforward ToDo list that supports adding new items to the list and displaying it. Further actions are left to the reader to experiment. We will store the data in a DynamoDB table and implement the business logic using AWS Lambda with our code written in TypeScript. As the API endpoint, an HTTP API will be used.

Initialize your CDK application

To start our project, we need to initialize our CDK project. In my previous blog post, I describe the necessary steps.

After these steps are done, we enhance the setup by installing further libraries with the following command:

npm install --save-exact @aws-cdk/aws-lambda @aws-cdk/aws-lambda-nodejs @aws-cdk/aws-dynamodb @aws-cdk/aws-apigatewayv2

Creating the datastore

To create our backing datastore we create a new DynamoDB table and use PK as the hash key of the table. In CDK, we accomplish this by using the Table construct. To ease the setup, we use on-demand billing for DynamoDB, so we do not need to calculate throughput. Be aware that this is not covered by the Free Tier of your AWS account!

const table = new dynamodb.Table(this, 'Table', {
  partitionKey: {
    name: 'PK',
    type: dynamodb.AttributeType.STRING,
  },
  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
});

To be able to look into the database, later on, we create an output to know the table name CloudFormation chose.

new cdk.CfnOutput(this, 'TableName', {value: table.tableName});

Creating our business logic

For our business logic, we create two lambda functions—one to fetch a list of all tasks and one to create a new task inside the table. To hold the code of these lambdas, we create a folder lambda/ and initialize it as a new NodeJS project. I am using the following settings to create my Lambda in TypeScript:

{
  "name": "lambda",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "tslint -p tsconfig.json && jest"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "aws-sdk": "^2.714.0",
    "uuid": "^8.3.0"
  },
  "devDependencies": {
    "@types/aws-lambda": "^8.10.59",
    "@types/jest": "^26.0.4",
    "@types/node": "14.0.23",
    "@types/uuid": "^8.3.0",
    "jest": "^26.1.0",
    "sinon": "^9.0.2",
    "ts-jest": "^26.1.2",
    "ts-mock-imports": "^1.3.0",
    "ts-node": "^8.10.2",
    "tslint": "^6.1.3",
    "typescript": "~3.9.6"
  }
}

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "lib": ["es2018"],
    "declaration": true,
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitThis": true,
    "esModuleInterop": true,
    "alwaysStrict": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": false,
    "inlineSourceMap": true,
    "inlineSources": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": false,
    "typeRoots": ["./node_modules/@types"]
  },
  "exclude": ["cdk.out"]
}

The most important part is to have the AWS SDK and the uuid library installed.

The header of my lambda code, sitting in lib/tasks.ts, is:

import { DynamoDB } from 'aws-sdk';
import { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { env } from 'process';
import { v4 } from 'uuid';

const dynamoClient = new DynamoDB.DocumentClient();

To add new tasks to the database, we will post a JSON object to the API with two fields named "name" and "state". We generate a new UUID to be used as the primary id of the task.

// Export new function to be called by Lambda
export async function post(event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> {
    // Log the event to debug the application during development
  console.log(event);

    // If we do not receive a body, we cannot continue...
  if (!event.body) {
        // ...so we return a Bad Request response
    return {
      statusCode: 400,
    };
  }

    // As we made sure we have a body, let's parse it
  const task = JSON.parse(event.body);
    // Let's create a new UUID for the task
  const id = v4();

    // define a new task entry and await its creation
  const put = await dynamoClient.put({
    TableName: env.TABLE_NAME!,
    Item: {
            // Hash key is set to the new UUID
      PK: id,
            // we just use the fields from the body
      Name: task.name,
      State: task.state,
    },
  }).promise();

    // Tell the caller that everything went great
  return {
    statusCode: 200,
    body: JSON.stringify({...task, id}),
  };
}

To fetch data from the table, we implement another function that resides in the same file. For better readability, I split it into two functions, one to handle the API call and a helper function that is reading from the database.

// Export new function to be called by Lambda
export async function get(event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> {
  // Log the event to debug the application during development
  console.log(event);

  // Get a list of all tasks from the DB, extract the method to do paging
  const tasks = (await getTasksFromDatabase()).map((task) => ({
    // let's reformat the data to our API model
    id: task.PK,
    name: task.Name,
    state: task.State,
  }));

  // Return the list as JSON objects
  return {
    statusCode: 200,
    headers: {
      'Content-Type': 'application/json',
    },
    // Body needs to be string so render the JSON to string
    body: JSON.stringify(tasks),
  };
}

// Helper method to fetch all tasks
async function getTasksFromDatabase(): Promise<DynamoDB.DocumentClient.ItemList> {
  // This variable will hold our paging key
  let startKey;
  // start with an empty list of tasks
  const result: DynamoDB.DocumentClient.ItemList = [];

  // start a fetch loop
  do {
    // Scan the table for all tasks
    const res: DynamoDB.DocumentClient.ScanOutput = await dynamoClient.scan({
      TableName: env.TABLE_NAME!,
      // Start with the given paging key
      ExclusiveStartKey: startKey,
    }).promise();
    // If we got tasks, store them into our list
    if (res.Items) {
      result.push(...res.Items);
    }
    // Keep the new paging token if there is one and repeat when necessary
    startKey = res.LastEvaluatedKey;
  } while (startKey);
  // return the accumulated list of tasks
  return result;
}

After we put this code into the tasks.ts file, we can instantiate the functions inside our CDK app and configure automatic bundling.

To setup the Lambda functions, the NodejsFunction construct is excellent. We can specify the file to use as the entry point and the name of the exported function. CDK will then transpile and package this code during synth using Parcel. For this step, you need a running Docker setup on your machine as the bundling happens inside a container.

const postFunction = new lambdaNode.NodejsFunction(this, 'PostFunction', {
  runtime: lambda.Runtime.NODEJS_12_X,
  // name of the exported function
  handler: 'post',
  // file to use as entry point for our Lambda function
  entry: __dirname + '/../lambda/lib/tasks.ts',
  environment: {
    TABLE_NAME: table.tableName,
  },
});
// Grant full access to the data
table.grantReadWriteData(postFunction);

const getFunction = new lambdaNode.NodejsFunction(this, 'GetFunction', {
  runtime: lambda.Runtime.NODEJS_12_X,
  handler: 'get',
  entry: __dirname + '/../lambda/lib/tasks.ts',
  environment: {
    TABLE_NAME: table.tableName,
  },
});
// Grant only read access for this function
table.grantReadData(getFunction);

Setup of the API

As the entry point to our API, we use the new HTTP API of the service API Gateway. To create the API and print out the URL, we use this code:

const api = new apiGW.HttpApi(this, 'Api');
new cdk.CfnOutput(this, 'ApiUrl', {value: api.url!});

We then need to add routes for every path and method we want to expose and supply a Lambda function that implements this.

api.addRoutes({
  path: '/tasks',
  methods: [apiGW.HttpMethod.POST],
  integration: new apiGW.LambdaProxyIntegration({handler: postFunction})
});
api.addRoutes({
  path: '/tasks',
  methods: [apiGW.HttpMethod.GET],
  integration: new apiGW.LambdaProxyIntegration({handler: getFunction})
});

Deploy to our AWS account

By running cdk synth, we can synthesize the CloudFormation template and let CDK package our Lambda code. The cdk.out folder will then contain the code bundles and the templates, ready to be deployed.

Using the cdk deploy command, our application will go live inside our AWS account and print out the table name of our DynamoDB table and the API URL.

Testing the API

We can then use Postman or cURL to add tasks to the database or retrieve the list of entries.

API_URL=https://XXXXX.execute-api.eu-central-1.amazonaws.com/

# Add new task to the table
curl -v -X POST -d '{"name":"Testtask","state":"OPEN"}' -H "Content-Type: application/json" ${API_URL}tasks

# Retrieve the list
curl -v ${API_URL}tasks

Conclusion

In this post, we learned to set up an AWS CDK application that creates a DynamoDB table, two Lambda functions, and an HTTP API. It uses CDK native bundling of code to transpile TypeScript to JavaScript and to package the code ready to be deployed to Lambda.

Initializing a new CDK app

Thorsten Hoeger — Sun, 09 Aug 2020 10:32:33 +0000

In this blog post, I want to show you how to create a new CDK project for your application deployment. We will initialize a new CDK app and add some constructs, then we deploy and destroy the infrastructure using the CDK CLI.

Initializing the app

To initialize the new CDK app first of all we need to install the CDK CLI on our machine. To achieve this we have to make sure that NodeJS is set up correctly. We can then install CDK using the node package manager by calling npm install -g aws-cdk.

For our application, we create a new and empty folder called cdk-demo and run cdk init inside of it. The init command needs two parts of information to successfully initialize our app. We need to tell it which language we want to use and which scaffolding template to use. As project language, we can choose from TypeScript, JavaScript, Python, Java, and .NET. As a blueprint, we have templates for applications, a complete sample application, or a template for our own CDK Construct Library.

In this example, we will use the app template using TypeScript, so we call cdk init --language=typescript app in our folder.

Configuration of the app

After the initialization finishes, we have a folder containing a new NodeJS project. The package.json file is set up to install the needed parts of CDK and to provide some scripts for using the CDK CLI.

As you can see the CDK CLI is installed as a development dependency and the core package is installed too. To make sure you use the correct version of the CDK CLI in your following command you can use the provided NPM script by using npm run cdk -- <command> which uses the local version of CDK instead of your global one. This also makes sure that you do not need to install CDK CLI on your CI system.

If you want to use CDK constructs in your application, and you want to do this, you need to install the corresponding packages in the dependencies section here. These packages are named @aws-cdk/aws-<service> and exist for every AWS service with CloudFormation support and also for higher-level patterns the CDK provides. A future version of CDK will fold all these packages into one module called monocdk but this will not happen earlier than v2 of the CDK.

For your CDK dependencies, you have to make sure that all use the exact same version and you should definitely pin the version to a fixed string instead of using semver in NPM. The CDK packages are not compatible with each other in different versions, no matter if it is a major, minor or patch release.

You can achieve this by removing the ^ character in front of the version. To prevent other versions from being installed, I recommend adding new dependencies by duplication a line in this file instead of using npm install --save <package>.

For convenience, we can also add additional commands to the scripts section of the package.json file. By adding scripts for deployment, showing diffs, and removing the stacks, we do not need to memorize the commands later on. So our new scripts section should look like this:

"scripts": {
  "test": "jest",
  "cdk": "cdk",
  "diff": "cdk diff CdkDemoStack",
  "deploy": "cdk deploy CdkDemoStack",
  "destroy": "cdk destroy CdkDemoStack"
},

Folder structure

The CDK initialization created three subfolders in your project. The bin/ folder contains your CDK application definition, the lib/ folder contains your stacks and constructs, and the tst/ folder is the place to store your unit tests for your code.

Adding constructs

At first, we will have a look at the definition of our stack and add some constructs to it. We want to add an SNS topic, so we need to add the service dependency to our package.json file.

"dependencies": {
  "@aws-cdk/core": "1.54.0",
  "@aws-cdk/aws-sns": "1.54.0",
  "source-map-support": "^0.5.16"
}

In our lib/cdk-demo-stack.ts file we can then create our stack. But let's look at this file first.

import * as cdk from '@aws-cdk/core';

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

    // The code that defines your stack goes here
  }
}

At the top, we import the CDK library for later use. Here we need to add all the additional libraries we want to use. We then export a class representing our stack that extends the CDK Stack class. The constructor of a stack and nearly all other CDK constructs follows this pattern:

scope argument defining the location of this construct in the hierarchy tree.
scope-unique id of the construct to identity it. This will be part of the logical name in CloudFormation later.
class-specific properties object with additional settings.

For our stack class, we will just forward these arguments to the inherited constructor. We can then define our nested element inside this method.

We can now import the SNS library at the top of the file and then instantiate a new object of the imported class Topic. The resulting file looks like this:

import * as cdk from '@aws-cdk/core';
import * as sns from '@aws-cdk/aws-sns';

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

    new sns.Topic(this, 'MyTopic', {
      displayName: 'MySuperTopic',
    });
  }
}

Deploy the infrastructure

We are now almost ready to deploy our infrastructure into our AWS account. Let's have a look at our application configuration.

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from '@aws-cdk/core';
import { CdkDemoStack } from '../lib/cdk-demo-stack';

const app = new cdk.App();
new CdkDemoStack(app, 'CdkDemoStack');

This file tells CDK to create a new application that consists of one stack named CdkDemoStack that uses our export class as the definition. To make sure that we are deploying the code into the correct AWS account and to be prepared for advanced features like resource lookups and cross-account deployments, we should pin the stack instance to a concrete AWS account and region. We do this by configuring the env parameter of our stack properties.

new CdkDemoStack(app, 'CdkDemoStack', {
  env: {
    account: '123456789012', // Replace with your account id
    region: 'eu-central-1',
  },
});

By running npm run cdk -- synth we can now generate our CloudFormation template based on our stack definition. The resulting template is written to the cdk.out folder.

{
  "Resources": {
    "MyTopic86869434": {
      "Type": "AWS::SNS::Topic",
      "Properties": {
        "DisplayName": "MySuperTopic"
      },
      "Metadata": {
        "aws:cdk:path": "CdkDemoStack/MyTopic/Resource"
      }
    }
  }
}

Using the commands in our scripts section of the project configuration we can then deploy this stack into our AWS account.

To clean up, the stack we can run the destroy command, and CDK and CloudFormation will remove all created resources.

Conclusion

In this demo, we initialized a new CDK app using cdk init and added an SNS topic. We then synthesized, deployed, and destroyed the infrastructure using the CDK CLI and CloudFormation.

One of the most important things to remember is the pinning of versions inside your package.json file as mixed versions of CDK libraries lead to a lot of issues that are hard to debug.