Skip to main content

Defined in: src/progressive-lambda/progressive-lambda.ts:321

A progressive deployment Lambda function with integrated CloudWatch monitoring and CodeDeploy automation.

Overview​

This construct provides a production-ready Lambda function with:

  • Progressive Deployments: Uses AWS CodeDeploy for safe, automated rollouts
  • Error Monitoring: CloudWatch alarms that trigger rollbacks on failures
  • Observability: Optional dashboard widgets and X-Ray tracing
  • Security Best Practices: Latest runtime, SSL enforcement guidance, and proper IAM roles

Key Features​

Progressive Deployment​

  • Creates a Lambda alias for traffic management
  • Integrates with CodeDeploy for controlled traffic shifting
  • Supports various deployment strategies (linear, canary, blue/green)

Monitoring & Alerting​

  • CloudWatch alarm based on custom error metrics
  • Automatic rollback when error threshold is breached
  • SNS notifications for deployment events
  • Optional dashboard widgets for real-time monitoring

Security & Compliance​

  • Uses latest Node.js runtime by default (AwsSolutions-L1)
  • X-Ray tracing enabled for request tracking
  • Follows AWS Well-Architected Framework principles
  • CDK Nag compliant with documented exceptions

Usage Patterns​

Basic Usage​

const app = new codeDeploy.LambdaApplication(this, 'MyApp');
const alertTopic = new sns.Topic(this, 'Alerts');

const lambda = new ProgressiveLambda(this, 'ProcessorFunction', {
  entry: 'src/handlers/processor.ts',
  stageName: 'prod',
  application: app,
  deploymentConfig: codeDeploy.LambdaDeploymentConfig.LINEAR_10PERCENT_EVERY_1MINUTE,
  alarmEnabled: true,
  snsTopic: alertTopic,
  namespace: 'ECommerce',
  serviceName: 'OrderProcessor',
  metricSuccessName: 'ProcessedOrders',
  metricSuccessNameTitle: 'Successfully Processed Orders',
  metricErrorName: 'ProcessingErrors',
  metricErrorNameTitle: 'Order Processing Failures',
  region: 'us-east-1'
});

With Dashboard Widgets​

const lambda = new ProgressiveLambda(this, 'ProcessorFunction', {
  // ... other props
  createWidget: true  // Creates dashboard widgets
});

// Add widgets to a dashboard
const dashboard = new cloudwatch.Dashboard(this, 'MyDashboard');
dashboard.addWidgets(...lambda.widgets);

Canary Deployment​

const lambda = new ProgressiveLambda(this, 'RiskyFeature', {
  // ... other props
  deploymentConfig: codeDeploy.LambdaDeploymentConfig.CANARY_10PERCENT_5MINUTES,
  // Deploy 10% of traffic, wait 5 minutes, then proceed or rollback
});

Metrics Integration​

Your Lambda function code should publish the specified success and error metrics:

import { CloudWatch } from 'aws-sdk';
const cloudwatch = new CloudWatch();

export const handler = async (event) => {
  try {
    // Process event
    await processOrder(event);

    // Publish success metric
    await cloudwatch.putMetricData({
      Namespace: 'ECommerce',
      MetricData: [{
        MetricName: 'ProcessedOrders',
        Value: 1,
        Dimensions: [{ Name: 'service', Value: 'OrderProcessor' }]
      }]
    }).promise();
  } catch (error) {
    // Publish error metric
    await cloudwatch.putMetricData({
      Namespace: 'ECommerce',
      MetricData: [{
        MetricName: 'ProcessingErrors',
        Value: 1,
        Dimensions: [{ Name: 'service', Value: 'OrderProcessor' }]
      }]
    }).promise();
    throw error;
  }
};

Alarm Configuration​

  • Threshold: 10 errors within 1 minute triggers alarm
  • Evaluation: Single evaluation period to enable fast rollbacks
  • Missing Data: Treated as NOT_BREACHING to avoid false alarms
  • Actions: SNS notification and CodeDeploy rollback

See​

Remarks​

Security Considerations:

  • Uses latest Node.js runtime by default (AwsSolutions-L1 compliance)
  • Requires user-provided SNS topic to enforce SSL policies (AwsSolutions-SNS3)
  • Uses AWS managed policies for Lambda execution (AwsSolutions-IAM4 - acceptable for standard roles)
  • X-Ray tracing requires wildcard IAM permissions (AwsSolutions-IAM5 - acceptable for tracing)

Extends​

  • Construct

Constructors​

Constructor​

new ProgressiveLambda(scope, id, props): ProgressiveLambda

Defined in: src/progressive-lambda/progressive-lambda.ts:406

Creates a new ProgressiveLambda construct.

Parameters​

scope​

Construct

The construct scope

id​

string

The construct identifier

props​

ProgressiveLambdaProps

Configuration properties

Returns​

ProgressiveLambda

Throws​

When required properties are missing or invalid

Example​

const lambda = new ProgressiveLambda(this, 'MyLambda', {
  entry: 'src/handler.ts',
  stageName: 'prod',
  application: myCodeDeployApp,
  deploymentConfig: codeDeploy.LambdaDeploymentConfig.LINEAR_10PERCENT_EVERY_1MINUTE,
  alarmEnabled: true,
  snsTopic: mySnsTopic,
  namespace: 'MyApp',
  serviceName: 'MyService',
  metricSuccessName: 'Success',
  metricSuccessNameTitle: 'Successful Operations',
  metricErrorName: 'Errors',
  metricErrorNameTitle: 'Failed Operations',
  region: 'us-east-1'
});

Overrides​

Construct.constructor

Properties​

alarm​

readonly alarm: Alarm

Defined in: src/progressive-lambda/progressive-lambda.ts:344

CloudWatch alarm that monitors error metrics.

Triggers when error count exceeds threshold, causing CodeDeploy to automatically rollback the deployment to the previous version.

alias​

readonly alias: Alias

Defined in: src/progressive-lambda/progressive-lambda.ts:336

Lambda alias for traffic management during deployments.

Points to the current version and is used by CodeDeploy to shift traffic between versions during progressive deployments.

deploymentGroup​

readonly deploymentGroup: LambdaDeploymentGroup

Defined in: src/progressive-lambda/progressive-lambda.ts:352

CodeDeploy deployment group managing progressive rollouts.

Orchestrates traffic shifting between Lambda versions based on the configured deployment strategy and alarm status.

lambda​

readonly lambda: NodejsFunction

Defined in: src/progressive-lambda/progressive-lambda.ts:328

The underlying Lambda function.

Provides access to the NodejsFunction for additional configuration, permissions, or integration with other AWS services.

node​

readonly node: Node

Defined in: node_modules/.pnpm/constructs@10.4.2/node_modules/constructs/lib/construct.d.ts:266

The tree node.

Inherited from​

Construct.node

widgets​

readonly widgets: ConcreteWidget[] = []

Defined in: src/progressive-lambda/progressive-lambda.ts:364

CloudWatch dashboard widgets for monitoring (when enabled).

Contains three widgets when createWidget is true:

  1. Success metric single value widget
  2. Error metric single value widget
  3. Alarm status widget

Add to dashboards using: dashboard.addWidgets(...lambda.widgets)

Methods​

toString()​

toString(): string

Defined in: node_modules/.pnpm/constructs@10.4.2/node_modules/constructs/lib/construct.d.ts:279

Returns a string representation of this construct.

Returns​

string

Inherited from​

Construct.toString

isConstruct()​

static isConstruct(x): x is Construct

Defined in: node_modules/.pnpm/constructs@10.4.2/node_modules/constructs/lib/construct.d.ts:262

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters​

x​

any

Any object

Returns​

x is Construct

true if x is an object created from a class which extends Construct.

Inherited from​

Construct.isConstruct