Show / Hide Table of Contents

Namespace Amazon.CDK.AWS.AutoScaling

Amazon EC2 Auto Scaling Construct Library

--- cfn-resources: Stable cdk-constructs: Stable

This module is part of the AWS Cloud Development Kit project.

Auto Scaling Group

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:

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
using Amazon.CDK.AWS.AutoScaling;
using Amazon.CDK.AWS.EC2;

new AutoScalingGroup(this, "ASG", new AutoScalingGroupProps {
    Vpc = vpc,
    InstanceType = InstanceType.Of(InstanceClass.BURSTABLE2, InstanceSize.MICRO),
    MachineImage = new AmazonLinuxImage()
});

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.

// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var mySecurityGroup = new ec2.SecurityGroup(this, "SecurityGroup", new Struct { ... });
new autoscaling.AutoScalingGroup(this, "ASG", new Struct {
    Vpc = vpc,
    InstanceType = ec2.InstanceType.Of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
    MachineImage = new ec2.AmazonLinuxImage(),
    SecurityGroup = mySecurityGroup
});

Machine Images (AMIs)

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:

// Example automatically generated. See https://github.com/aws/jsii/issues/826
// Pick a Windows edition to use
WindowsImage windows = new WindowsImage(WindowsVersion.WINDOWS_SERVER_2019_ENGLISH_FULL_BASE);

// Pick the right Amazon Linux edition. All arguments shown are optional
// and will default to these values when omitted.
AmazonLinuxImage amznLinux = new AmazonLinuxImage(new AmazonLinuxImageProps {
    Generation = AmazonLinuxGeneration.AMAZON_LINUX,
    Edition = AmazonLinuxEdition.STANDARD,
    Virtualization = AmazonLinuxVirt.HVM,
    Storage = AmazonLinuxStorage.GENERAL_PURPOSE
});

// For other custom (Linux) images, instantiate a `GenericLinuxImage` with
// a map giving the AMI to in for each region:

GenericLinuxImage linux = new GenericLinuxImage(new Dictionary<string, string> {
    { "us-east-1", "ami-97785bed" },
    { "eu-west-1", "ami-12345678" }
});
NOTE: The Amazon Linux images selected will be cached in your <code>cdk.json</code>, so that your
AutoScalingGroups don&apos;t automatically change out from under you when you&apos;re making unrelated
changes. To update to the latest version of Amazon Linux, remove the cache entry from the <code>context</code>
section of your <code>cdk.json</code>.

We will add command-line options to make this step easier in the future.

AutoScaling Instance Counts

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:

    // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
    var autoScalingGroup = new autoscaling.AutoScalingGroup(this, "ASG", new Struct {
        MinCapacity = 5,
        MaxCapacity = 100
    });
    
    // Step scaling
    autoScalingGroup.ScaleOnMetric(...);
    
    // Target tracking scaling
    autoScalingGroup.ScaleOnCpuUtilization(...);
    autoScalingGroup.ScaleOnIncomingBytes(...);
    autoScalingGroup.ScaleOnOutgoingBytes(...);
    autoScalingGroup.ScaleOnRequestCount(...);
    autoScalingGroup.ScaleToTrackMetric(...);
    
    // Scheduled scaling
    autoScalingGroup.ScaleOnSchedule(...);

    Step Scaling

    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:

    // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
    var workerUtilizationMetric = new cloudwatch.Metric(new Struct {
        Namespace = "MyService",
        MetricName = "WorkerUtilization"
    });
    
    capacity.ScaleOnMetric("ScaleToCPU", new Struct {
        Metric = workerUtilizationMetric,
        ScalingSteps = new [] { new Struct { Upper = 10, Change = -1 }, new Struct { Lower = 50, Change = +1 }, new Struct { 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.

    Target Tracking Scaling

    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:

    // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
    autoScalingGroup.ScaleOnCpuUtilization("KeepSpareCPU", new Struct {
        TargetUtilizationPercent = 50
    });

    To scale on average network traffic in and out of your instances:

    // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
    autoScalingGroup.ScaleOnIncomingBytes("LimitIngressPerInstance", new Struct {
        TargetBytesPerSecond = 10 * 1024 * 1024
    });
    autoScalingGroup.ScaleOnOutcomingBytes("LimitEgressPerInstance", new Struct {
        TargetBytesPerSecond = 10 * 1024 * 1024
    });

    To scale on the average request count per instance (only works for AutoScalingGroups that have been attached to Application Load Balancers):

    // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
    autoScalingGroup.ScaleOnRequestCount("LimitRPS", new Struct {
        TargetRequestsPerSecond = 1000
    });

    Scheduled Scaling

    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:

      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:

      // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
      autoScalingGroup.ScaleOnSchedule("PrescaleInTheMorning", new Struct {
          Schedule = autoscaling.Schedule.Cron(new Struct { Hour = "8", Minute = "0" }),
          MinCapacity = 20
      });
      
      autoScalingGroup.ScaleOnSchedule("AllowDownscalingAtNight", new Struct {
          Schedule = autoscaling.Schedule.Cron(new Struct { Hour = "20", Minute = "0" }),
          MinCapacity = 1
      });

      Configuring Instances using CloudFormation Init

      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:

        Here's an example of using CloudFormation Init to write a file to the instance hosts on startup:

        // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        new autoscaling.AutoScalingGroup(this, "ASG", new Struct {
            // ...
        
            Init = ec2.CloudFormationInit.FromElements(ec2.InitFile.FromString("/etc/my_instance", "This got written during instance startup")),
            Signals = autoscaling.Signals.WaitForAll(new Struct {
                Timeout = Duration.Minutes(10)
            })
        });

        Signals

        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:

          There are two options you can configure:

            Update Policy

            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:

              Allowing Connections

              See the documentation of the @aws-cdk/aws-ec2 package for more information about allowing connections between resources backed by instances.

              Max Instance Lifetime

              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.

              Instance Monitoring

              To disable detailed instance monitoring, specify instanceMonitoring property for the AutoscalingGroup resource as Monitoring.BASIC. Otherwise detailed monitoring will be enabled.

              Monitoring Group Metrics

              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:

              // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
              // Enable monitoring of all group metrics
              // Enable monitoring of all group metrics
              new autoscaling.AutoScalingGroup(stack, "ASG", new Struct {
                  GroupMetrics = new [] { GroupMetrics.All() }
              });
              
              // Enable monitoring for a subset of group metrics
              // Enable monitoring for a subset of group metrics
              new autoscaling.AutoScalingGroup(stack, "ASG", new Struct {
                  GroupMetrics = new [] { new autoscaling.GroupMetrics(GroupMetric.MIN_SIZE, GroupMetric.MAX_SIZE) }
              });

              Future work

                Classes

                AdjustmentTier

                An adjustment.

                AdjustmentType

                How adjustment numbers are interpreted.

                ApplyCloudFormationInitOptions

                Options for applying CloudFormation init to an instance or instance group.

                AutoScalingGroup

                A Fleet represents a managed set of EC2 instances.

                AutoScalingGroupProps

                Properties of a Fleet.

                BaseTargetTrackingProps

                Base interface for target tracking props.

                BasicLifecycleHookProps

                Basic properties for a lifecycle hook.

                BasicScheduledActionProps

                Properties for a scheduled scaling action.

                BasicStepScalingPolicyProps
                BasicTargetTrackingScalingPolicyProps

                Properties for a Target Tracking policy that include the metric but exclude the target.

                BlockDevice

                Block device.

                BlockDeviceVolume

                Describes a block device mapping for an EC2 instance or Auto Scaling group.

                CfnAutoScalingGroup

                A CloudFormation AWS::AutoScaling::AutoScalingGroup.

                CfnAutoScalingGroup.InstancesDistributionProperty
                CfnAutoScalingGroup.LaunchTemplateOverridesProperty
                CfnAutoScalingGroup.LaunchTemplateProperty
                CfnAutoScalingGroup.LaunchTemplateSpecificationProperty
                CfnAutoScalingGroup.LifecycleHookSpecificationProperty
                CfnAutoScalingGroup.MetricsCollectionProperty
                CfnAutoScalingGroup.MixedInstancesPolicyProperty
                CfnAutoScalingGroup.NotificationConfigurationProperty
                CfnAutoScalingGroup.TagPropertyProperty
                CfnAutoScalingGroupProps

                Properties for defining a AWS::AutoScaling::AutoScalingGroup.

                CfnLaunchConfiguration

                A CloudFormation AWS::AutoScaling::LaunchConfiguration.

                CfnLaunchConfiguration.BlockDeviceMappingProperty
                CfnLaunchConfiguration.BlockDeviceProperty
                CfnLaunchConfiguration.MetadataOptionsProperty
                CfnLaunchConfigurationProps

                Properties for defining a AWS::AutoScaling::LaunchConfiguration.

                CfnLifecycleHook

                A CloudFormation AWS::AutoScaling::LifecycleHook.

                CfnLifecycleHookProps

                Properties for defining a AWS::AutoScaling::LifecycleHook.

                CfnScalingPolicy

                A CloudFormation AWS::AutoScaling::ScalingPolicy.

                CfnScalingPolicy.CustomizedMetricSpecificationProperty
                CfnScalingPolicy.MetricDimensionProperty
                CfnScalingPolicy.PredefinedMetricSpecificationProperty
                CfnScalingPolicy.StepAdjustmentProperty
                CfnScalingPolicy.TargetTrackingConfigurationProperty
                CfnScalingPolicyProps

                Properties for defining a AWS::AutoScaling::ScalingPolicy.

                CfnScheduledAction

                A CloudFormation AWS::AutoScaling::ScheduledAction.

                CfnScheduledActionProps

                Properties for defining a AWS::AutoScaling::ScheduledAction.

                CommonAutoScalingGroupProps

                Basic properties of an AutoScalingGroup, except the exact machines to run and where they should run.

                CpuUtilizationScalingProps

                Properties for enabling scaling based on CPU utilization.

                CronOptions

                Options to configure a cron expression.

                DefaultResult
                EbsDeviceOptions

                Block device options for an EBS volume.

                EbsDeviceOptionsBase

                Base block device options for an EBS volume.

                EbsDeviceProps

                Properties of an EBS block device.

                EbsDeviceSnapshotOptions

                Block device options for an EBS volume created from a snapshot.

                EbsDeviceVolumeType

                Supported EBS volume types for blockDevices.

                Ec2HealthCheckOptions

                EC2 Heath check options.

                ElbHealthCheckOptions

                ELB Heath check options.

                GroupMetric

                Group metrics that an Auto Scaling group sends to Amazon CloudWatch.

                GroupMetrics

                A set of group metrics.

                HealthCheck

                Health check settings.

                LifecycleHook

                Define a life cycle hook.

                LifecycleHookProps

                Properties for a Lifecycle hook.

                LifecycleHookTargetConfig

                Properties to add the target to a lifecycle hook.

                LifecycleTransition

                What instance transition to attach the hook to.

                MetricAggregationType

                How the scaling metric is going to be aggregated.

                MetricTargetTrackingProps

                Properties for enabling tracking of an arbitrary metric.

                Monitoring

                The monitoring mode for instances launched in an autoscaling group.

                NetworkUtilizationScalingProps

                Properties for enabling scaling based on network utilization.

                NotificationConfiguration

                AutoScalingGroup fleet change notifications configurations.

                PredefinedMetric

                One of the predefined autoscaling metrics.

                RenderSignalsOptions

                Input for Signals.renderCreationPolicy.

                RequestCountScalingProps

                Properties for enabling scaling based on request/second.

                RollingUpdateConfiguration

                Additional settings when a rolling update is selected.

                RollingUpdateOptions

                Options for customizing the rolling update.

                ScalingEvent

                Fleet scaling events.

                ScalingEvents

                A list of ScalingEvents, you can use one of the predefined lists, such as ScalingEvents.ERRORS or create a custom group by instantiating a NotificationTypes object, e.g: new NotificationTypes(NotificationType.INSTANCE_LAUNCH).

                ScalingInterval

                A range of metric values in which to apply a certain scaling operation.

                ScalingProcess
                Schedule

                Schedule for scheduled scaling actions.

                ScheduledAction

                Define a scheduled scaling action.

                ScheduledActionProps

                Properties for a scheduled action on an AutoScalingGroup.

                Signals

                Configure whether the AutoScalingGroup waits for signals.

                SignalsOptions

                Customization options for Signal handling.

                StepScalingAction

                Define a step scaling action.

                StepScalingActionProps

                Properties for a scaling policy.

                StepScalingPolicy

                Define a acaling strategy which scales depending on absolute values of some metric.

                StepScalingPolicyProps
                TargetTrackingScalingPolicy
                TargetTrackingScalingPolicyProps

                Properties for a concrete TargetTrackingPolicy.

                UpdatePolicy

                How existing instances should be updated.

                UpdateType

                (deprecated) The type of update to perform on instances in this AutoScalingGroup.

                Interfaces

                CfnAutoScalingGroup.IInstancesDistributionProperty
                CfnAutoScalingGroup.ILaunchTemplateOverridesProperty
                CfnAutoScalingGroup.ILaunchTemplateProperty
                CfnAutoScalingGroup.ILaunchTemplateSpecificationProperty
                CfnAutoScalingGroup.ILifecycleHookSpecificationProperty
                CfnAutoScalingGroup.IMetricsCollectionProperty
                CfnAutoScalingGroup.IMixedInstancesPolicyProperty
                CfnAutoScalingGroup.INotificationConfigurationProperty
                CfnAutoScalingGroup.ITagPropertyProperty
                CfnLaunchConfiguration.IBlockDeviceMappingProperty
                CfnLaunchConfiguration.IBlockDeviceProperty
                CfnLaunchConfiguration.IMetadataOptionsProperty
                CfnScalingPolicy.ICustomizedMetricSpecificationProperty
                CfnScalingPolicy.IMetricDimensionProperty
                CfnScalingPolicy.IPredefinedMetricSpecificationProperty
                CfnScalingPolicy.IStepAdjustmentProperty
                CfnScalingPolicy.ITargetTrackingConfigurationProperty
                IAdjustmentTier

                An adjustment.

                IApplyCloudFormationInitOptions

                Options for applying CloudFormation init to an instance or instance group.

                IAutoScalingGroup

                An AutoScalingGroup.

                IAutoScalingGroupProps

                Properties of a Fleet.

                IBaseTargetTrackingProps

                Base interface for target tracking props.

                IBasicLifecycleHookProps

                Basic properties for a lifecycle hook.

                IBasicScheduledActionProps

                Properties for a scheduled scaling action.

                IBasicStepScalingPolicyProps
                IBasicTargetTrackingScalingPolicyProps

                Properties for a Target Tracking policy that include the metric but exclude the target.

                IBlockDevice

                Block device.

                ICfnAutoScalingGroupProps

                Properties for defining a AWS::AutoScaling::AutoScalingGroup.

                ICfnLaunchConfigurationProps

                Properties for defining a AWS::AutoScaling::LaunchConfiguration.

                ICfnLifecycleHookProps

                Properties for defining a AWS::AutoScaling::LifecycleHook.

                ICfnScalingPolicyProps

                Properties for defining a AWS::AutoScaling::ScalingPolicy.

                ICfnScheduledActionProps

                Properties for defining a AWS::AutoScaling::ScheduledAction.

                ICommonAutoScalingGroupProps

                Basic properties of an AutoScalingGroup, except the exact machines to run and where they should run.

                ICpuUtilizationScalingProps

                Properties for enabling scaling based on CPU utilization.

                ICronOptions

                Options to configure a cron expression.

                IEbsDeviceOptions

                Block device options for an EBS volume.

                IEbsDeviceOptionsBase

                Base block device options for an EBS volume.

                IEbsDeviceProps

                Properties of an EBS block device.

                IEbsDeviceSnapshotOptions

                Block device options for an EBS volume created from a snapshot.

                IEc2HealthCheckOptions

                EC2 Heath check options.

                IElbHealthCheckOptions

                ELB Heath check options.

                ILifecycleHook

                A basic lifecycle hook object.

                ILifecycleHookProps

                Properties for a Lifecycle hook.

                ILifecycleHookTarget

                Interface for autoscaling lifecycle hook targets.

                ILifecycleHookTargetConfig

                Properties to add the target to a lifecycle hook.

                IMetricTargetTrackingProps

                Properties for enabling tracking of an arbitrary metric.

                INetworkUtilizationScalingProps

                Properties for enabling scaling based on network utilization.

                INotificationConfiguration

                AutoScalingGroup fleet change notifications configurations.

                IRenderSignalsOptions

                Input for Signals.renderCreationPolicy.

                IRequestCountScalingProps

                Properties for enabling scaling based on request/second.

                IRollingUpdateConfiguration

                Additional settings when a rolling update is selected.

                IRollingUpdateOptions

                Options for customizing the rolling update.

                IScalingInterval

                A range of metric values in which to apply a certain scaling operation.

                IScheduledActionProps

                Properties for a scheduled action on an AutoScalingGroup.

                ISignalsOptions

                Customization options for Signal handling.

                IStepScalingActionProps

                Properties for a scaling policy.

                IStepScalingPolicyProps
                ITargetTrackingScalingPolicyProps

                Properties for a concrete TargetTrackingPolicy.

                Back to top Generated by DocFX