Skip navigation links


AWS Auto Scaling Construct Library

See: Description

Package Description

AWS Auto Scaling Construct Library


cfn-resources: Stable

cdk-constructs: Stable

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:

 // Example automatically generated without compilation. See
 Object capacity = resource.autoScaleCapacity(Map.of(
         "minCapacity", 5,
         "maxCapacity", 100));
 // Enable a type of metric scaling and/or schedule scaling

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:

 // Example automatically generated without compilation. See
 capacity.scaleOnMetric("ScaleToCPU", Map.of(
         "metric", service.metricCpuUtilization(),
         "scalingSteps", asList(Map.of("upper", 10, "change", -1), Map.of("lower", 50, "change", +1), Map.of("lower", 70, "change", +3)),
         // Change this to AdjustmentType.PercentChangeInCapacity to interpret the
         // 'change' numbers before as percentages instead of capacity counts.
         "adjustmentType", autoscaling.AdjustmentType.getCHANGE_IN_CAPACITY()));

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

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:

 // Example automatically generated without compilation. See
 Object readCapacity = table.autoScaleReadCapacity(Map.of(
         "minCapacity", 10,
         "maxCapacity", 1000));
         "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:

 // Example automatically generated without compilation. See
 Object capacity = resource.autoScaleCapacity(Map.of(
         "minCapacity", 1,
         "maxCapacity", 50));
 capacity.scaleOnSchedule("PrescaleInTheMorning", Map.of(
         "schedule", autoscaling.Schedule.cron(Map.of("hour", "8", "minute", "0")),
         "minCapacity", 20));
 capacity.scaleOnSchedule("AllowDownscalingAtNight", Map.of(
         "schedule", autoscaling.Schedule.cron(Map.of("hour", "20", "minute", "0")),
         "minCapacity", 1));


Lambda Provisioned Concurrency Auto Scaling

 // Example automatically generated without compilation. See
 Function handler = new Function(this, "MyFunction", new FunctionProps()
         .code(new InlineCode("\nimport json, time\ndef handler(event, context):\n    time.sleep(1)\n    return {\n        'statusCode': 200,\n        'body': json.dumps('Hello CDK from Lambda!')\n    }"))
 Version fnVer = handler.addVersion("CDKLambdaVersion", undefined, "demo alias", 10);
 LambdaRestApi.Builder.create(this, "API").handler(fnVer).build();
 Object target = ScalableTarget.Builder.create(this, "ScalableTarget")
         .resourceId(String.format("function:%s:%s", handler.getFunctionName(), fnVer.getVersion()))
 target.scaleToTrackMetric("PceTracking", Map.of(
         "targetValue", 0.9,
         "predefinedMetric", applicationautoscaling.PredefinedMetric.getLAMBDA_PROVISIONED_CONCURRENCY_UTILIZATION()));
Skip navigation links