or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-aws-cdk--aws-cloudwatch-actions

CloudWatch alarm action implementations for AWS CDK v1 framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-cdk/aws-cloudwatch-actions@1.204.x

To install, run

npx @tessl/cli install tessl/npm-aws-cdk--aws-cloudwatch-actions@1.204.0

index.mddocs/

AWS CDK CloudWatch Actions

AWS CDK CloudWatch Actions provides a comprehensive set of alarm action implementations for the AWS CDK v1 framework. It enables automated responses to CloudWatch alarms including EC2 instance management, SNS notifications, SSM OpsCenter item creation, and autoscaling actions.

Package Information

  • Package Name: @aws-cdk/aws-cloudwatch-actions
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-cdk/aws-cloudwatch-actions

Core Imports

import * as actions from "@aws-cdk/aws-cloudwatch-actions";

For specific imports:

import { Ec2Action, Ec2InstanceAction, SnsAction, SsmAction, OpsItemSeverity } from "@aws-cdk/aws-cloudwatch-actions";

CommonJS:

const actions = require("@aws-cdk/aws-cloudwatch-actions");

Basic Usage

import * as cloudwatch from "@aws-cdk/aws-cloudwatch";
import * as actions from "@aws-cdk/aws-cloudwatch-actions";
import * as sns from "@aws-cdk/aws-sns";

// Create a CloudWatch alarm
const alarm = new cloudwatch.Alarm(stack, "MyAlarm", {
  metric: new cloudwatch.Metric({
    namespace: "AWS/EC2",
    metricName: "CPUUtilization",
    dimensionsMap: { InstanceId: "i-1234567890abcdef0" }
  }),
  threshold: 80,
  evaluationPeriods: 2
});

// Add EC2 action to reboot instance when alarm triggers
alarm.addAlarmAction(new actions.Ec2Action(actions.Ec2InstanceAction.REBOOT));

// Add SNS notification
const topic = new sns.Topic(stack, "AlarmTopic");
alarm.addAlarmAction(new actions.SnsAction(topic));

// Add SSM OpsCenter item creation
alarm.addAlarmAction(new actions.SsmAction(
  actions.OpsItemSeverity.HIGH,
  actions.OpsItemCategory.PERFORMANCE
));

Architecture

AWS CDK CloudWatch Actions is built around the CloudWatch alarm action pattern:

  • Action Classes: Each action type implements the cloudwatch.IAlarmAction interface
  • ARN Generation: Actions generate appropriate AWS service ARNs based on the action type
  • CDK Integration: Seamless integration with AWS CDK Stack and Construct patterns
  • Type Safety: Full TypeScript support with strongly-typed enums and interfaces

All action classes follow the same pattern:

  1. Accept action-specific parameters in constructor
  2. Implement bind(scope: Construct, alarm: IAlarm): AlarmActionConfig method
  3. Return appropriate ARN for the AWS service integration

Capabilities

EC2 Instance Actions

Control EC2 instances directly from CloudWatch alarms with stop, terminate, recover, and reboot actions.

class Ec2Action implements cloudwatch.IAlarmAction {
  constructor(instanceAction: Ec2InstanceAction);
  bind(scope: Construct, alarm: cloudwatch.IAlarm): cloudwatch.AlarmActionConfig;
}

enum Ec2InstanceAction {
  STOP = "stop",
  TERMINATE = "terminate", 
  RECOVER = "recover",
  REBOOT = "reboot"
}

Usage Examples:

import * as actions from "@aws-cdk/aws-cloudwatch-actions";

// Reboot instance when alarm triggers
const rebootAction = new actions.Ec2Action(actions.Ec2InstanceAction.REBOOT);
alarm.addAlarmAction(rebootAction);

// Stop instance for cost savings
const stopAction = new actions.Ec2Action(actions.Ec2InstanceAction.STOP);
alarm.addAlarmAction(stopAction);

// Recover instance from system failure
const recoverAction = new actions.Ec2Action(actions.Ec2InstanceAction.RECOVER);
alarm.addAlarmAction(recoverAction);

// Terminate unhealthy instance
const terminateAction = new actions.Ec2Action(actions.Ec2InstanceAction.TERMINATE);
alarm.addAlarmAction(terminateAction);

SNS Notifications

Send notifications to SNS topics when alarms trigger, enabling email, SMS, or HTTP endpoint notifications.

class SnsAction implements cloudwatch.IAlarmAction {
  constructor(topic: sns.ITopic);
  bind(scope: Construct, alarm: cloudwatch.IAlarm): cloudwatch.AlarmActionConfig;
}

Usage Examples:

import * as sns from "@aws-cdk/aws-sns";
import * as actions from "@aws-cdk/aws-cloudwatch-actions";

// Create SNS topic
const alertTopic = new sns.Topic(stack, "AlertTopic");

// Add email subscription
alertTopic.addSubscription(new subscriptions.EmailSubscription("admin@company.com"));

// Create SNS action
const snsAction = new actions.SnsAction(alertTopic);
alarm.addAlarmAction(snsAction);

SSM OpsCenter Actions

Create AWS Systems Manager OpsCenter items for operational issue tracking with configurable severity and category.

class SsmAction implements cloudwatch.IAlarmAction {
  constructor(severity: OpsItemSeverity, category?: OpsItemCategory);
  bind(scope: Construct, alarm: cloudwatch.IAlarm): cloudwatch.AlarmActionConfig;
}

enum OpsItemSeverity {
  CRITICAL = "1",
  HIGH = "2", 
  MEDIUM = "3",
  LOW = "4"
}

enum OpsItemCategory {
  AVAILABILITY = "Availability",
  COST = "Cost",
  PERFORMANCE = "Performance", 
  RECOVERY = "Recovery",
  SECURITY = "Security"
}

Usage Examples:

import * as actions from "@aws-cdk/aws-cloudwatch-actions";

// Create critical performance OpsItem
const criticalOpsAction = new actions.SsmAction(
  actions.OpsItemSeverity.CRITICAL,
  actions.OpsItemCategory.PERFORMANCE
);
alarm.addAlarmAction(criticalOpsAction);

// Create medium severity OpsItem without category
const mediumOpsAction = new actions.SsmAction(actions.OpsItemSeverity.MEDIUM);
alarm.addAlarmAction(mediumOpsAction);

// Create security-related OpsItem
const securityOpsAction = new actions.SsmAction(
  actions.OpsItemSeverity.HIGH,
  actions.OpsItemCategory.SECURITY
);
alarm.addAlarmAction(securityOpsAction);

Auto Scaling Actions

Trigger Auto Scaling group scaling policies in response to CloudWatch alarms.

class AutoScalingAction implements cloudwatch.IAlarmAction {
  constructor(stepScalingAction: autoscaling.StepScalingAction);
  bind(scope: Construct, alarm: cloudwatch.IAlarm): cloudwatch.AlarmActionConfig;
}

Usage Examples:

import * as autoscaling from "@aws-cdk/aws-autoscaling";
import * as actions from "@aws-cdk/aws-cloudwatch-actions";

// Assume you have an Auto Scaling group
declare const autoScalingGroup: autoscaling.AutoScalingGroup;

// Create step scaling policy
const scaleUpPolicy = autoScalingGroup.scaleOnMetric("ScaleUp", {
  metric: cpuUtilization,
  scalingSteps: [
    { upper: 50, change: +1 },
    { lower: 85, change: +2 }
  ],
  adjustmentType: autoscaling.AdjustmentType.CHANGE_IN_CAPACITY
});

// Create action from scaling policy
const scaleUpAction = new actions.AutoScalingAction(scaleUpPolicy);
alarm.addAlarmAction(scaleUpAction);

Application Auto Scaling Actions

Trigger Application Auto Scaling policies for services like ECS, DynamoDB, and other AWS services.

class ApplicationScalingAction implements cloudwatch.IAlarmAction {
  constructor(stepScalingAction: appscaling.StepScalingAction);
  bind(scope: Construct, alarm: cloudwatch.IAlarm): cloudwatch.AlarmActionConfig;
}

Usage Examples:

import * as appscaling from "@aws-cdk/aws-applicationautoscaling";
import * as actions from "@aws-cdk/aws-cloudwatch-actions";

// Assume you have a scalable target (e.g., ECS service)
declare const scalableTarget: appscaling.ScalableTarget;

// Create step scaling policy
const appScalingPolicy = scalableTarget.scaleOnMetric("ScaleOnCPU", {
  metric: cpuUtilization,
  scalingSteps: [
    { upper: 50, change: +1 },
    { lower: 85, change: +2 }
  ],
  adjustmentType: appscaling.AdjustmentType.CHANGE_IN_CAPACITY
});

// Create action from application scaling policy
const appScalingAction = new actions.ApplicationScalingAction(appScalingPolicy);
alarm.addAlarmAction(appScalingAction);

Error Handling

All action classes follow standard AWS CDK error handling patterns:

  • Construction Errors: Invalid parameters throw errors during construction
  • Binding Errors: ARN generation errors occur during the bind() method call
  • Runtime Errors: AWS service integration errors are handled by CloudWatch and the respective AWS services

Common error scenarios:

  • Invalid EC2 instance action types
  • Missing or invalid SNS topic references
  • Incorrect OpsItem severity or category values
  • Invalid scaling policy references

Dependencies

This package requires the following AWS CDK v1 dependencies:

  • @aws-cdk/aws-cloudwatch - Core CloudWatch interfaces and constructs
  • @aws-cdk/aws-sns - SNS topic interface
  • @aws-cdk/aws-autoscaling - Auto Scaling constructs
  • @aws-cdk/aws-applicationautoscaling - Application Auto Scaling constructs
  • @aws-cdk/core - Core CDK constructs (Stack, Construct)
  • constructs - Construct base classes