Namespace Amazon.CDK.AWS.ApplicationAutoScaling

AWS Auto Scaling Construct Library

---

AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.

For more information on how to migrate, see the Migrating to AWS CDK v2 guide.

Application AutoScaling is used to configure autoscaling for all services other than scaling EC2 instances. For example, you will use this to scale ECS tasks, DynamoDB capacity, Spot Fleet sizes, Comprehend document classification endpoints, Lambda function provisioned concurrency and more.

As a CDK user, you will probably not have to interact with this library directly; instead, it will be used by other construct libraries to offer AutoScaling features for their own constructs.

This document will describe the general autoscaling features and concepts; your particular service may offer only a subset of these.

AutoScaling basics

Resources can offer one or more attributes to autoscale, typically representing some capacity dimension of the underlying service. For example, a DynamoDB Table offers autoscaling of the read and write capacity of the table proper and its Global Secondary Indexes, an ECS Service offers autoscaling of its task count, an RDS Aurora cluster offers scaling of its replica count, and so on.

When you enable autoscaling for an attribute, you specify a minimum and a maximum value for the capacity. AutoScaling policies that respond to metrics will never go higher or lower than the indicated capacity (but scheduled scaling actions might, see below).

There are three ways to scale your capacity:

The general pattern of autoscaling will look like this:

SomeScalableResource resource;


var capacity = resource.AutoScaleCapacity(new Caps {
    MinCapacity = 5,
    MaxCapacity = 100
});

Step Scaling

This type of scaling scales in and out in deterministic steps that you configure, in response to metric values. For example, your scaling strategy to scale in response to CPU usage might look like this:

 Scaling        -1          (no change)          +1       +3
            │        │                       │        │        │
            ├────────┼───────────────────────┼────────┼────────┤
            │        │                       │        │        │
CPU usage   0%      10%                     50%       70%     100%

(Note that this is not necessarily a recommended scaling strategy, but it's a possible one. You will have to determine what thresholds are right for you).

You would configure it like this:

ScalableAttribute capacity;
Metric cpuUtilization;


capacity.ScaleOnMetric("ScaleToCPU", new BasicStepScalingPolicyProps {
    Metric = cpuUtilization,
    ScalingSteps = new [] { new ScalingInterval { Upper = 10, Change = -1 }, new ScalingInterval { Lower = 50, Change = +1 }, new ScalingInterval { Lower = 70, Change = +3 } },

    // Change this to AdjustmentType.PercentChangeInCapacity to interpret the
    // 'change' numbers before as percentages instead of capacity counts.
    AdjustmentType = AdjustmentType.CHANGE_IN_CAPACITY
});

The AutoScaling construct library will create the required CloudWatch alarms and AutoScaling policies for you.

Scaling based on multiple datapoints

The Step Scaling configuration above will initiate a scaling event when a single datapoint of the scaling metric is breaching a scaling step breakpoint. In cases where you might want to initiate scaling actions on a larger number of datapoints (ie in order to smooth out randomness in the metric data), you can use the optional evaluationPeriods and datapointsToAlarm properties:

ScalableAttribute capacity;
Metric cpuUtilization;


capacity.ScaleOnMetric("ScaleToCPUWithMultipleDatapoints", new BasicStepScalingPolicyProps {
    Metric = cpuUtilization,
    ScalingSteps = new [] { new ScalingInterval { Upper = 10, Change = -1 }, new ScalingInterval { Lower = 50, Change = +1 }, new ScalingInterval { Lower = 70, Change = +3 } },

    // if the cpuUtilization metric has a period of 1 minute, then data points
    // in the last 10 minutes will be evaluated
    EvaluationPeriods = 10,

    // Only trigger a scaling action when 6 datapoints out of the last 10 are
    // breaching. If this is left unspecified, then ALL datapoints in the
    // evaluation period must be breaching to trigger a scaling action
    DatapointsToAlarm = 6
});

Target Tracking Scaling

This type of scaling scales in and out in order to keep a metric (typically representing utilization) around a value you prefer. This type of scaling is typically heavily service-dependent in what metric you can use, and so different services will have different methods here to set up target tracking scaling.

The following example configures the read capacity of a DynamoDB table to be around 60% utilization:

using Amazon.CDK.AWS.DynamoDB;

Table table;


var readCapacity = table.AutoScaleReadCapacity(new EnableScalingProps {
    MinCapacity = 10,
    MaxCapacity = 1000
});
readCapacity.ScaleOnUtilization(new UtilizationScalingProps {
    TargetUtilizationPercent = 60
});

Scheduled Scaling

This type of scaling is used to change capacities based on time. It works by changing the minCapacity and maxCapacity of the attribute, and so can be used for two purposes:

The following schedule expressions can be used:

Of these, the cron expression is the most useful but also the most complicated. A schedule is expressed as a cron expression. The Schedule class has a cron method to help build cron expressions.

The following example scales the fleet out in the morning, and lets natural scaling take over at night:

SomeScalableResource resource;


var capacity = resource.AutoScaleCapacity(new Caps {
    MinCapacity = 1,
    MaxCapacity = 50
});

capacity.ScaleOnSchedule("PrescaleInTheMorning", new ScalingSchedule {
    Schedule = Schedule.Cron(new CronOptions { Hour = "8", Minute = "0" }),
    MinCapacity = 20
});

capacity.ScaleOnSchedule("AllowDownscalingAtNight", new ScalingSchedule {
    Schedule = Schedule.Cron(new CronOptions { Hour = "20", Minute = "0" }),
    MinCapacity = 1
});

Examples

Lambda Provisioned Concurrency Auto Scaling

using Amazon.CDK.AWS.Lambda;

Code code;


var handler = new Function(this, "MyFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_7,
    Handler = "index.handler",
    Code = code,

    ReservedConcurrentExecutions = 2
});

var fnVer = handler.CurrentVersion;

var target = new ScalableTarget(this, "ScalableTarget", new ScalableTargetProps {
    ServiceNamespace = ServiceNamespace.LAMBDA,
    MaxCapacity = 100,
    MinCapacity = 10,
    ResourceId = $"function:{handler.functionName}:{fnVer.version}",
    ScalableDimension = "lambda:function:ProvisionedConcurrency"
});

target.ScaleToTrackMetric("PceTracking", new BasicTargetTrackingScalingPolicyProps {
    TargetValue = 0.9,
    PredefinedMetric = PredefinedMetric.LAMBDA_PROVISIONED_CONCURRENCY_UTILIZATION
});

ElastiCache Redis shards scaling with target value

var shardsScalableTarget = new ScalableTarget(this, "ElastiCacheRedisShardsScalableTarget", new ScalableTargetProps {
    ServiceNamespace = ServiceNamespace.ELASTICACHE,
    ScalableDimension = "elasticache:replication-group:NodeGroups",
    MinCapacity = 2,
    MaxCapacity = 10,
    ResourceId = "replication-group/main-cluster"
});

shardsScalableTarget.ScaleToTrackMetric("ElastiCacheRedisShardsCPUUtilization", new BasicTargetTrackingScalingPolicyProps {
    TargetValue = 20,
    PredefinedMetric = PredefinedMetric.ELASTICACHE_PRIMARY_ENGINE_CPU_UTILIZATION
});

Classes

AdjustmentTier	An adjustment.
AdjustmentType	How adjustment numbers are interpreted.
BaseScalableAttribute	Represent an attribute for which autoscaling can be configured.
BaseScalableAttributeProps	Properties for a ScalableTableAttribute.
BaseTargetTrackingProps	Base interface for target tracking props.
BasicStepScalingPolicyProps
BasicTargetTrackingScalingPolicyProps	Properties for a Target Tracking policy that include the metric but exclude the target.
CfnScalableTarget	A CloudFormation `AWS::ApplicationAutoScaling::ScalableTarget`.
CfnScalableTarget.ScalableTargetActionProperty	`ScalableTargetAction` specifies the minimum and maximum capacity for the `ScalableTargetAction` property of the AWS::ApplicationAutoScaling::ScalableTarget ScheduledAction property type.
CfnScalableTarget.ScheduledActionProperty	`ScheduledAction` is a property of the AWS::ApplicationAutoScaling::ScalableTarget resource that specifies a scheduled action for a scalable target.
CfnScalableTarget.SuspendedStateProperty	`SuspendedState` is a property of the AWS::ApplicationAutoScaling::ScalableTarget resource that specifies whether the scaling activities for a scalable target are in a suspended state.
CfnScalableTargetProps	Properties for defining a `CfnScalableTarget`.
CfnScalingPolicy	A CloudFormation `AWS::ApplicationAutoScaling::ScalingPolicy`.
CfnScalingPolicy.CustomizedMetricSpecificationProperty	Contains customized metric specification information for a target tracking scaling policy for Application Auto Scaling.
CfnScalingPolicy.MetricDimensionProperty	`MetricDimension` specifies a name/value pair that is part of the identity of a CloudWatch metric for the `Dimensions` property of the AWS::ApplicationAutoScaling::ScalingPolicy CustomizedMetricSpecification property type. Duplicate dimensions are not allowed.
CfnScalingPolicy.PredefinedMetricSpecificationProperty	Contains predefined metric specification information for a target tracking scaling policy for Application Auto Scaling.
CfnScalingPolicy.StepAdjustmentProperty	`StepAdjustment` specifies a step adjustment for the `StepAdjustments` property of the AWS::ApplicationAutoScaling::ScalingPolicy StepScalingPolicyConfiguration property type.
CfnScalingPolicy.StepScalingPolicyConfigurationProperty	`StepScalingPolicyConfiguration` is a property of the AWS::ApplicationAutoScaling::ScalingPolicy resource that specifies a step scaling policy configuration for Application Auto Scaling.
CfnScalingPolicy.TargetTrackingScalingPolicyConfigurationProperty	`TargetTrackingScalingPolicyConfiguration` is a property of the AWS::ApplicationAutoScaling::ScalingPolicy resource that specifies a target tracking scaling policy configuration for Application Auto Scaling. Use a target tracking scaling policy to adjust the capacity of the specified scalable target in response to actual workloads, so that resource utilization remains at or near the target utilization value.
CfnScalingPolicyProps	Properties for defining a `CfnScalingPolicy`.
CronOptions	Options to configure a cron expression.
EnableScalingProps	Properties for enabling Application Auto Scaling.
MetricAggregationType	How the scaling metric is going to be aggregated.
PredefinedMetric	One of the predefined autoscaling metrics.
ScalableTarget	Define a scalable target.
ScalableTargetProps	Properties for a scalable target.
ScalingInterval	A range of metric values in which to apply a certain scaling operation.
ScalingSchedule	A scheduled scaling action.
Schedule	Schedule for scheduled scaling actions.
ServiceNamespace	The service that supports Application AutoScaling.
StepScalingAction	Define a step scaling action.
StepScalingActionProps	Properties for a scaling policy.
StepScalingPolicy	Define a scaling strategy which scales depending on absolute values of some metric.
StepScalingPolicyProps
TargetTrackingScalingPolicy
TargetTrackingScalingPolicyProps	Properties for a concrete TargetTrackingPolicy.

Interfaces

CfnScalableTarget.IScalableTargetActionProperty	`ScalableTargetAction` specifies the minimum and maximum capacity for the `ScalableTargetAction` property of the AWS::ApplicationAutoScaling::ScalableTarget ScheduledAction property type.
CfnScalableTarget.IScheduledActionProperty	`ScheduledAction` is a property of the AWS::ApplicationAutoScaling::ScalableTarget resource that specifies a scheduled action for a scalable target.
CfnScalableTarget.ISuspendedStateProperty	`SuspendedState` is a property of the AWS::ApplicationAutoScaling::ScalableTarget resource that specifies whether the scaling activities for a scalable target are in a suspended state.
CfnScalingPolicy.ICustomizedMetricSpecificationProperty	Contains customized metric specification information for a target tracking scaling policy for Application Auto Scaling.
CfnScalingPolicy.IMetricDimensionProperty	`MetricDimension` specifies a name/value pair that is part of the identity of a CloudWatch metric for the `Dimensions` property of the AWS::ApplicationAutoScaling::ScalingPolicy CustomizedMetricSpecification property type. Duplicate dimensions are not allowed.
CfnScalingPolicy.IPredefinedMetricSpecificationProperty	Contains predefined metric specification information for a target tracking scaling policy for Application Auto Scaling.
CfnScalingPolicy.IStepAdjustmentProperty	`StepAdjustment` specifies a step adjustment for the `StepAdjustments` property of the AWS::ApplicationAutoScaling::ScalingPolicy StepScalingPolicyConfiguration property type.
CfnScalingPolicy.IStepScalingPolicyConfigurationProperty	`StepScalingPolicyConfiguration` is a property of the AWS::ApplicationAutoScaling::ScalingPolicy resource that specifies a step scaling policy configuration for Application Auto Scaling.
CfnScalingPolicy.ITargetTrackingScalingPolicyConfigurationProperty	`TargetTrackingScalingPolicyConfiguration` is a property of the AWS::ApplicationAutoScaling::ScalingPolicy resource that specifies a target tracking scaling policy configuration for Application Auto Scaling. Use a target tracking scaling policy to adjust the capacity of the specified scalable target in response to actual workloads, so that resource utilization remains at or near the target utilization value.
IAdjustmentTier	An adjustment.
IBaseScalableAttributeProps	Properties for a ScalableTableAttribute.
IBaseTargetTrackingProps	Base interface for target tracking props.
IBasicStepScalingPolicyProps
IBasicTargetTrackingScalingPolicyProps	Properties for a Target Tracking policy that include the metric but exclude the target.
ICfnScalableTargetProps	Properties for defining a `CfnScalableTarget`.
ICfnScalingPolicyProps	Properties for defining a `CfnScalingPolicy`.
ICronOptions	Options to configure a cron expression.
IEnableScalingProps	Properties for enabling Application Auto Scaling.
IScalableTarget
IScalableTargetProps	Properties for a scalable target.
IScalingInterval	A range of metric values in which to apply a certain scaling operation.
IScalingSchedule	A scheduled scaling action.
IStepScalingActionProps	Properties for a scaling policy.
IStepScalingPolicyProps
ITargetTrackingScalingPolicyProps	Properties for a concrete TargetTrackingPolicy.