# AWS Auto Scaling Construct Library
<!--BEGIN STABILITY BANNER-->---
---
<!--END STABILITY BANNER-->
**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:
* **In response to a metric** (also known as step scaling); for example, you
might want to scale out if the CPU usage across your cluster starts to rise,
and scale in when it drops again.
* **By trying to keep a certain metric around a given value** (also known as
target tracking scaling); you might want to automatically scale out an in to
keep your CPU usage around 50%.
* **On a schedule**; you might want to organize your scaling around traffic
flows you expect, by scaling out in the morning and scaling in in the
evening.
The general pattern of autoscaling will look like this:
```python
# resource: SomeScalableResource
capacity = resource.auto_scale_capacity(
min_capacity=5,
max_capacity=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:
```plaintext
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:
```python
# capacity: ScalableAttribute
# cpu_utilization: cloudwatch.Metric
capacity.scale_on_metric("ScaleToCPU",
metric=cpu_utilization,
scaling_steps=[appscaling.ScalingInterval(upper=10, change=-1), appscaling.ScalingInterval(lower=50, change=+1), appscaling.ScalingInterval(lower=70, change=+3)
],
# Change this to AdjustmentType.PercentChangeInCapacity to interpret the
# 'change' numbers before as percentages instead of capacity counts.
adjustment_type=appscaling.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:
```python
# capacity: ScalableAttribute
# cpu_utilization: cloudwatch.Metric
capacity.scale_on_metric("ScaleToCPUWithMultipleDatapoints",
metric=cpu_utilization,
scaling_steps=[appscaling.ScalingInterval(upper=10, change=-1), appscaling.ScalingInterval(lower=50, change=+1), appscaling.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
evaluation_periods=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
datapoints_to_alarm=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:
```python
import aws_cdk.aws_dynamodb as dynamodb
# table: dynamodb.Table
read_capacity = table.auto_scale_read_capacity(
min_capacity=10,
max_capacity=1000
)
read_capacity.scale_on_utilization(
target_utilization_percent=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:
* Scale in and out on a schedule by setting the `minCapacity` high or
the `maxCapacity` low.
* Still allow the regular scaling actions to do their job, but restrict
the range they can scale over (by setting both `minCapacity` and
`maxCapacity` but changing their range over time).
The following schedule expressions can be used:
* `at(yyyy-mm-ddThh:mm:ss)` -- scale at a particular moment in time
* `rate(value unit)` -- scale every minute/hour/day
* `cron(mm hh dd mm dow)` -- scale on arbitrary schedules
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:
```python
# resource: SomeScalableResource
capacity = resource.auto_scale_capacity(
min_capacity=1,
max_capacity=50
)
capacity.scale_on_schedule("PrescaleInTheMorning",
schedule=appscaling.Schedule.cron(hour="8", minute="0"),
min_capacity=20
)
capacity.scale_on_schedule("AllowDownscalingAtNight",
schedule=appscaling.Schedule.cron(hour="20", minute="0"),
min_capacity=1
)
```
## Examples
### Lambda Provisioned Concurrency Auto Scaling
```python
import aws_cdk.aws_lambda as lambda_
# code: lambda.Code
handler = lambda_.Function(self, "MyFunction",
runtime=lambda_.Runtime.PYTHON_3_7,
handler="index.handler",
code=code,
reserved_concurrent_executions=2
)
fn_ver = handler.current_version
target = appscaling.ScalableTarget(self, "ScalableTarget",
service_namespace=appscaling.ServiceNamespace.LAMBDA,
max_capacity=100,
min_capacity=10,
resource_id=f"function:{handler.functionName}:{fnVer.version}",
scalable_dimension="lambda:function:ProvisionedConcurrency"
)
target.scale_to_track_metric("PceTracking",
target_value=0.9,
predefined_metric=appscaling.PredefinedMetric.LAMBDA_PROVISIONED_CONCURRENCY_UTILIZATION
)
```
### ElastiCache Redis shards scaling with target value
```python
shards_scalable_target = appscaling.ScalableTarget(self, "ElastiCacheRedisShardsScalableTarget",
service_namespace=appscaling.ServiceNamespace.ELASTICACHE,
scalable_dimension="elasticache:replication-group:NodeGroups",
min_capacity=2,
max_capacity=10,
resource_id="replication-group/main-cluster"
)
shards_scalable_target.scale_to_track_metric("ElastiCacheRedisShardsCPUUtilization",
target_value=20,
predefined_metric=appscaling.PredefinedMetric.ELASTICACHE_PRIMARY_ENGINE_CPU_UTILIZATION
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-applicationautoscaling",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/95/e4/160a4b5325dbd05763dde913965230b08d558ea9527a3fcee340b8113018/aws-cdk.aws-applicationautoscaling-1.203.0.tar.gz",
"platform": null,
"description": "# AWS Auto Scaling Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n\n\n---\n<!--END STABILITY BANNER-->\n\n**Application AutoScaling** is used to configure autoscaling for all\nservices other than scaling EC2 instances. For example, you will use this to\nscale ECS tasks, DynamoDB capacity, Spot Fleet sizes, Comprehend document classification endpoints, Lambda function provisioned concurrency and more.\n\nAs a CDK user, you will probably not have to interact with this library\ndirectly; instead, it will be used by other construct libraries to\noffer AutoScaling features for their own constructs.\n\nThis document will describe the general autoscaling features and concepts;\nyour particular service may offer only a subset of these.\n\n## AutoScaling basics\n\nResources can offer one or more **attributes** to autoscale, typically\nrepresenting some capacity dimension of the underlying service. For example,\na DynamoDB Table offers autoscaling of the read and write capacity of the\ntable proper and its Global Secondary Indexes, an ECS Service offers\nautoscaling of its task count, an RDS Aurora cluster offers scaling of its\nreplica count, and so on.\n\nWhen you enable autoscaling for an attribute, you specify a minimum and a\nmaximum value for the capacity. AutoScaling policies that respond to metrics\nwill never go higher or lower than the indicated capacity (but scheduled\nscaling actions might, see below).\n\nThere are three ways to scale your capacity:\n\n* **In response to a metric** (also known as step scaling); for example, you\n might want to scale out if the CPU usage across your cluster starts to rise,\n and scale in when it drops again.\n* **By trying to keep a certain metric around a given value** (also known as\n target tracking scaling); you might want to automatically scale out an in to\n keep your CPU usage around 50%.\n* **On a schedule**; you might want to organize your scaling around traffic\n flows you expect, by scaling out in the morning and scaling in in the\n evening.\n\nThe general pattern of autoscaling will look like this:\n\n```python\n# resource: SomeScalableResource\n\n\ncapacity = resource.auto_scale_capacity(\n min_capacity=5,\n max_capacity=100\n)\n```\n\n## Step Scaling\n\nThis type of scaling scales in and out in deterministic steps that you\nconfigure, in response to metric values. For example, your scaling strategy\nto scale in response to CPU usage might look like this:\n\n```plaintext\n Scaling -1 (no change) +1 +3\n \u2502 \u2502 \u2502 \u2502 \u2502\n \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n \u2502 \u2502 \u2502 \u2502 \u2502\nCPU usage 0% 10% 50% 70% 100%\n```\n\n(Note that this is not necessarily a recommended scaling strategy, but it's\na possible one. You will have to determine what thresholds are right for you).\n\nYou would configure it like this:\n\n```python\n# capacity: ScalableAttribute\n# cpu_utilization: cloudwatch.Metric\n\n\ncapacity.scale_on_metric(\"ScaleToCPU\",\n metric=cpu_utilization,\n scaling_steps=[appscaling.ScalingInterval(upper=10, change=-1), appscaling.ScalingInterval(lower=50, change=+1), appscaling.ScalingInterval(lower=70, change=+3)\n ],\n\n # Change this to AdjustmentType.PercentChangeInCapacity to interpret the\n # 'change' numbers before as percentages instead of capacity counts.\n adjustment_type=appscaling.AdjustmentType.CHANGE_IN_CAPACITY\n)\n```\n\nThe AutoScaling construct library will create the required CloudWatch alarms and\nAutoScaling policies for you.\n\n### Scaling based on multiple datapoints\n\nThe Step Scaling configuration above will initiate a scaling event when a single\ndatapoint of the scaling metric is breaching a scaling step breakpoint. In cases\nwhere you might want to initiate scaling actions on a larger number of datapoints\n(ie in order to smooth out randomness in the metric data), you can use the\noptional `evaluationPeriods` and `datapointsToAlarm` properties:\n\n```python\n# capacity: ScalableAttribute\n# cpu_utilization: cloudwatch.Metric\n\n\ncapacity.scale_on_metric(\"ScaleToCPUWithMultipleDatapoints\",\n metric=cpu_utilization,\n scaling_steps=[appscaling.ScalingInterval(upper=10, change=-1), appscaling.ScalingInterval(lower=50, change=+1), appscaling.ScalingInterval(lower=70, change=+3)\n ],\n\n # if the cpuUtilization metric has a period of 1 minute, then data points\n # in the last 10 minutes will be evaluated\n evaluation_periods=10,\n\n # Only trigger a scaling action when 6 datapoints out of the last 10 are\n # breaching. If this is left unspecified, then ALL datapoints in the\n # evaluation period must be breaching to trigger a scaling action\n datapoints_to_alarm=6\n)\n```\n\n## Target Tracking Scaling\n\nThis type of scaling scales in and out in order to keep a metric (typically\nrepresenting utilization) around a value you prefer. This type of scaling is\ntypically heavily service-dependent in what metric you can use, and so\ndifferent services will have different methods here to set up target tracking\nscaling.\n\nThe following example configures the read capacity of a DynamoDB table\nto be around 60% utilization:\n\n```python\nimport aws_cdk.aws_dynamodb as dynamodb\n\n# table: dynamodb.Table\n\n\nread_capacity = table.auto_scale_read_capacity(\n min_capacity=10,\n max_capacity=1000\n)\nread_capacity.scale_on_utilization(\n target_utilization_percent=60\n)\n```\n\n## Scheduled Scaling\n\nThis type of scaling is used to change capacities based on time. It works\nby changing the `minCapacity` and `maxCapacity` of the attribute, and so\ncan be used for two purposes:\n\n* Scale in and out on a schedule by setting the `minCapacity` high or\n the `maxCapacity` low.\n* Still allow the regular scaling actions to do their job, but restrict\n the range they can scale over (by setting both `minCapacity` and\n `maxCapacity` but changing their range over time).\n\nThe following schedule expressions can be used:\n\n* `at(yyyy-mm-ddThh:mm:ss)` -- scale at a particular moment in time\n* `rate(value unit)` -- scale every minute/hour/day\n* `cron(mm hh dd mm dow)` -- scale on arbitrary schedules\n\nOf these, the cron expression is the most useful but also the most\ncomplicated. A schedule is expressed as a cron expression. The `Schedule` class has a `cron` method to help build cron expressions.\n\nThe following example scales the fleet out in the morning, and lets natural\nscaling take over at night:\n\n```python\n# resource: SomeScalableResource\n\n\ncapacity = resource.auto_scale_capacity(\n min_capacity=1,\n max_capacity=50\n)\n\ncapacity.scale_on_schedule(\"PrescaleInTheMorning\",\n schedule=appscaling.Schedule.cron(hour=\"8\", minute=\"0\"),\n min_capacity=20\n)\n\ncapacity.scale_on_schedule(\"AllowDownscalingAtNight\",\n schedule=appscaling.Schedule.cron(hour=\"20\", minute=\"0\"),\n min_capacity=1\n)\n```\n\n## Examples\n\n### Lambda Provisioned Concurrency Auto Scaling\n\n```python\nimport aws_cdk.aws_lambda as lambda_\n\n# code: lambda.Code\n\n\nhandler = lambda_.Function(self, \"MyFunction\",\n runtime=lambda_.Runtime.PYTHON_3_7,\n handler=\"index.handler\",\n code=code,\n\n reserved_concurrent_executions=2\n)\n\nfn_ver = handler.current_version\n\ntarget = appscaling.ScalableTarget(self, \"ScalableTarget\",\n service_namespace=appscaling.ServiceNamespace.LAMBDA,\n max_capacity=100,\n min_capacity=10,\n resource_id=f\"function:{handler.functionName}:{fnVer.version}\",\n scalable_dimension=\"lambda:function:ProvisionedConcurrency\"\n)\n\ntarget.scale_to_track_metric(\"PceTracking\",\n target_value=0.9,\n predefined_metric=appscaling.PredefinedMetric.LAMBDA_PROVISIONED_CONCURRENCY_UTILIZATION\n)\n```\n\n### ElastiCache Redis shards scaling with target value\n\n```python\nshards_scalable_target = appscaling.ScalableTarget(self, \"ElastiCacheRedisShardsScalableTarget\",\n service_namespace=appscaling.ServiceNamespace.ELASTICACHE,\n scalable_dimension=\"elasticache:replication-group:NodeGroups\",\n min_capacity=2,\n max_capacity=10,\n resource_id=\"replication-group/main-cluster\"\n)\n\nshards_scalable_target.scale_to_track_metric(\"ElastiCacheRedisShardsCPUUtilization\",\n target_value=20,\n predefined_metric=appscaling.PredefinedMetric.ELASTICACHE_PRIMARY_ENGINE_CPU_UTILIZATION\n)\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::ApplicationAutoScaling",
"version": "1.203.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a68d206c2522c51f9f61e8a94cdfcfd77164a04a1132e2c592dfde9ddcda34da",
"md5": "f38e57f6531ffa1ad85b22f09a81675f",
"sha256": "8b047ae5ac7af347c0757714921d17a75e8ef071f7eaf776c312a596225be0e2"
},
"downloads": -1,
"filename": "aws_cdk.aws_applicationautoscaling-1.203.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f38e57f6531ffa1ad85b22f09a81675f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 212644,
"upload_time": "2023-05-31T22:52:39",
"upload_time_iso_8601": "2023-05-31T22:52:39.583912Z",
"url": "https://files.pythonhosted.org/packages/a6/8d/206c2522c51f9f61e8a94cdfcfd77164a04a1132e2c592dfde9ddcda34da/aws_cdk.aws_applicationautoscaling-1.203.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "95e4160a4b5325dbd05763dde913965230b08d558ea9527a3fcee340b8113018",
"md5": "c7e1cb9924079d73cffa2b09972eabb4",
"sha256": "2cc9a02ab66e4582018898f1f8198034eac38fe83dae1b09e8f06013281f296d"
},
"downloads": -1,
"filename": "aws-cdk.aws-applicationautoscaling-1.203.0.tar.gz",
"has_sig": false,
"md5_digest": "c7e1cb9924079d73cffa2b09972eabb4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 212468,
"upload_time": "2023-05-31T23:00:37",
"upload_time_iso_8601": "2023-05-31T23:00:37.793294Z",
"url": "https://files.pythonhosted.org/packages/95/e4/160a4b5325dbd05763dde913965230b08d558ea9527a3fcee340b8113018/aws-cdk.aws-applicationautoscaling-1.203.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 23:00:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-applicationautoscaling"
}
JSON
