@aws-cdk/aws-autoscaling
Advanced tools
This module is part of the AWS Cloud Development Kit project.
An AutoScalingGroup represents a number of instances on which you run your code. You
pick the size of the fleet, the instance type and the OS image:
declare const vpc: ec2.Vpc;
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
machineImage: new ec2.AmazonLinuxImage() // get the latest Amazon Linux image
});
NOTE: AutoScalingGroup has an property called allowAllOutbound (allowing the instances to contact the
internet) which is set to true by default. Be sure to set this to false if you don't want
your instances to be able to start arbitrary connections. Alternatively, you can specify an existing security
group to attach to the instances that are launched, rather than have the group create a new one.
declare const vpc: ec2.Vpc;
const mySecurityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', { vpc });
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
machineImage: new ec2.AmazonLinuxImage(),
securityGroup: mySecurityGroup,
});
AMIs control the OS that gets launched when you start your EC2 instance. The EC2 library contains constructs to select the AMI you want to use.
Depending on the type of AMI, you select it a different way.
The latest version of Amazon Linux and Microsoft Windows images are selectable by instantiating one of these classes:
NOTE: The Amazon Linux images selected will be cached in your
cdk.json, so that your AutoScalingGroups don't automatically change out from under you when you're making unrelated changes. To update to the latest version of Amazon Linux, remove the cache entry from thecontextsection of yourcdk.json.We will add command-line options to make this step easier in the future.
AutoScalingGroups make it possible to raise and lower the number of instances in the group, in response to (or in advance of) changes in workload.
When you create your AutoScalingGroup, you specify a minCapacity and a
maxCapacity. 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:
declare const vpc: ec2.Vpc;
declare const instanceType: ec2.InstanceType;
declare const machineImage: ec2.IMachineImage;
const autoScalingGroup = new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType,
machineImage,
minCapacity: 5,
maxCapacity: 100
// ...
});
// Then call one of the scaling methods (explained below)
//
// autoScalingGroup.scaleOnMetric(...);
//
// autoScalingGroup.scaleOnCpuUtilization(...);
// autoScalingGroup.scaleOnIncomingBytes(...);
// autoScalingGroup.scaleOnOutgoingBytes(...);
// autoScalingGroup.scaleOnRequestCount(...);
// autoScalingGroup.scaleToTrackMetric(...);
//
// autoScalingGroup.scaleOnSchedule(...);
This type of scaling scales in and out in deterministics steps that you configure, in response to metric values. For example, your scaling strategy to scale in response to a metric that represents your average worker pool usage might look like this:
Scaling -1 (no change) +1 +3
│ │ │ │ │
├────────┼───────────────────────┼────────┼────────┤
│ │ │ │ │
Worker use 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).
Note that in order to set up this scaling strategy, you will have to emit a metric representing your worker utilization from your instances. After that, you would configure the scaling something like this:
declare const autoScalingGroup: autoscaling.AutoScalingGroup;
const workerUtilizationMetric = new cloudwatch.Metric({
namespace: 'MyService',
metricName: 'WorkerUtilization'
});
autoScalingGroup.scaleOnMetric('ScaleToCPU', {
metric: workerUtilizationMetric,
scalingSteps: [
{ upper: 10, change: -1 },
{ lower: 50, change: +1 },
{ lower: 70, change: +3 },
],
// Change this to AdjustmentType.PERCENT_CHANGE_IN_CAPACITY to interpret the
// 'change' numbers before as percentages instead of capacity counts.
adjustmentType: autoscaling.AdjustmentType.CHANGE_IN_CAPACITY,
});
The AutoScaling construct library will create the required CloudWatch alarms and AutoScaling policies for you.
This type of scaling scales in and out in order to keep a metric around a value you prefer. There are four types of predefined metrics you can track, or you can choose to track a custom metric. If you do choose to track a custom metric, be aware that the metric has to represent instance utilization in some way (AutoScaling will scale out if the metric is higher than the target, and scale in if the metric is lower than the target).
If you configure multiple target tracking policies, AutoScaling will use the one that yields the highest capacity.
The following example scales to keep the CPU usage of your instances around 50% utilization:
declare const autoScalingGroup: autoscaling.AutoScalingGroup;
autoScalingGroup.scaleOnCpuUtilization('KeepSpareCPU', {
targetUtilizationPercent: 50
});
To scale on average network traffic in and out of your instances:
declare const autoScalingGroup: autoscaling.AutoScalingGroup;
autoScalingGroup.scaleOnIncomingBytes('LimitIngressPerInstance', {
targetBytesPerSecond: 10 * 1024 * 1024 // 10 MB/s
});
autoScalingGroup.scaleOnOutgoingBytes('LimitEgressPerInstance', {
targetBytesPerSecond: 10 * 1024 * 1024 // 10 MB/s
});
To scale on the average request count per instance (only works for AutoScalingGroups that have been attached to Application Load Balancers):
declare const autoScalingGroup: autoscaling.AutoScalingGroup;
autoScalingGroup.scaleOnRequestCount('LimitRPS', {
targetRequestsPerSecond: 1000
});
This type of scaling is used to change capacities based on time. It works by
changing minCapacity, maxCapacity and desiredCapacity of the
AutoScalingGroup, and so can be used for two purposes:
minCapacity high or
the maxCapacity low.minCapacity and
maxCapacity but changing their range over time).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, going back to natural scaling (all the way down to 1 instance if necessary) at night:
declare const autoScalingGroup: autoscaling.AutoScalingGroup;
autoScalingGroup.scaleOnSchedule('PrescaleInTheMorning', {
schedule: autoscaling.Schedule.cron({ hour: '8', minute: '0' }),
minCapacity: 20,
});
autoScalingGroup.scaleOnSchedule('AllowDownscalingAtNight', {
schedule: autoscaling.Schedule.cron({ hour: '20', minute: '0' }),
minCapacity: 1
});
It is possible to use the CloudFormation Init mechanism to configure the
instances in the AutoScalingGroup. You can write files to it, run commands,
start services, etc. See the documentation of
AWS::CloudFormation::Init
and the documentation of CDK's aws-ec2 library for more information.
When you specify a CloudFormation Init configuration for an AutoScalingGroup:
signals to configure how long CloudFormation
should wait for the instances to successfully configure themselves.updatePolicy to configure how instances
should be updated when the AutoScalingGroup is updated (for example,
when the AMI is updated). If you don't specify an update policy, a rolling
update is chosen by default.Here's an example of using CloudFormation Init to write a file to the instance hosts on startup:
declare const vpc: ec2.Vpc;
declare const instanceType: ec2.InstanceType;
declare const machineImage: ec2.IMachineImage;
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType,
machineImage,
// ...
init: ec2.CloudFormationInit.fromElements(
ec2.InitFile.fromString('/etc/my_instance', 'This got written during instance startup'),
),
signals: autoscaling.Signals.waitForAll({
timeout: Duration.minutes(10),
}),
});
In normal operation, CloudFormation will send a Create or Update command to an AutoScalingGroup and proceed with the rest of the deployment without waiting for the instances in the AutoScalingGroup.
Configure signals to tell CloudFormation to wait for a specific number of
instances in the AutoScalingGroup to have been started (or failed to start)
before moving on. An instance is supposed to execute the
cfn-signal
program as part of its startup to indicate whether it was started
successfully or not.
If you use CloudFormation Init support (described in the previous section),
the appropriate call to cfn-signal is automatically added to the
AutoScalingGroup's UserData. If you don't use the signals directly, you are
responsible for adding such a call yourself.
The following type of Signals are available:
Signals.waitForAll([options]): wait for all of desiredCapacity amount of instances
to have started (recommended).Signals.waitForMinCapacity([options]): wait for a minCapacity amount of instances
to have started (use this if waiting for all instances takes too long and you are happy
with a minimum count of healthy hosts).Signals.waitForCount(count, [options]): wait for a specific amount of instances to have
started.There are two options you can configure:
timeout: maximum time a host startup is allowed to take. If a host does not report
success within this time, it is considered a failure. Default is 5 minutes.minSuccessPercentage: percentage of hosts that needs to be healthy in order for the
update to succeed. If you set this value lower than 100, some percentage of hosts may
report failure, while still considering the deployment a success. Default is 100%.The update policy describes what should happen to running instances when the definition of the AutoScalingGroup is changed. For example, if you add a command to the UserData of an AutoScalingGroup, do the existing instances get replaced with new instances that have executed the new UserData? Or do the "old" instances just keep on running?
It is recommended to always use an update policy, otherwise the current state of your instances also depends the previous state of your instances, rather than just on your source code. This degrades the reproducibility of your deployments.
The following update policies are available:
UpdatePolicy.none(): leave existing instances alone (not recommended).UpdatePolicy.rollingUpdate([options]): progressively replace the existing
instances with new instances, in small batches. At any point in time,
roughly the same amount of total instances will be running. If the deployment
needs to be rolled back, the fresh instances will be replaced with the "old"
configuration again.UpdatePolicy.replacingUpdate([options]): build a completely fresh copy
of the new AutoScalingGroup next to the old one. Once the AutoScalingGroup
has been successfully created (and the instances started, if signals is
configured on the AutoScalingGroup), the old AutoScalingGroup is deleted.
If the deployment needs to be rolled back, the new AutoScalingGroup is
deleted and the old one is left unchanged.See the documentation of the @aws-cdk/aws-ec2 package for more information
about allowing connections between resources backed by instances.
To enable the max instance lifetime support, specify maxInstanceLifetime property
for the AutoscalingGroup resource. The value must be between 7 and 365 days(inclusive).
To clear a previously set value, leave this property undefined.
To disable detailed instance monitoring, specify instanceMonitoring property
for the AutoscalingGroup resource as Monitoring.BASIC. Otherwise detailed monitoring
will be enabled.
Group metrics are used to monitor group level properties; they describe the group rather than any of its instances (e.g GroupMaxSize, the group maximum size). To enable group metrics monitoring, use the groupMetrics property.
All group metrics are reported in a granularity of 1 minute at no additional charge.
See EC2 docs for a list of all available group metrics.
To enable group metrics monitoring using the groupMetrics property:
declare const vpc: ec2.Vpc;
declare const instanceType: ec2.InstanceType;
declare const machineImage: ec2.IMachineImage;
// Enable monitoring of all group metrics
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType,
machineImage,
// ...
groupMetrics: [autoscaling.GroupMetrics.all()],
});
// Enable monitoring for a subset of group metrics
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType,
machineImage,
// ...
groupMetrics: [new autoscaling.GroupMetrics(autoscaling.GroupMetric.MIN_SIZE, autoscaling.GroupMetric.MAX_SIZE)],
});
Auto Scaling uses termination policies
to determine which instances it terminates first during scale-in events. You
can specify one or more termination policies with the terminationPolicies
property:
declare const vpc: ec2.Vpc;
declare const instanceType: ec2.InstanceType;
declare const machineImage: ec2.IMachineImage;
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType,
machineImage,
// ...
terminationPolicies: [
autoscaling.TerminationPolicy.OLDEST_INSTANCE,
autoscaling.TerminationPolicy.DEFAULT,
],
});
By default, Auto Scaling can terminate an instance at any time after launch when scaling in an Auto Scaling Group, subject to the group's termination policy.
However, you may wish to protect newly-launched instances from being scaled in
if they are going to run critical applications that should not be prematurely
terminated. EC2 Capacity Providers for Amazon ECS requires this attribute be
set to true.
declare const vpc: ec2.Vpc;
declare const instanceType: ec2.InstanceType;
declare const machineImage: ec2.IMachineImage;
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType,
machineImage,
// ...
newInstancesProtectedFromScaleIn: true,
});
You can configure EC2 Instance Metadata Service options to either allow both IMDSv1 and IMDSv2 or enforce IMDSv2 when interacting with the IMDS.
To do this for a single AutoScalingGroup, you can use set the requireImdsv2 property.
The example below demonstrates IMDSv2 being required on a single AutoScalingGroup:
declare const vpc: ec2.Vpc;
declare const instanceType: ec2.InstanceType;
declare const machineImage: ec2.IMachineImage;
new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType,
machineImage,
// ...
requireImdsv2: true,
});
You can also use AutoScalingGroupRequireImdsv2Aspect to apply the operation to multiple AutoScalingGroups.
The example below demonstrates the AutoScalingGroupRequireImdsv2Aspect being used to require IMDSv2 for all AutoScalingGroups in a stack:
const aspect = new autoscaling.AutoScalingGroupRequireImdsv2Aspect();
Aspects.of(this).add(aspect);
Auto Scaling offers a warm pool which gives an ability to decrease latency for applications that have exceptionally long boot times. You can create a warm pool with default parameters as below:
declare const autoScalingGroup: autoscaling.AutoScalingGroup;
autoScalingGroup.addWarmPool();
You can also customize a warm pool by configuring parameters:
declare const autoScalingGroup: autoscaling.AutoScalingGroup;
autoScalingGroup.addWarmPool({
minSize: 1,
reuseOnScaleIn: true,
});
1.150.0 (2022-03-26)
StepFunctionsIntegration does not create required role and responses (#19486) (d59bee9).gitignore (#19482) (5ce0983)Invoke with Qualifier authorization strategy (#19318) (d06b27f), closes #19273FAQs
The CDK Construct Library for AWS::AutoScaling
The npm package @aws-cdk/aws-autoscaling receives a total of 43,216 weekly downloads. As such, @aws-cdk/aws-autoscaling popularity was classified as popular.
We found that @aws-cdk/aws-autoscaling demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.