AWS::AutoScaling::ScalingPolicy - AWS CloudFormation

AWS::AutoScaling::ScalingPolicy

Specifies an Amazon EC2 Auto Scaling scaling policy so that the Auto Scaling group can change the number of instances available for your application in response to changing demand.

To update an existing scaling policy, use the existing policy name and set the property to change. If you leave a property unspecified when updating a scaling policy, the corresponding value remains unchanged.

If you create either a step scaling policy or a simple scaling policy, you must also create a CloudWatch alarm that monitors a CloudWatch metric for your Auto Scaling group. Note that you can associate a CloudWatch alarm with only one scaling policy.

For more information about using scaling policies to scale your Auto Scaling group automatically, see Dynamic Scaling in the Amazon EC2 Auto Scaling User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::AutoScaling::ScalingPolicy", "Properties" : { "AdjustmentType" : String, "AutoScalingGroupName" : String, "Cooldown" : String, "EstimatedInstanceWarmup" : Integer, "MetricAggregationType" : String, "MinAdjustmentMagnitude" : Integer, "PolicyType" : String, "ScalingAdjustment" : Integer, "StepAdjustments" : [ StepAdjustment, ... ], "TargetTrackingConfiguration" : TargetTrackingConfiguration } }

Properties

AdjustmentType

Specifies whether the ScalingAdjustment property is an absolute number or a percentage of the current capacity. The valid values are ChangeInCapacity, ExactCapacity, and PercentChangeInCapacity.

Valid only if the policy type is StepScaling or SimpleScaling. For more information, see Scaling Adjustment Types in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: String

Minimum: 1

Maximum: 255

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

AutoScalingGroupName

The name or Amazon Resource Name (ARN) of the Auto Scaling group that you want to attach the policy to.

Required: Yes

Type: String

Minimum: 1

Maximum: 255

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

Cooldown

The amount of time, in seconds, after a scaling activity completes before any further dynamic scaling activities can start. If this property is not specified, the default cooldown period for the group applies.

Valid only if the policy type is SimpleScaling. For more information, see Scaling Cooldowns in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: String

Update requires: No interruption

EstimatedInstanceWarmup

The estimated time, in seconds, until a newly launched instance can contribute to the CloudWatch metrics. The default is to use the value specified for the default cooldown period for the group.

Valid only if the policy type is StepScaling or TargetTrackingScaling.

Required: No

Type: Integer

Update requires: No interruption

MetricAggregationType

The aggregation type for the CloudWatch metrics. The valid values are Minimum, Maximum, and Average. By default, AWS CloudFormation specifies Average.

Valid only if the policy type is StepScaling.

Required: No

Type: String

Minimum: 1

Maximum: 32

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

MinAdjustmentMagnitude

The minimum value to scale by when scaling by percentages. For example, suppose that you create a step scaling policy to scale out an Auto Scaling group by 25 percent and you specify a MinAdjustmentMagnitude of 2. If the group has 4 instances and the scaling policy is performed, 25 percent of 4 is 1. However, because you specified a MinAdjustmentMagnitude of 2, Amazon EC2 Auto Scaling scales out the group by 2 instances.

Valid only if the policy type is StepScaling or SimpleScaling and the adjustment type is PercentChangeInCapacity. For more information, see Scaling Adjustment Types in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: Integer

Update requires: No interruption

PolicyType

The policy type. The default value is SimpleScaling.

Allowed Values: SimpleScaling, StepScaling, or TargetTrackingScaling

Required: No

Type: String

Update requires: No interruption

ScalingAdjustment

The amount by which a simple scaling policy scales the Auto Scaling group in response to an alarm breach. The adjustment is based on the value that you specified in the AdjustmentType property (either an absolute number or a percentage). A positive value adds to the current capacity and a negative value subtracts from the current capacity. For exact capacity, you must specify a positive value.

If you specify SimpleScaling for the policy type, you must specify this property. (Not used with any other policy type.)

Required: Conditional

Type: Integer

Update requires: No interruption

StepAdjustments

A set of adjustments that enable you to scale based on the size of the alarm breach.

If you specify StepScaling for the policy type, you must specify this property. (Not used with any other policy type.)

Required: Conditional

Type: List of StepAdjustment

Update requires: No interruption

TargetTrackingConfiguration

Configures a target tracking scaling policy.

If you specify TargetTrackingScaling for the policy type, you must specify this property. (Not used with any other policy type.)

Required: Conditional

Type: TargetTrackingConfiguration

Update requires: No interruption

Return Values

Ref

When you specify an AWS::AutoScaling::ScalingPolicy type as an argument to the Ref function, AWS CloudFormation returns the policy Amazon Resource Name (ARN). For example: arn:aws:autoscaling:us-east-2:123456789012:scalingPolicy:ab12c4d5-a1b2-a1b2-a1b2-ab12c4d56789:autoScalingGroupName/myStack-AutoScalingGroup-AB12C4D5E6:policyName/myStack-myScalingPolicy-AB12C4D5E6.

For more information about using the Ref function, see Ref.

Examples

The following examples specify scaling policies for an Auto Scaling group.

Target Tracking Scaling Policy

The following example creates an Auto Scaling group with two target tracking scaling policies based on the ASGAverageCPUUtilization and ALBRequestCountPerTarget metrics. The properties of each of these policies include a TargetValue property that references a parameter value from the same template.

JSON

{ "AWSTemplateFormatVersion":"2010-09-09", "Parameters":{ "AMI":{ "Type":"String" }, "Subnets":{ "Type":"CommaDelimitedList" }, "VPC":{ "Type":"String" }, "CPUPolicyTargetValue":{ "Type":"String" }, "ALBRequestCountTargetValue":{ "Type":"String" } }, "Resources":{ "myLoadBalancer":{ "Type":"AWS::ElasticLoadBalancingV2::LoadBalancer", "Properties":{ "Subnets":{ "Ref":"Subnets" } } }, "myLoadBalancerListener":{ "Type":"AWS::ElasticLoadBalancingV2::Listener", "Properties":{ "DefaultActions":[ { "TargetGroupArn":{ "Ref":"myTargetGroup" }, "Type":"forward" } ], "LoadBalancerArn":{ "Ref":"myLoadBalancer" }, "Port":80, "Protocol":"HTTP" } }, "myTargetGroup":{ "Type":"AWS::ElasticLoadBalancingV2::TargetGroup", "Properties":{ "Name":"myTargetGroup", "Port":80, "Protocol":"HTTP", "VpcId":{ "Ref":"VPC" } } }, "myLaunchConfig":{ "Type":"AWS::AutoScaling::LaunchConfiguration", "Properties":{ "ImageId":{ "Ref":"AMI" }, "InstanceType":"t2.large" } }, "myASG":{ "Type":"AWS::AutoScaling::AutoScalingGroup", "Properties":{ "MaxSize":"2", "MinSize":"1", "VPCZoneIdentifier":{ "Ref":"Subnets" }, "LaunchConfigurationName":{ "Ref":"myLaunchConfig" }, "TargetGroupARNs":[ { "Ref":"myTargetGroup" } ] } }, "myCPUPolicy":{ "Type":"AWS::AutoScaling::ScalingPolicy", "Properties":{ "AutoScalingGroupName":{ "Ref":"myASG" }, "PolicyType":"TargetTrackingScaling", "TargetTrackingConfiguration":{ "PredefinedMetricSpecification":{ "PredefinedMetricType":"ASGAverageCPUUtilization" }, "TargetValue":{ "Ref":"CPUPolicyTargetValue" } } } }, "myALBRequestCountPolicy":{ "Type":"AWS::AutoScaling::ScalingPolicy", "Properties":{ "AutoScalingGroupName":{ "Ref":"myASG" }, "PolicyType":"TargetTrackingScaling", "TargetTrackingConfiguration":{ "PredefinedMetricSpecification":{ "PredefinedMetricType":"ALBRequestCountPerTarget", "ResourceLabel":{ "Fn::Join":[ "/", [ { "Fn::GetAtt":[ "myLoadBalancer", "LoadBalancerFullName" ] }, { "Fn::GetAtt":[ "myTargetGroup", "TargetGroupFullName" ] } ] ] } }, "TargetValue":{ "Ref":"ALBRequestCountTargetValue" } } } } } }

YAML

AWSTemplateFormatVersion: 2010-09-09 Parameters: AMI: Type: String Subnets: Type: CommaDelimitedList VPC: Type: String CPUPolicyTargetValue: Type: String ALBRequestCountTargetValue: Type: String Resources: myLoadBalancer: Type: AWS::ElasticLoadBalancingV2::LoadBalancer Properties: Subnets: !Ref Subnets myLoadBalancerListener: Type: "AWS::ElasticLoadBalancingV2::Listener" Properties: DefaultActions: - TargetGroupArn: !Ref myTargetGroup Type: forward LoadBalancerArn: !Ref myLoadBalancer Port: 80 Protocol: HTTP myTargetGroup: Type: "AWS::ElasticLoadBalancingV2::TargetGroup" Properties: Name: myTargetGroup Port: 80 Protocol: HTTP VpcId: !Ref VPC myLaunchConfig: Type: AWS::AutoScaling::LaunchConfiguration Properties: ImageId: !Ref AMI InstanceType: t2.large myASG: Type: AWS::AutoScaling::AutoScalingGroup Properties: MaxSize: '2' MinSize: '1' VPCZoneIdentifier: !Ref Subnets LaunchConfigurationName: !Ref myLaunchConfig TargetGroupARNs: - !Ref myTargetGroup myCPUPolicy: Type: AWS::AutoScaling::ScalingPolicy Properties: AutoScalingGroupName: !Ref myASG PolicyType: TargetTrackingScaling TargetTrackingConfiguration: PredefinedMetricSpecification: PredefinedMetricType: ASGAverageCPUUtilization TargetValue: !Ref CPUPolicyTargetValue myALBRequestCountPolicy: Type: AWS::AutoScaling::ScalingPolicy Properties: AutoScalingGroupName: !Ref myASG PolicyType: TargetTrackingScaling TargetTrackingConfiguration: PredefinedMetricSpecification: PredefinedMetricType: ALBRequestCountPerTarget ResourceLabel: !Join - '/' - - !GetAtt myLoadBalancer.LoadBalancerFullName - !GetAtt myTargetGroup.TargetGroupFullName TargetValue: !Ref ALBRequestCountTargetValue

Step Scaling Policy

The following example creates a scaling policy with the StepScaling policy type and the ChangeInCapacity adjustment type. When an associated alarm is triggered, the policy increases the capacity of the Auto Scaling group based on the following step adjustments (assuming a CloudWatch alarm threshold of 70 percent):

  • Increase capacity by 1 when the value of the metric is greater than or equal to 70 percent but less than 85 percent

  • Increase capacity by 2 when the value of the metric is greater than or equal to 85 percent but less than 95 percent

  • Increase capacity by 3 when the value of the metric is greater than or equal to 95 percent

JSON

{ "Resources":{ "ASGScalingPolicyHigh":{ "Type":"AWS::AutoScaling::ScalingPolicy", "Properties":{ "AdjustmentType":"ChangeInCapacity", "AutoScalingGroupName":{ "Ref":"myASG" }, "PolicyType":"StepScaling", "MetricAggregationType":"Average", "EstimatedInstanceWarmup":60, "StepAdjustments":[ { "MetricIntervalLowerBound":0, "MetricIntervalUpperBound":15, "ScalingAdjustment":1 }, { "MetricIntervalLowerBound":15, "MetricIntervalUpperBound":25, "ScalingAdjustment":2 }, { "MetricIntervalLowerBound":25, "ScalingAdjustment":3 } ] } } } }

YAML

--- Resources: ASGScalingPolicyHigh: Type: AWS::AutoScaling::ScalingPolicy Properties: AdjustmentType: "ChangeInCapacity" AutoScalingGroupName: Ref: "myASG" PolicyType: "StepScaling" MetricAggregationType: "Average" EstimatedInstanceWarmup: 60 StepAdjustments: - MetricIntervalLowerBound: 0 MetricIntervalUpperBound: 15 ScalingAdjustment: 1 - MetricIntervalLowerBound: 15 MetricIntervalUpperBound: 25 ScalingAdjustment: 2 - MetricIntervalLowerBound: 25 ScalingAdjustment: 3

Simple Scaling Policy

The following example creates a scaling policy with the SimpleScaling policy type and the ChangeInCapacity adjustment type. The policy increases capacity by one when it is triggered.

JSON

{ "Resources":{ "ASGScalingPolicyHigh":{ "Type":"AWS::AutoScaling::ScalingPolicy", "Properties":{ "AdjustmentType":"ChangeInCapacity", "PolicyType":"SimpleScaling", "Cooldown":"300", "AutoScalingGroupName":{ "Ref":"myASG" }, "ScalingAdjustment":1 } } } }

YAML

--- Resources: ASGScalingPolicyHigh: Type: AWS::AutoScaling::ScalingPolicy Properties: AdjustmentType: "ChangeInCapacity" PolicyType: "SimpleScaling" Cooldown: "300" AutoScalingGroupName: Ref: "myASG" ScalingAdjustment: 1