Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Create a step scaling policy using the Amazon CLI

You can create a step scaling policy for Application Auto Scaling by using the Amazon CLI for the following configuration tasks.

For brevity, the examples in this topic illustrate CLI commands for an Amazon ECS service. To specify a different scalable target, specify its namespace in --service-namespace, its scalable dimension in --scalable-dimension, and its resource ID in --resource-id. For more information and examples for each service, see the topics in Amazon services that you can use with Application Auto Scaling.

When using the Amazon CLI, remember that your commands run in the Amazon Web Services Region configured for your profile. If you want to run the commands in a different Region, either change the default Region for your profile, or use the --region parameter with the command.

Register a scalable target

If you haven't already done so, register the scalable target. Use the register-scalable-target command to register a specific resource in the target service as a scalable target. The following example registers an Amazon ECS service with Application Auto Scaling. Application Auto Scaling can scale the number of tasks at a minimum of 2 tasks and a maximum of 10. Replace each user input placeholder with your own information.

Linux, macOS, or Unix

aws application-autoscaling register-scalable-target --service-namespace ecs \
  --scalable-dimension ecs:service:DesiredCount \
  --resource-id service/my-cluster/my-service \
  --min-capacity 2 --max-capacity 10

Windows

aws application-autoscaling register-scalable-target --service-namespace ecs --scalable-dimension ecs:service:DesiredCount --resource-id service/my-cluster/my-service --min-capacity 2 --max-capacity 10

If successful, this command returns the ARN of the scalable target.

{
    "ScalableTargetARN": "arn:aws-cn:application-autoscaling:region:account-id:scalable-target/1234abcd56ab78cd901ef1234567890ab123"
}

Create a step scaling policy

To create a step scaling policy for your scalable target, you can use the following examples to help you get started.

Scale out

To create a step scaling policy for scale out (increase capacity)

1. Use the following cat command to store a step scaling policy configuration in a JSON file named config.json in your home directory. The following is an example configuration with an adjustment type of PercentChangeInCapacity that increases the capacity of the scalable target based on the following step adjustments (assuming a CloudWatch alarm threshold of 70):

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

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

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

   $ cat ~/config.json
   {
     "AdjustmentType": "PercentChangeInCapacity",
     "MetricAggregationType": "Average",
     "Cooldown": 60,
     "MinAdjustmentMagnitude": 1,
     "StepAdjustments": [ 
       {
         "MetricIntervalLowerBound": 0.0,
         "MetricIntervalUpperBound": 15.0,
         "ScalingAdjustment": 10
       },
       {
         "MetricIntervalLowerBound": 15.0,
         "MetricIntervalUpperBound": 25.0,
         "ScalingAdjustment": 20
       },
       {
         "MetricIntervalLowerBound": 25.0,
         "ScalingAdjustment": 30
       }
     ]
   }

   For more information, see StepScalingPolicyConfiguration in the Application Auto Scaling API Reference.

2. Use the following put-scaling-policy command, along with the config.json file that you created, to create a scaling policy named my-step-scaling-policy.

   Linux, macOS, or Unix

   aws application-autoscaling put-scaling-policy --service-namespace ecs \
     --scalable-dimension ecs:service:DesiredCount \
     --resource-id service/my-cluster/my-service \
     --policy-name my-step-scaling-policy --policy-type StepScaling \
     --step-scaling-policy-configuration file://config.json

   Windows

   aws application-autoscaling put-scaling-policy --service-namespace ecs --scalable-dimension ecs:service:DesiredCount --resource-id service/my-cluster/my-service --policy-name my-step-scaling-policy --policy-type StepScaling --step-scaling-policy-configuration file://config.json

   The output includes the ARN that serves as a unique name for the policy. You need it to create a CloudWatch alarm for your policy.

   {
       "PolicyARN": "arn:aws-cn:autoscaling:region:123456789012:scalingPolicy:ac542982-cbeb-4294-891c-a5a941dfa787:resource/ecs/service/my-cluster/my-service:policyName/my-step-scaling-policy"
   }

Scale in

To create a step scaling policy for scale in (decrease capacity)

1. Use the following cat command to store a step scaling policy configuration in a JSON file named config.json in your home directory. The following is an example configuration with an adjustment type of ChangeInCapacity that decreases the capacity of the scalable target based on the following step adjustments (assuming a CloudWatch alarm threshold of 50):

   • Decrease capacity by 1 when the value of the metric is less than or equal to 50 but greater than 40

   • Decrease capacity by 2 when the value of the metric is less than or equal to 40 but greater than 30

   • Decrease capacity by 3 when the value of the metric is less than or equal to 30

   $ cat ~/config.json
   {
     "AdjustmentType": "ChangeInCapacity",
     "MetricAggregationType": "Average",
     "Cooldown": 60,
     "StepAdjustments": [ 
       {
         "MetricIntervalUpperBound": 0.0,
         "MetricIntervalLowerBound": -10.0,
         "ScalingAdjustment": -1
       },
       {
         "MetricIntervalUpperBound": -10.0,
         "MetricIntervalLowerBound": -20.0,
         "ScalingAdjustment": -2
       },
       {
         "MetricIntervalUpperBound": -20.0,
         "ScalingAdjustment": -3
       }
     ]
   }

   For more information, see StepScalingPolicyConfiguration in the Application Auto Scaling API Reference.

2. Use the following put-scaling-policy command, along with the config.json file that you created, to create a scaling policy named my-step-scaling-policy.

   Linux, macOS, or Unix

   aws application-autoscaling put-scaling-policy --service-namespace ecs \
     --scalable-dimension ecs:service:DesiredCount \
     --resource-id service/my-cluster/my-service \
     --policy-name my-step-scaling-policy --policy-type StepScaling \
     --step-scaling-policy-configuration file://config.json

   Windows

   aws application-autoscaling put-scaling-policy --service-namespace ecs --scalable-dimension ecs:service:DesiredCount --resource-id service/my-cluster/my-service --policy-name my-step-scaling-policy --policy-type StepScaling --step-scaling-policy-configuration file://config.json

   The output includes the ARN that serves as a unique name for the policy. You need it to create a CloudWatch alarm for your policy.

   {
       "PolicyARN": "arn:aws-cn:autoscaling:region:123456789012:scalingPolicy:ac542982-cbeb-4294-891c-a5a941dfa787:resource/ecs/service/my-cluster/my-service:policyName/my-step-scaling-policy"
   }

Create an alarm that invokes the scaling policy

Finally, use the following CloudWatch put-metric-alarm command to create an alarm to use with your step scaling policy. In this example, you have an alarm based on average CPU utilization. The alarm is configured to be in an ALARM state if it reaches a threshold of 70 percent for at least two consecutive evaluation periods of 60 seconds. To specify a different CloudWatch metric or use your own custom metric, specify its name in --metric-name and its namespace in --namespace.

Linux, macOS, or Unix

aws cloudwatch put-metric-alarm --alarm-name Step-Scaling-AlarmHigh-ECS:service/my-cluster/my-service \
  --metric-name CPUUtilization --namespace AWS/ECS --statistic Average \
  --period 60 --evaluation-periods 2 --threshold 70 \
  --comparison-operator GreaterThanOrEqualToThreshold \
  --dimensions Name=ClusterName,Value=default Name=ServiceName,Value=sample-app-service \
  --alarm-actions PolicyARN

Windows

aws cloudwatch put-metric-alarm --alarm-name Step-Scaling-AlarmHigh-ECS:service/my-cluster/my-service --metric-name CPUUtilization --namespace AWS/ECS --statistic Average --period 60 --evaluation-periods 2 --threshold 70 --comparison-operator GreaterThanOrEqualToThreshold --dimensions Name=ClusterName,Value=default Name=ServiceName,Value=sample-app-service --alarm-actions PolicyARN

Describe step scaling policies

You can describe all scaling policies for the specified service namespace using the following describe-scaling-policies command.

aws application-autoscaling describe-scaling-policies --service-namespace ecs

You can filter the results to just the step scaling policies using the --query parameter. For more information about the syntax for query, see Controlling command output from the Amazon CLI in the Amazon Command Line Interface User Guide.

Linux, macOS, or Unix

aws application-autoscaling describe-scaling-policies --service-namespace ecs \
  --query 'ScalingPolicies[?PolicyType==`StepScaling`]'

Windows

aws application-autoscaling describe-scaling-policies --service-namespace ecs --query "ScalingPolicies[?PolicyType==`StepScaling`]"

The following is example output.

[
    {
        "PolicyARN": "PolicyARN",
        "StepScalingPolicyConfiguration": {
            "MetricAggregationType": "Average",
            "Cooldown": 60,
            "StepAdjustments": [
                {
                    "MetricIntervalLowerBound": 0.0,
                    "MetricIntervalUpperBound": 15.0,
                    "ScalingAdjustment": 1
                },
                {
                    "MetricIntervalLowerBound": 15.0,
                    "MetricIntervalUpperBound": 25.0,
                    "ScalingAdjustment": 2
                },
                {
                    "MetricIntervalLowerBound": 25.0,
                    "ScalingAdjustment": 3
                }
            ],
            "AdjustmentType": "ChangeInCapacity"
        },
        "PolicyType": "StepScaling",
        "ResourceId": "service/my-cluster/my-service",
        "ServiceNamespace": "ecs",
        "Alarms": [
            {
                "AlarmName": "Step-Scaling-AlarmHigh-ECS:service/my-cluster/my-service",
                "AlarmARN": "arn:aws-cn:cloudwatch:region:012345678910:alarm:Step-Scaling-AlarmHigh-ECS:service/my-cluster/my-service"
            }
        ],
        "PolicyName": "my-step-scaling-policy",
        "ScalableDimension": "ecs:service:DesiredCount",
        "CreationTime": 1515024099.901
    }
]

Delete a step scaling policy

When you no longer need a step scaling policy, you can delete it. To delete both the scaling policy and the CloudWatch alarm, complete the following tasks.

To delete your scaling policy

Use the following delete-scaling-policy command.

Linux, macOS, or Unix

aws application-autoscaling delete-scaling-policy --service-namespace ecs \
  --scalable-dimension ecs:service:DesiredCount \
  --resource-id service/my-cluster/my-service \
  --policy-name my-step-scaling-policy

Windows

aws application-autoscaling delete-scaling-policy --service-namespace ecs --scalable-dimension ecs:service:DesiredCount --resource-id service/my-cluster/my-service --policy-name my-step-scaling-policy

To delete the CloudWatch alarm

Use the delete-alarms command. You can delete one or more alarms at a time. For example, use the following command to delete the Step-Scaling-AlarmHigh-ECS:service/my-cluster/my-service and Step-Scaling-AlarmLow-ECS:service/my-cluster/my-service alarms.

aws cloudwatch delete-alarms --alarm-name Step-Scaling-AlarmHigh-ECS:service/my-cluster/my-service Step-Scaling-AlarmLow-ECS:service/my-cluster/my-service