Skip to main content

Blue/Green Deployments

Blue/Green Deployment Instruction Set – AWS CDK + TypeScript

Purpose This instruction set defines the mandatory Blue/Green deployment patterns for Lambdas and API Gateways, ensuring zero-downtime updates and robust rollback strategies. This set can be applied in any repository or project where safe deployment practices are required.

Global Assumptions​

  • AWS CDK v2 is used
  • TypeScript with strict: true
  • All Lambda functions must support versioning and aliasing
  • API Gateway may be used in front of Lambdas and must support traffic shifting

Reason Explicit assumptions prevent Copilot or developers from generating deployments without rollback and versioning safety.

1. Lambda Deployment Rules​

  • Always deploy Lambdas using versioned aliases
  • Define a comprehensive rollback strategy for each Lambda deployment
  • Use aws-cdk-lib constructs for Alias and Version objects
  • No direct updates to Lambda functions without aliases

Example​

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

const version = fn.currentVersion;
const aliasBlue = new lambda.Alias(this, 'BlueAlias', {
  aliasName: 'blue',
  version,
});

2. API Gateway Deployment Rules​

  • Deploy API Gateway in front of Lambda when external access is required
  • Enable traffic shifting for Blue/Green deployments
  • Route traffic to Lambda aliases (blue/green) instead of raw Lambda functions

Example​

const api = new apigateway.RestApi(this, 'MyApi');
const lambdaIntegrationBlue = new apigateway.LambdaIntegration(aliasBlue);
api.root.addMethod('GET', lambdaIntegrationBlue);

3. Rollback Strategy​

  • Define a rollback strategy for each Lambda alias
  • In case of errors, switch traffic to the previous stable alias
  • Use CloudWatch alarms to trigger rollback if required

Example Mermaid Diagram​

Reason Ensures zero-downtime deployments and allows quick, reliable rollbacks.

Source AWS Lambda Deployment Strategies https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html

4. Git-Based Trunk Deployment Strategy​

Trunk-Based Development Rules​

  • All development happens on short-lived feature branches off main
  • Feature branches must be merged via approved Pull Requests
  • main branch is always deployable and protected
  • Blue/Green deployments are triggered by merged PRs to main

Branch Protection Rules​

Branch: main
- Require pull request reviews (minimum 1 approval)
- Require status checks to pass (tests, lint)
- Require branches to be up to date before merging
- No direct commits to main

Deployment Workflow​

  1. Feature Development: Developer creates short-lived branch from main
  2. Pull Request: Developer opens PR with changes
  3. CI Checks: Automated tests, linting, and CDK synth run
  4. Code Review: Team reviews and approves PR
  5. Merge to Main: PR merged to main triggers deployment
  6. Blue Deployment: New version deployed to "blue" alias
  7. Traffic Shift: Gradual traffic shift from green to blue (e.g., 10%, 50%, 100%)
  8. Monitor: CloudWatch alarms monitor error rates and latency
  9. Rollback: Automatic rollback to "green" if alarms trigger
  10. Promote: If successful, "blue" becomes new "green" for next deployment

GitHub Actions Workflow Structure​

name: Blue-Green Deploy

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Tests
        run: npm ci && npm test

  deploy-blue:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Blue
        run: npm run deploy:blue
      
      - name: Shift Traffic
        run: npm run traffic:shift
      
      - name: Monitor
        run: npm run monitor:alarms

Mermaid Workflow Diagram​

Reason Integrating blue-green deployments with trunk-based Git workflow ensures:

  • Code review before deployment
  • Automated testing and validation
  • Safe, gradual traffic shifting
  • Quick rollback capability
  • Audit trail of all changes

Source

5. Copilot Instructions When This Set is Applied​

  • Enforce alias usage for all Lambdas
  • Include rollback logic in generated code
  • Always integrate API Gateway with Lambda aliases when external endpoints are required
  • Include Mermaid diagram as part of documentation for clarity
  • Never generate direct Lambda updates without aliasing
  • Generate GitHub Actions workflows for trunk-based blue-green deployments
  • Ensure PR templates include deployment checklist
  • Configure CloudWatch alarms for automated rollback

This instruction set is modular and can be applied to any repository alongside the main TypeScript/CDK instructions when Blue/Green deployment patterns are required.