Step scaling policies adjust target capacity in configurable steps based on metric values. The size of each step is configurable based on the metric's distance from its alarm threshold.
Creates CloudWatch alarms and scaling policies that respond to metric breaches with configured scaling steps.
/**
* Define a scaling strategy which scales depending on absolute values of some metric.
* Implemented using CloudWatch alarms and Step Scaling Policies.
*/
class StepScalingPolicy extends Construct {
/**
* Create a new StepScalingPolicy
* @param scope - CDK construct scope
* @param id - Construct identifier
* @param props - Step scaling policy properties
*/
constructor(scope: Construct, id: string, props: StepScalingPolicyProps);
/**
* CloudWatch alarm for lower threshold (scale in)
*/
readonly lowerAlarm?: cloudwatch.Alarm;
/**
* Scaling action for lower threshold
*/
readonly lowerAction?: StepScalingAction;
/**
* CloudWatch alarm for upper threshold (scale out)
*/
readonly upperAlarm?: cloudwatch.Alarm;
/**
* Scaling action for upper threshold
*/
readonly upperAction?: StepScalingAction;
}
/**
* Properties for step scaling policy without scalingTarget
*/
interface BasicStepScalingPolicyProps {
/**
* Metric to scale on
*/
readonly metric: cloudwatch.IMetric;
/**
* The intervals for scaling
* Maps a range of metric values to a particular scaling behavior
*/
readonly scalingSteps: ScalingInterval[];
/**
* How the adjustment numbers inside 'intervals' are interpreted
* @default ChangeInCapacity
*/
readonly adjustmentType?: AdjustmentType;
/**
* Grace period after scaling activity
* Subsequent scale outs during cooldown are squashed so only the biggest happens.
* Subsequent scale ins during cooldown are ignored.
* @default No cooldown period
*/
readonly cooldown?: cdk.Duration;
/**
* Minimum absolute number to adjust capacity with as result of percentage scaling
* Only when using AdjustmentType = PercentChangeInCapacity
* @default No minimum scaling effect
*/
readonly minAdjustmentMagnitude?: number;
/**
* How many evaluation periods of the metric to wait before triggering a scaling action
* Raising this value smooths out the metric at expense of slower response times
* @default 1
*/
readonly evaluationPeriods?: number;
/**
* The number of data points out of evaluation periods that must be breaching
* Creates an "M out of N" alarm where this is M and evaluationPeriods is N
* @default evaluationPeriods
*/
readonly datapointsToAlarm?: number;
/**
* Aggregation to apply to all data points over the evaluation periods
* Only has meaning if evaluationPeriods != 1
* @default The statistic from the metric if applicable (MIN, MAX, AVERAGE), otherwise AVERAGE
*/
readonly metricAggregationType?: MetricAggregationType;
}
/**
* Properties for step scaling policy with scalingTarget
*/
interface StepScalingPolicyProps extends BasicStepScalingPolicyProps {
/**
* The scaling target
*/
readonly scalingTarget: IScalableTarget;
}
/**
* A range of metric values in which to apply a certain scaling operation
*/
interface ScalingInterval {
/**
* The lower bound of the interval
* The scaling adjustment will be applied if the metric is higher than this value
* @default Threshold automatically derived from neighbouring intervals
*/
readonly lower?: number;
/**
* The upper bound of the interval
* The scaling adjustment will be applied if the metric is lower than this value
* @default Threshold automatically derived from neighbouring intervals
*/
readonly upper?: number;
/**
* The capacity adjustment to apply in this interval
* - ChangeInCapacity: add the adjustment to the current capacity
* - PercentChangeInCapacity: add/remove the given percentage of current capacity
* - ExactCapacity: set the capacity to this number (must be positive)
*/
readonly change: number;
}Usage Examples:
import * as appscaling from '@aws-cdk/aws-applicationautoscaling';
import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
// CPU-based step scaling
const cpuMetric = new cloudwatch.Metric({
namespace: 'AWS/ECS',
metricName: 'CPUUtilization',
dimensionsMap: {
ServiceName: ecsService.serviceName,
ClusterName: cluster.clusterName,
},
});
target.scaleOnMetric('CpuScaling', {
metric: cpuMetric,
scalingSteps: [
{ upper: 10, change: -1 }, // Scale in by 1 if CPU < 10%
{ lower: 50, change: +1 }, // Scale out by 1 if CPU >= 50%
{ lower: 70, change: +3 }, // Scale out by 3 if CPU >= 70%
],
adjustmentType: appscaling.AdjustmentType.CHANGE_IN_CAPACITY,
cooldown: cdk.Duration.minutes(5),
});
// Percentage-based scaling with multiple datapoints
target.scaleOnMetric('MemoryScaling', {
metric: memoryMetric,
scalingSteps: [
{ upper: 30, change: -10 }, // Scale in by 10%
{ lower: 80, change: +20 }, // Scale out by 20%
],
adjustmentType: appscaling.AdjustmentType.PERCENT_CHANGE_IN_CAPACITY,
minAdjustmentMagnitude: 2,
evaluationPeriods: 3,
datapointsToAlarm: 2,
});Lower-level scaling action that can be triggered by CloudWatch alarms.
/**
* Define a step scaling action
* This kind of scaling policy adjusts target capacity in configurable steps
* Must be used as the target of a CloudWatch alarm to take effect
*/
class StepScalingAction extends Construct {
/**
* Create a new StepScalingAction
* @param scope - CDK construct scope
* @param id - Construct identifier
* @param props - Step scaling action properties
*/
constructor(scope: Construct, id: string, props: StepScalingActionProps);
/**
* ARN of the scaling policy
*/
readonly scalingPolicyArn: string;
/**
* Add an adjustment interval to the ScalingAction
* @param adjustment - The adjustment tier configuration
*/
addAdjustment(adjustment: AdjustmentTier): void;
}
/**
* Properties for a scaling policy
*/
interface StepScalingActionProps {
/**
* The scalable target
*/
readonly scalingTarget: IScalableTarget;
/**
* A name for the scaling policy
* @default Automatically generated name
*/
readonly policyName?: string;
/**
* How the adjustment numbers are interpreted
* @default ChangeInCapacity
*/
readonly adjustmentType?: AdjustmentType;
/**
* Grace period after scaling activity
* For scale out policies, multiple scale outs during cooldown are squashed
* For scale in policies, subsequent scale ins during cooldown are ignored
* @default No cooldown period
*/
readonly cooldown?: cdk.Duration;
/**
* Minimum absolute number to adjust capacity with as result of percentage scaling
* Only when using AdjustmentType = PercentChangeInCapacity
* @default No minimum scaling effect
*/
readonly minAdjustmentMagnitude?: number;
/**
* The aggregation type for the CloudWatch metrics
* @default Average
*/
readonly metricAggregationType?: MetricAggregationType;
}
/**
* An adjustment tier for step scaling
*/
interface AdjustmentTier {
/**
* What number to adjust the capacity with
* The number is interpreted as added capacity, new fixed capacity, or
* added percentage depending on the AdjustmentType
*/
readonly adjustment: number;
/**
* Lower bound where this scaling tier applies
* The scaling tier applies if the difference between metric value and
* alarm threshold is higher than this value
* @default -Infinity if this is the first tier, otherwise upperBound of previous tier
*/
readonly lowerBound?: number;
/**
* Upper bound where this scaling tier applies
* The scaling tier applies if the difference between metric value and
* alarm threshold is lower than this value
* @default +Infinity
*/
readonly upperBound?: number;
}Configuration enums for step scaling behavior.
/**
* How adjustment numbers are interpreted
*/
enum AdjustmentType {
/**
* Add the adjustment number to the current capacity
* A positive number increases capacity, negative decreases
*/
CHANGE_IN_CAPACITY = 'ChangeInCapacity',
/**
* Add this percentage of the current capacity to itself
* The number must be between -100 and 100
*/
PERCENT_CHANGE_IN_CAPACITY = 'PercentChangeInCapacity',
/**
* Make the capacity equal to the exact number given
*/
EXACT_CAPACITY = 'ExactCapacity',
}
/**
* How the scaling metric is going to be aggregated
*/
enum MetricAggregationType {
/**
* Average
*/
AVERAGE = 'Average',
/**
* Minimum
*/
MINIMUM = 'Minimum',
/**
* Maximum
*/
MAXIMUM = 'Maximum'
}