# Automatically scale your Amazon ECS service Service auto scaling *Automatic scaling* is the ability to increase or decrease the desired number of tasks in your Amazon ECS service automatically. Amazon ECS leverages the Application Auto Scaling service to provide this functionality. For more information, see the [Application Auto Scaling User Guide](https://docs.aws.amazon.com/autoscaling/application/userguide/what-is-application-auto-scaling.html). Amazon ECS publishes CloudWatch metrics with your service’s average CPU and memory usage. For more information, see [Amazon ECS service utilization metrics](service_utilization.md). You can use these and other CloudWatch metrics to scale out your service (add more tasks) to deal with high demand at peak times, and to scale in your service (run fewer tasks) to reduce costs during periods of low utilization. Amazon ECS Service Auto Scaling supports the following types of automatic scaling: + [Use a target metric to scale Amazon ECS services](service-autoscaling-targettracking.md)— Increase or decrease the number of tasks that your service runs based on a target value for a specific metric. This is similar to the way that your thermostat maintains the temperature of your home. You select temperature and the thermostat does the rest. + [Use predefined increments based on CloudWatch alarms to scale Amazon ECS services](service-autoscaling-stepscaling.md)— Increase or decrease the number of tasks that your service runs based on a set of scaling adjustments, known as step adjustments, that vary based on the size of the alarm breach. + [Use scheduled actions to scale Amazon ECS services](service-autoscaling-schedulescaling.md)—Increase or decrease the number of tasks that your service runs based on the date and time. + [Use historical patterns to scale Amazon ECS services with predictive scaling](predictive-auto-scaling.md)—Increase or decrease the number of tasks that your service runs based on historical load data analytics to detect daily or weekly patterns in traffic flows. ## Considerations When using scaling policies, consider the following: + Amazon ECS sends metrics in 1-minute intervals to CloudWatch. Metrics are not available until the clusters and services send the metrics to CloudWatch, and you cannot create CloudWatch alarms for metrics that do not exist. + The scaling policies support a cooldown period. This is the number of seconds to wait for a previous scaling activity to take effect. + For scale-out events, the intention is to continuously (but not excessively) scale out. After Service Auto Scaling successfully scales out using a scaling policy, it starts to calculate the cooldown time. The scaling policy won't increase the desired capacity again unless either a larger scale out is initiated or the cooldown period ends. While the scale-out cooldown period is in effect, the capacity added by the initiating scale-out activity is calculated as part of the desired capacity for the next scale-out activity. + For scale-in events, the intention is to scale in conservatively to protect your application's availability, so scale-in activities are blocked until the cooldown period has expired. However, if another alarm initiates a scale-out activity during the scale-in cooldown period, Service Auto Scaling scales out the target immediately. In this case, the scale-in cooldown period stops and doesn't complete. + The service scheduler respects the desired count at all times, but as long as you have active scaling policies and alarms on a service, Service Auto Scaling could change a desired count that was manually set by you. + If a service's desired count is set below its minimum capacity value, and an alarm initiates a scale-out activity, Service Auto Scaling scales the desired count up to the minimum capacity value and then continues to scale out as required, based on the scaling policy associated with the alarm. However, a scale-in activity does not adjust the desired count, because it is already below the minimum capacity value. + If a service's desired count is set above its maximum capacity value, and an alarm initiates a scale in activity, Service Auto Scaling scales the desired count out to the maximum capacity value and then continues to scale in as required, based on the scaling policy associated with the alarm. However, a scale-out activity does not adjust the desired count, because it is already above the maximum capacity value. + During scaling activities, the actual running task count in a service is the value that Service Auto Scaling uses as its starting point, as opposed to the desired count. This is what processing capacity is supposed to be. This prevents excessive (runaway) scaling that might not be satisfied, for example, if there aren't enough container instance resources to place the additional tasks. If the container instance capacity is available later, the pending scaling activity may succeed, and then further scaling activities can continue after the cooldown period. + If you want your task count to scale to zero when there's no work to be done, set a minimum capacity of 0. With target tracking scaling policies, when actual capacity is 0 and the metric indicates that there is workload demand, Service Auto Scaling waits for one data point to be sent before scaling out. In this case, it scales out by the minimum possible amount as a starting point and then resumes scaling based on the actual running task count. + Application Auto Scaling turns off scale-in processes while Amazon ECS deployments are in progress. However, scale-out processes continue to occur, unless suspended, during a deployment. This behavior does not apply to Amazon ECS services using the external deployment controller. For more information, see [Service auto scaling and deployments](#service-auto-scaling-deployments). + You have several Application Auto Scaling options for Amazon ECS tasks. Target tracking is the easiest mode to use. With it, all you need to do is set a target value for a metric, such as CPU average utilization. Then, the auto scaler automatically manages the number of tasks that are needed to attain that value. With step scaling you can more quickly react to changes in demand, because you define the specific thresholds for your scaling metrics, and how many tasks to add or remove when the thresholds are crossed. And, more importantly, you can react very quickly to changes in demand by minimizing the amount of time a threshold alarm is in breach. For more information about best practices for service auto scaling, see [Optimizing Amazon ECS service auto scaling](capacity-autoscaling-best-practice.md). ## Service auto scaling and deployments Application Auto Scaling turns off scale-in processes while Amazon ECS deployments are in progress. However, scale-out processes continue to occur, unless suspended, during a deployment. This behavior does not apply to Amazon ECS services using the external deployment controller. If you want to suspend scale-out processes while deployments are in progress, take the following steps. 1. Call the [describe-scalable-targets](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/describe-scalable-targets.html) command, specifying the resource ID of the service associated with the scalable target in Application Auto Scaling (Example: `service/default/sample-webapp`). Record the output. You will need it when you call the next command. 1. Call the [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) command, specifying the resource ID, namespace, and scalable dimension. Specify `true` for both `DynamicScalingInSuspended` and `DynamicScalingOutSuspended`. 1. After deployment is complete, you can call the [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) command to resume scaling. For more information, see [Suspending and resuming scaling for Application Auto Scaling](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-suspend-resume-scaling.html). # Use a target metric to scale Amazon ECS services Target tracking With target tracking scaling policies, you select a metric and set a target value. Amazon ECS Service Auto Scaling creates and manages the CloudWatch alarms that control the scaling policy and calculates the scaling adjustment based on the metric and the target value. The scaling policy adds or removes service tasks as required to keep the metric at, or close to, the specified target value. In addition to keeping the metric close to the target value, a target tracking scaling policy also adjusts to the fluctuations in the metric due to a fluctuating load pattern and minimizes rapid fluctuations in the number of tasks running in your service. Target tracking policies remove the need to manually define CloudWatch alarms and scaling adjustments. Amazon ECS handles this automatically based on the target you set. Consider the following when using target tracking policies: + A target tracking scaling policy assumes that it should perform scale out when the specified metric is above the target value. You cannot use a target tracking scaling policy to scale out when the specified metric is below the target value. + A target tracking scaling policy does not perform scaling when the specified metric has insufficient data. It does not perform scale in because it does not interpret insufficient data as low utilization. + You may see gaps between the target value and the actual metric data points. This is because Service Auto Scaling always acts conservatively by rounding up or down when it determines how much capacity to add or remove. This prevents it from adding insufficient capacity or removing too much capacity. + To ensure application availability, the service scales out proportionally to the metric as fast as it can, but scales in more gradually. + Application Auto Scaling turns off scale-in processes while Amazon ECS deployments are in progress. However, scale-out processes continue to occur, unless suspended, during a deployment. This behavior does not apply to Amazon ECS services using the external deployment controller. For more information, see [Service auto scaling and deployments](service-auto-scaling.md#service-auto-scaling-deployments). + You can have multiple target tracking scaling policies for an Amazon ECS service, provided that each of them uses a different metric. The intention of Service Auto Scaling is to always prioritize availability, so its behavior differs depending on whether the target tracking policies are ready for scale out or scale in. It will scale out the service if any of the target tracking policies are ready for scale out, but will scale in only if all of the target tracking policies (with the scale-in portion turned on) are ready to scale in. + Do not edit or delete the CloudWatch alarms that Service Auto Scaling manages for a target tracking scaling policy. Service Auto Scaling deletes the alarms automatically when you delete the scaling policy. + The `ALBRequestCountPerTarget` metric for target tracking scaling policies is not supported for the blue/green deployment type. For more information about target tracking scaling policies, see [Target tracking scaling policies](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html) in the *Application Auto Scaling User Guide*. # Create a target tracking scaling policy for Amazon ECS service auto scaling Create a target tracking scaling policy Create a target tracking scaling policy to have Amazon ECS increase or decrease the desired task count in your service automatically. Target tracking works off of a target metric value. ## Console 1. In addition to the standard IAM permissions for creating and updating services, you need additional permissions. For more information, see [IAM permissions required for Amazon ECS service auto scaling](auto-scaling-IAM.md). 1. Determine the metrics to use for the policy. The following metrics are available: + **ECSServiceAverageCPUUtilization** – The average CPU utilization the service should use. + **ECSServiceAverageMemoryUtilization** – Average memory utilization the service should use. + **ALBRequestCountPerTarget** – The average number of requests per minute that task should ideally receive. 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, and then choose the service. The service details page appears. 1. Choose **Set the number of tasks**. 1. Under **Amazon ECS service task count**, choose **Use auto scaling**. The **Task count section** appears. 1. For **Minimum number of tasks**, enter the lower limit of the number of tasks for service auto scaling to use. The desired count will not go below this count. 1. For **Maximum**, enter the upper limit of the number of tasks for service auto scaling to use. The desired count will not go above this count. 1. Choose **Save**. The policies page appears. 1. Choose **Create scaling policy**. The **Create policy** page appears. 1. For **Scaling policy type**, choose **Target tracking**. 1. For **Policy name**, enter the name of the policy. 1. For **Metric type**, choose your metrics from the list of options. 1. For **Target utilization**, enter the target value for the percentage of tasks that Amazon ECS should maintain. Service auto scaling scales out your capacity until the average utilization is at the target utilization, or until it reaches the maximum number of tasks you specified. 1. Under **Additional Settings**, do the following 1. For **Scale-in cooldown period**, enter the amount of time in seconds after a scale-in activity completes before another scale-in activity can start. 1. For **Scale-out cooldown period**, enter the amount of time in seconds to wait for a previous scale-out activity to take effect. 1. To create only a scale-out policy, select **Disable scale-in**. 1. Choose **Create scaling policy**. ## AWS CLI 1. Register your Amazon ECS service as a scalable target using the [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) command. 1. Create a scaling policy using the [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html) command. # Use predefined increments based on CloudWatch alarms to scale Amazon ECS services Step scaling With step scaling policies, you create and manage the CloudWatch alarms that invoke the scaling process. When an alarm is breached, Amazon ECS initiates the scaling policy associated with that alarm. The step scaling policy scales tasks using a set of adjustments, known as step adjustments. The size of the adjustment varies based on the magnitude of the alarm breach. + If the breach exceeds the first threshold, Amazon ECS applies the first step adjustment. + If the breach exceeds the second threshold, Amazon ECS applies the second step adjustment, and so on. We strongly recommend that you use target tracking scaling policies to scale on metrics like average CPU utilization or average request count per target. Metrics that decrease when capacity increases and increase when capacity decreases can be used to proportionally scale out or in the number of tasks using target tracking. This helps ensure that Amazon ECS follows the demand curve for your applications closely. # Create a step scaling policy for Amazon ECS service auto scaling Create a step scaling policy Create a step scaling policy to have Amazon ECS increase or decrease the desired number of tasks in your service automatically. Step scaling runs based on a set of scaling adjustments, known as step adjustments, that vary based on the size of the alarm breach. ## Console 1. In addition to the standard IAM permissions for creating and updating services, you need additional permissions. For more information, see [IAM permissions required for Amazon ECS service auto scaling](auto-scaling-IAM.md). 1. Determine the metrics to use for the policy. The following metrics are available: + **ECSServiceAverageCPUUtilization** – The average CPU utilization the service should use. + **ECSServiceAverageMemoryUtilization** – Average memory utilization the service should use. + **ALBRequestCountPerTarget** – The average number of requests per minute that task should ideally receive. 1. Create the CloudWatch alarms for the metrics. For more information, see [Create a CloudWatch alarm based on a static threshold](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ConsoleAlarms.html) in the *Amazon CloudWatch User Guide*. 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, and then choose the service. The service details page appears. 1. Choose **Set the number of tasks**. 1. Under **Amazon ECS service task count**, choose **Use auto scaling**. The **Task count section** appears. 1. For **Minimum number of tasks**, enter the lower limit of the number of tasks for service auto scaling to use. The desired count will not go below this count. 1. For **Maximum**, enter the upper limit of the number of tasks for service auto scaling to use. The desired count will not go above this count. 1. Choose **Save**. The policies page appears. 1. Choose **Create scaling policy**. The **Create policy** page appears. 1. For **Scaling policy type**, choose **Step Scaling**. 1. Configure the scaling-out properties. Under **Steps to add tasks** do the following: 1. For **Policy name**, enter the name of the policy. 1. For **CloudWatch alarm name**, choose the CloudWatch alarm. 1. For **Metric aggregation type**, choose how to compare the selected metric to the defined threshold. 1. For A**djustment types**, choose whether the adjustment is based on a change in the number of tasks, or a change in the percentage of tasks. 1. For **Actions to take**, enter the values for what action to take. Choose **Add step** to add additional actions. 1. Configure the scaling-in properties. Under **Steps to remove tasks**, do the following: 1. For **Policy name**, enter the name of the policy. 1. For **CloudWatch alarm name**, choose the CloudWatch alarm. 1. For **Metric aggregation type**, choose how to compare the selected metric to the defined threshold. 1. For **Adjustment types**, choose whether the adjustment is based on a change in the number of tasks, or a change in the percentage of tasks. 1. For **Actions to take**, enter the values for what action to take. Choose **Add step** to add additional actions. 1. For **Cooldown period**, enter the amount of time, in seconds, to wait for a previous scaling activity to take effect. For an add policy, this is the time after a scale-out activity that the scaling policy blocks scale-in activities and limits how many tasks can be scale out at a time. For a remove policy, this is the time after a scale-in activity that must pass before another scale-in activity can start. 1. Choose **Create scaling policy**. ## AWS CLI 1. Register your Amazon ECS service as a scalable target using the [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) command. 1. Create a scaling policy using the [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html) command. # Use scheduled actions to scale Amazon ECS services Schedule scaling With scheduled scaling, you can set up automatic scaling for your application based on predictable load changes by creating scheduled actions that increase or decrease the number of tasks at specific times. This allows you to scale your application proactively to match predictable load changes. These scheduled scaling actions allow you to optimize costs and performance. Your application has a sufficient number of tasks to handle the mid-week traffic peak, but does not over-provision the number of tasks at other times. You can use scheduled scaling and scaling policies together to get the benefits of proactive and reactive approaches to scaling. After a scheduled scaling action runs, the scaling policy can continue to make decisions about whether to further scale the number of tasks. This helps you ensure that you have a sufficient number of tasks to handle the load for your application. While your application scales to match demand, current capacity must fall within the minimum and maximum number of tasks that was set by your scheduled action. You can configure schedule scaling using the AWS CLI. For more information about scheduled scaling, see [Scheduled Scaling](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-scheduled-scaling.html) in the *Application Auto Scaling User Guide*. # Create a scheduled action for Amazon ECS service auto scaling Create a scheduled action Create a scheduled action to have Amazon ECS increase or decrease the number of tasks that your service runs based on the date and time. ## Console 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, choose the service. The service details page appears. 1. Choose **Service auto scaling**. The service auto scaling page appears. 1. If you haven't configured service auto scaling, choose **Set the number of tasks**. The **Amazon ECS service task count** section appears. Under **Amazon ECS service task count**, choose **Use service auto scaling to adjust your service's desired task count**. The **Task count section** appears. 1. For **Minimum number of tasks**, enter the lower limit of the number of tasks for service auto scaling to use. The desired count will not go below this count. 1. For **Maximum**, enter the upper limit of the number of tasks for service auto scaling to use. The desired count will not go above this count. 1. Choose **Choose Save**. The policies page appears. 1. Choose **Scheduled actions**, and then choose **Create**. The **Create Scheduled action** page appears. 1. For **Action name**, enter a unique name. 1. For **Time zone**, choose a time zone. All of the time zones listed are from the IANA Time Zone database. For more information, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). 1. For **Start time**, enter the **Date** and **Time** the action starts. If you chose a recurring schedule, the start time defines when the first scheduled action in the recurring series runs. 1. For **Recurrence**, choose one of the available options. + To scale on a recurring schedule, choose how often Amazon ECS runs the scheduled action. + If you choose an option that begins with **Rate**, the cron expression is created for you. + If you choose **Cron**, enter a cron expression that specifies when to perform the action. + To scale only once, choose **Once**. 1. Under **Task adjustments**, do the following: + For **Minimum**, enter the minumum number of tasks the service should run. + For **Maximum**, enter the maximum number of tasks the service should run. 1. Choose **Create scheduled action**. ## CLI Use the AWS CLI as follows to configure scheduled scaling policies for your service. Replace each *user input placeholder* with your own information. **Example: To scale one time only** Use the following [put-scheduled-action](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scheduled-action.html) command with the `--start-time "YYYY-MM-DDThh:mm:ssZ"` and and either or both of the `--MinCapacity` and `--MaxCapacity` options. ``` aws application-autoscaling put-scheduled-action --service-namespace ecs \ --resource-id service/my-cluster/my-service \ --scheduled-action-name my-one-time-schedule \ --start-time 2021-01-30T12:00:00 \ --scalable-target-action MinCapacity=3,MaxCapacity=10 ``` **Example: To schedule scaling on a recurring schedule** Use the following [put-scheduled-action](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scheduled-action.html) command. Replace the *user input* with your values. ``` aws application-autoscaling put-scheduled-action --service-namespace ecs \ --resource-id service/my-cluster/my-service \ --scheduled-action-name my-recurring-action \ --schedule "rate(5 hours)" \ --start-time 2021-01-30T12:00:00 \ --end-time 2021-01-31T22:00:00 \ --scalable-target-action MinCapacity=3,MaxCapacity=10 ``` The specified recurrence schedule runs based on the UTC time zone. To specify a different time zone, include the `--time-zone` option and the name of the IANA time zone, as in the following example. ``` --time-zone "America/New_York" ``` For more information, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). # Use historical patterns to scale Amazon ECS services with predictive scaling Predictive scaling Predictive scaling looks at past load data from traffic flows to analyze daily or weekly patterns. It then uses this analysis to anticipate future needs and proactively increase tasks in your service as needed. Predictive auto scaling is most useful in the following situations. + Cyclical traffic ‐ Increased use of resources during regular business hours, and decreased use of resources during evenings and weekends. + Recurring on-and-off workload patterns ‐ Examples include batch processing, testing, or periodic data analysis. + Applications with long initialization times ‐ This can impact application performance during scale-out events causing of noticeable latency. If your applications take a long time to initialize and traffic increases in a regular pattern, you should consider using predicitive scaling. It helps you scale faster by proactively increasing the number of tasks for forecasted loads, instead of using dynamic scaling policies, such as Target Tracking or Step Scaling alone. By helping you avoid the possibility of over-provisioning the number of tasks, predictive scaling can also potentially save you money. For example, consider an application that has high usage during business hours and low usage overnight. At the start of each business day, predictive scaling can scale-out tasks before the first influx of traffic. This helps your application maintain high availability and performance when going from a period of lower utilization to a period of higher utilization. You don't have to wait for dynamic scaling to react to changing traffic. You also don't have to spend time reviewing your application's load patterns and trying to schedule the right amount of tasks using scheduled scaling. Predictive scaling is a service-level capability that scales the task of your service independently from the scaling of the underlying compute capacity (for example, EC2 or Fargate). For Fargate, AWS manages and automatically scales the underlying capacity based on task requirements. For EC2 capacity, you can use Auto Scaling group capacity providers to automatically scale underlying EC2 instances based on the scaling requirements of your tasks. **Topics** + [Predictive scaling overview](#predictive-auto-scaling-overview) + [Create a predictive scaling policy](predictive-scaling-create-policy.md) + [Evaluate your predictive scaling policies](predictive-scaling-graphs.md) + [Override the forecast](predictive-scaling-overriding-forecast-capacity.md) + [Use custom metrics](predictive-scaling-custom-metrics.md) ## How predictive scaling works in Amazon ECS Predictive scaling overview Here you can learn about considerations for using predictive scaling, how it works, and what the limits are. ### Considerations for using predictive scaling Considerations + You want to make sure predictive scaling is suitable for your workload. You can check this by configuring scaling policies in **forecast only** mode and see what the console recommends. You should evaluate the forecast and recommendations before starting to use predictive scaling. + Before predictive scaling can start forecasting, it needs at least 24 hours of historical data. The more historical data that is available, the more effective the forecast, with two weeks being ideal. You'll also need to wait 24 hours for before predictive scaling can generate new forecasts when you delete an Amazon ECS service and create a new one. One way to speed this up is to use custom metrics to aggregate metrics across old and new Amazon ECS service. + Choose a load metric that accurately represents the full load on your application and is the aspect of your application that's most important to scale on. + Dynamic scaling with predictive scaling helps you follow the demand for your application closely, so you can scale in during lulls and scale out during unexpected increases in traffic. When multiple scaling policies are active, each policy determines the desired number of tasks independently, and the desired number of tasks is set to the maximum of those. + You can use predictive scaling alongside your dynamic scaling policies, such as target tracking or step scaling, so that your applications scale based on both real-time and historic patterns. By itself, predictive scaling doesn't scale-in your tasks. + If you use a custom role when calling the `register-scalable-target` API, you may get an error saying predictive scaling policy can only work with SLR enabled. In this case you should call `register-scalable-target` again but without role-arn. Use SLR when registering the scalable target and call the `put-scaling-policy` API. ### How predictive scaling works How it works You use predictive scaling by creating a predictive scaling policy that specifies the CloudWatch metric to monitor and analyze. Predictive scaling must have at least 24 hours of data to start forecasting future values. After you create the policy, predictive scaling starts analyzing metric data from up to the past 14 days to identify patterns. This analysis is used to generate the next 48 hours of requirements hourly forecasts. The latest CloudWatch data is used to update the forecast every six hours. As new data comes in, predictive scaling continuously improves the accuracy of future forecasts. When you first enable predictive scaling, it runs in *forecast only* mode. It generates forecasts in this mode, but it doesn't scale your Amazon ECS service based on those forecasts. This means you can evaluate the accuracy and suitability of the forecast. You view forecast data by using the `GetPredictiveScalingForecast` API operation or the AWS Management Console. When you decide to start using predictive scaling, switch the scaling policy to *forecast and scale* mode. The following occurs while in this mode. Your Amazon ECS service is scaled at the start of each hour based on the forecast for that hour, by default. You can choose to start earlier by using the `SchedulingBufferTime` property in the `PutScalingPolicy` API operation. This makes new tasks launch ahead of forecasted demand and gives them time to boot and become ready to handle traffic. ### Maximum tasks limit When you register Amazon ECS services for scaling, you define a maximum number of tasks that can be launched per service. By default, when scaling policies are set, they cannot increase the number of tasks higher than its maximum limit. Alternatively, you can allow the service's maximum number of tasks to be automatically increased if the forecast approaches or exceeds the maximum number of tasks of the Amazon ECS service. **Warning** Use caution when allowing the maximum number of tasks to be automatically increased. This can lead to more tasks being launched than intended, if the increased maximum number of tasks isn't monitored and managed. The increased maximum number of tasks then becomes the new normal maximum number of tasks for the Amazon ECS service until you manually update it. The maximum number of tasks doesn't automatically decrease back to the original maximum. ### Supported regions + US East (N. Virginia) + US East (Ohio) + US West (N. California) + US West (Oregon) + Africa (Cape Town) + Asia Pacific (Hong Kong) + Asia Pacific (Jakarta) + Asia Pacific (Mumbai) + Asia Pacific (Osaka) + Asia Pacific (Seoul) + Asia Pacific (Singapore) + Asia Pacific (Sydney) + Asia Pacific (Tokyo) + Canada (Central) + China (Beijing) + China (Ningxia) + Europe (Frankfurt) + Europe (Ireland) + Europe (London) + Europe (Milan) + Europe (Paris) + Europe (Stockholm) + Middle East (Bahrain) + South America (São Paulo) + AWS GovCloud (US-East) + AWS GovCloud (US-West) # Create a predictive scaling policy for Amazon ECS service auto scaling Create a predictive scaling policy Create a predictive scaling policy to have Amazon ECS increase or decrease the number of tasks that your service runs based on historical data. **Note** A new service needs to provide at least 24 hours of data before a forecast can be generated. ## Console 1. In addition to the standard IAM permissions for creating and updating services, you need additional permissions. For more information, see [IAM permissions required for Amazon ECS service auto scaling](auto-scaling-IAM.md). 1. Determine the metrics to use for the policy. The following metrics are available: + **ECSServiceAverageCPUUtilization** – The average CPU utilization the service should use. + **ECSServiceAverageMemoryUtilization** – Average memory utilization the service should use. + **ALBRequestCountPerTarget** – The average number of requests per minute that task should ideally receive. You can alternatively use a custom metric. You need to define the following values: + Load - a metric that accurately represents the full load on your application and is the aspect of your application that's most important to scale on. + Scaling metric - the best predictor for how much utilization is ideal for your application. 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, choose the service. The service details page appears. 1. Choose **Service auto scaling** and then choose **Set the number of tasks**. 1. Under **Amazon ECS service task count**, choose **Use auto scaling**. The **Task count section** appears. 1. For **Minimum number of tasks**, enter the lower limit of the number of tasks for service auto scaling to use. The desired count will not go below this count. 1. For **Maximum**, enter the upper limit of the number of tasks for service auto scaling to use. The desired count will not go above this count. 1. Choose **Save**. The policies page appears. 1. Choose **Create scaling policy**. The **Create policy** page appears. 1. For **Scaling policy type**, choose **Predictive Scaling**. 1. For **Policy name**, enter the name of the policy. 1. For **Metric pair**, choose your metrics from the list of options. If you chose **Application Load Balancer request count per target**, then choose a target group in **Target group**. **Application Load Balancer request count per target** is only supported if you have attached an Application Load Balancer target group for your service. If you chose **Custom metric pair**, choose individual metrics from the lists for **Load metric** and **Scaling metric**. 1. For **Target utilization**, enter the target value for the percentage of tasks that Amazon ECS should maintain. Service auto scaling scales out your capacity until the average utilization is at the target utilization, or until it reaches the maximum number of tasks you specified. 1. Choose **Create scaling policy**. ## AWS CLI Use the AWS CLI as follows to configure predictive scaling policies for your Amazon ECS service. Replace each *user input placeholder* with your own information. For more information about the CloudWatch metrics you can specify, see [PredictiveScalingMetricSpecification](https://docs.aws.amazon.com/autoscaling/ec2/APIReference/API_PredictiveScalingMetricSpecification.html) in the *Amazon EC2 Auto Scaling API Reference*. ### Example 1: A predictive scaling policy with predefined memory. The following is an example policy with a predefined memory configuration. ``` cat policy.json { "MetricSpecifications": [ { "TargetValue": 40, "PredefinedMetricPairSpecification": { "PredefinedMetricType": "ECSServiceMemoryUtilization" } } ], "SchedulingBufferTime": 3600, "MaxCapacityBreachBehavior": "HonorMaxCapacity", "Mode": "ForecastOnly" } ``` The following example illustrates creating the policy by running the [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/put-scaling-policy.html) command with the configuration file specified. ``` aws application-autoscaling put-scaling-policy \ --service-namespace ecs \ --region us-east-1 \ --policy-name predictive-scaling-policy-example \ --resource-id service/MyCluster/test \ --policy-type PredictiveScaling \ --scalable-dimension ecs:service:DesiredCount \ --predictive-scaling-policy-configuration file://policy.json ``` If successful, this command returns the policy's ARN. ``` { "PolicyARN": "arn:aws:autoscaling:us-east-1:012345678912:scalingPolicy:d1d72dfe-5fd3-464f-83cf-824f16cb88b7:resource/ecs/service/MyCluster/test:policyName/predictive-scaling-policy-example", "Alarms": [] } ``` ### Example 2: A predictive scaling policy with predefined CPU. The following is an example policy with a predefined CPU configuration. ``` cat policy.json { "MetricSpecifications": [ { "TargetValue": 0.00000004, "PredefinedMetricPairSpecification": { "PredefinedMetricType": "ECSServiceCPUUtilization" } } ], "SchedulingBufferTime": 3600, "MaxCapacityBreachBehavior": "HonorMaxCapacity", "Mode": "ForecastOnly" } ``` The following example illustrates creating the policy by running the [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/put-scaling-policy.html) command with the configuration file specified. ``` aws aas put-scaling-policy \ --service-namespace ecs \ --region us-east-1 \ --policy-name predictive-scaling-policy-example \ --resource-id service/MyCluster/test \ --policy-type PredictiveScaling \ --scalable-dimension ecs:service:DesiredCount \ --predictive-scaling-policy-configuration file://policy.json ``` If successful, this command returns the policy's ARN. ``` { "PolicyARN": "arn:aws:autoscaling:us-east-1:012345678912:scalingPolicy:d1d72dfe-5fd3-464f-83cf-824f16cb88b7:resource/ecs/service/MyCluster/test:policyName/predictive-scaling-policy-example", "Alarms": [] } ``` # Evaluate your predictive scaling policies for Amazon ECS Evaluate your predictive scaling policies Before you use a predictive scaling policy to scale your services, review the recommendations and other data for your policy in the Amazon ECS console. This is important because you don't want a predictive scaling policy to scale your actual capacity until you know that its predictions are accurate. If the service is new, allow 24 hours to create the first forecast. When AWS creates a forecast, it uses historical data. If your service doesn't have much recent historical data yet, predictive scaling might temporarily backfill the forecast with aggregates created from the currently available historical aggregates. Forecasts are backfilled for up to two weeks before a policy's creation date. ## View your predictive scaling recommendations View your recommendations For effective analysis, service auto scaling should have at least two predictive scaling policies to compare. (However, you can still review the findings for a single policy.) When you create multiple policies, you can evaluate a policy that uses one metric against a policy that uses a different metric. You can also evaluate the impact of different target value and metric combinations. After the predictive scaling policies are created, Amazon ECS immediately starts evaluating which policy would do a better job of scaling your group. **To view your recommendations in the Amazon ECS console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, choose the service. The service details page appears. 1. Choose **Service auto scaling**. 1. Choose the predictive scaling policy, and then choose **Actions**, **Predictive Scaling**, **View recommendation**. You can view details about a policy along with our recommendation. The recommendation tells you whether the predictive scaling policy does a better job than not using it. If you're unsure whether a predictive scaling policy is appropriate for your group, review the **Availability impact** and **Cost impact** columns to choose the right policy. The information for each column tells you what the impact of the policy is. + **Availability impact**: Describes whether the policy would avoid negative impact to availability by provisioning enough tasks to handle the workload, compared to not using the policy. + **Cost impact**: Describes whether the policy would avoid negative impact on your costs by not over-provisioning tasks, compared to not using the policy. By over-provisioning too much, your services are underutilized or idle, which only adds to the cost impact. If you have multiple policies, then a **Best prediction** tag displays next to the name of the policy that gives the most availability benefits at lower cost. More weight is given to availability impact. 1. (Optional) To select the desired time period for recommendation results, choose your preferred value from the **Evaluation period** dropdown: **2 days**, **1 week**, or **2 weeks**. By default, the evaluation period is the last two weeks. A longer evaluation period provides more data points to the recommendation results. However, adding more data points might not improve the results if your load patterns have changed, such as after a period of exceptional demand. In this case, you can get a more focused recommendation by looking at more recent data. **Note** Recommendations are generated only for policies that are in **Forecast only** mode. The recommendations feature works better when a policy is in the **Forecast only** mode throughout the evaluation period. If you start a policy in **Forecast and scale** mode and switch it to **Forecast only** mode later, the findings for that policy are likely to be biased. This is because the policy has already contributed toward the actual capacity. ## Review predictive scaling monitoring graphs Review monitoring graphs In the console, you can review the forecast of the previous days, weeks, or months to visualize how well the policy performs over time. You can also use this information to evaluate the accuracy of predictions when deciding whether to let a policy scale your actual number of tasks. **To review predictive scaling monitoring graphs in the Amazon ECS console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, choose the service. The service details page appears. 1. Choose **Service auto scaling**. 1. Choose the predictive scaling policy, and then choose **Actions**, **Predictive Scaling**, **View Graph**. 1. In the **Monitoring** section, you can view your policy's past and future forecasts for load and capacity against actual values. The **Load** graph shows load forecast and actual values for the load metric that you chose. The **Capacity** graph shows the number of tasks predicted by the policy. It also includes the actual number of tasks launched. The vertical line separates historical values from future forecasts. These graphs become available shortly after the policy is created. 1. (Optional) To change the amount of historical data shown in the chart, choose your preferred value from the **Evaluation period** dropdown at the top of the page. The evaluation period does not transform the data on this page in any way. It only changes the amount of historical data shown. **Compare data in the **Load** graph** Each horizontal line represents a different set of data points reported in one-hour intervals: 1. **Actual observed load** uses the SUM statistic for your chosen load metric to show the total hourly load in the past. 1. **Load predicted by the policy** shows the hourly load prediction. This prediction is based on the previous two weeks of actual load observations. **Compare data in the **Capacity** graph** Each horizontal line represents a different set of data points reported in one-hour intervals: 1. **Actual observed number of tasks** shows your Amazon ECS service actual capacity in the past, which depends on your other scaling policies and minimum group size in effect for the selected time period. 1. **Capacity predicted by the policy** shows the baseline capacity that you can expect to have at the beginning of each hour when the policy is in **Forecast and scale** mode. 1. **Inferred required number of tasks** shows the ideal number of tasks in your service to maintain the scaling metric at the target value you chose. 1. **Minimum number of tasks** shows the minimum number of tasks in your service. 1. **Maximum capacity** shows the maximum number of tasks in your service. For the purpose of calculating the inferred required capacity, we begin by assuming that each task is equally utilized at a specified target value. In practice, the number of tasks are not equally utilized. By assuming that utilization is uniformly spread between tasks, however, we can make a likelihood estimate of the amount of capacity that is needed. The requirement for thenumber of tasks is then calculated to be inversely proportional to the scaling metric that you used for your predictive scaling policy. In other words, as the number of tasks increase, the scaling metric decreases at the same rate. For example, if the number of tasks doubles, the scaling metric must decrease by half. The formula for the inferred required capacity: `sum of (actualServiceUnits*scalingMetricValue)/(targetUtilization)` For example, we take the `actualServiceUnits` (`10`) and the `scalingMetricValue` (`30`) for a given hour. We then take the `targetUtilization` that you specified in your predictive scaling policy (`60`) and calculate the inferred required capacity for the same hour. This returns a value of `5`. This means that five is the inferred amount of capacity required to maintain capacity in direct inverse proportion to the target value of the scaling metric. **Note** Various levers are available for you to adjust and improve the cost savings and availability of your application. You use predictive scaling for the baseline capacity and dynamic scaling to handle additional capacity. Dynamic scaling works independently from predictive scaling, scaling in and out based on current utilization. First, Amazon ECS calculates the recommended number of tasks for each non-scheduled scaling policy. Then, it scales based on the policy that provides the largest number of tasks. To allow scale in to occur when the load decreases, your service should always have at least one dynamic scaling policy with the scale-in portion enabled. You can improve scaling performance by making sure that your minimum and maximum capacity are not too restrictive. A policy with a recommended number of tasks that does not fall within the minimum and maximum capacity range will be prevented from scaling in and out. # Monitor predictive scaling metrics for Amazon ECS with CloudWatch Predictive auto scaling monitoring with CloudWatch You can use Amazon CloudWatch to monitor your data for predictive scaling. A predictive scaling policy collects data that is used to forecast your future load. The data collected is automatically stored in CloudWatch at regular intervals and can be used to visualize how well the policy performs over time. You can also create CloudWatch alarms to notify you when performance indicators change beyond the limits that you defined. ## Visualize historical forecast data Visualize historical forecast data Load forecast data for a predictive scaling policy can be viewed in CloudWatch and can be useful when visualizing forecasts against other CloudWatch metrics in a single graph. You can also see trends over time by viewing a broader time range. You can access up to 15 months of historical metrics to get a better perspective on how your policy is performing. **To view historical forecast data using the CloudWatch console** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, choose **Metrics** and then **All metrics**. 1. Choose the **Application Auto Scaling** metric namespace. 1. Choose **Predictive Scaling Load Forecasts**. 1. In the search field, enter the name of the predictive scaling policy or the name of the Amazon ECS service group, and then press Enter to filter the results. 1. To graph a metric, select the check box next to the metric. To change the name of the graph, choose the pencil icon. To change the time range, select one of the predefined values or choose **custom**. For more information, see [Graphing a metric](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_a_metric.html) in the *Amazon CloudWatch User Guide*. 1. To change the statistic, choose the **Graphed metrics** tab. Choose the column heading or an individual value, and then choose a different statistic. Although you can choose any statistic for each metric, not all statistics are useful for **PredictiveScalingLoadForecast** metrics. For example, the **Average**, **Minimum**, and **Maximum** statistics are useful, but the **Sum** statistic is not. 1. To add another metric to the graph, under **Browse**, choose **All**, find the specific metric, and then select the check box next to it. You can add up to 10 metrics. 1. (Optional) To add the graph to a CloudWatch dashboard, choose **Actions**, **Add to dashboard**. ## Create accuracy metrics using metric math Create accuracy metrics With metric math, you can query multiple CloudWatch metrics and use math expressions to create new time series based on these metrics. You can visualize the resulting time series on the CloudWatch console and add them to dashboards. For more information about metric math, see [Using metric math](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html) in the *Amazon CloudWatch User Guide*. Using metric math, you can graph the data that service auto scaling generates for predictive scaling in different ways. This helps you monitor policy performance over time, and helps you understand whether your combination of metrics can be improved. For example, you can use a metric math expression to monitor the [mean absolute percentage error](https://en.wikipedia.org/wiki/Mean_absolute_percentage_error) (MAPE). The MAPE metric helps monitor the difference between the forecasted values and the actual values observed during a given forecast window. Changes in the value of MAPE can indicate whether the policy's performance is degrading over time as the nature of your application changes. An increase in MAPE signals a wider gap between the forecasted values and the actual values. **Example: Metric math expression** To get started with this type of graph, you can create a metric math expression like the one shown in the following example. Instead of a single metric, there is an array of metric data query structures for `MetricDataQueries`. Each item in `MetricDataQueries` gets a metric or performs a math expression. The first item, `e1`, is the math expression. The designated expression sets the `ReturnData` parameter to `true`, which ultimately produces a single time series. For all other metrics, the `ReturnData` value is `false`. In the example, the designated expression uses the actual and forecasted values as input and returns the new metric (MAPE). `m1` is the CloudWatch metric that contains the actual load values (assuming CPU utilization is the load metric that was originally specified for the policy named `my-predictive-scaling-policy`). `m2` is the CloudWatch metric that contains the forecasted load values. The math syntax for the MAPE metric is as follows: *Average of (abs ((Actual - Forecast)/(Actual)))* ### Visualize your accuracy metrics and set alarms To visualize the accuracy metric data, select the **Metrics** tab in the CloudWatch console. You can graph the data from there. For more information, see [Adding a math expression to a CloudWatch graph](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html#adding-metrics-expression-console) in the *Amazon CloudWatch User Guide*. You can also set an alarm on a metric that you're monitoring from the **Metrics** section. While on the **Graphed metrics** tab, select the **Create alarm** icon under the **Actions** column. The **Create alarm** icon is represented as a small bell. For more information and notification options, see [Creating a CloudWatch alarm based on a metric math expression](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Create-alarm-on-metric-math-expression.html) and [Notifying users on alarm changes](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Notify_Users_Alarm_Changes.html) in the *Amazon CloudWatch User Guide*. Alternatively, you can use [GetMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricData.html) and [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) to perform calculations using metric math and create alarms based on the output. # Use scheduled actions to override forecast values for Amazon ECS Override the forecast Sometimes, you might have additional information about your future application requirements that the forecast calculation is unable to take into account. For example, forecast calculations might underestimate the tasks needed for an upcoming marketing event. You can use scheduled actions to temporarily override the forecast during future time periods. The scheduled actions can run on a recurring basis, or at a specific date and time when there are one-time demand fluctuations. For example, you can create a scheduled action with a higher number of tasks than what is forecasted. At runtime, Amazon ECS updates the minimum number of tasks in your service. Because predictive scaling optimizes for the number of tasks, a scheduled action with a minimum number of tasks that is higher than the forecast values is honored. This prevents the number of tasks from being less than expected. To stop overriding the forecast, use a second scheduled action to return the minimum number of tasks to its original setting. The following procedure outlines the steps for overriding the forecast during future time periods. **Topics** + [ ## Step 1: (Optional) Analyze time series data ](#analyzing-time-series-data) + [ ## Step 2: Create two scheduled actions ](#scheduling-capacity) **Important** This topic assumes that you are trying to override the forecast to scale to a higher capacity than what is forecasted. If you need to temporarily decrease the number of tasks without interference from a predictive scaling policy, use *forecast only* mode instead. While in forecast only mode, predictive scaling will continue to generate forecasts, but it will not automatically increase the number of tasks. You can then monitor resource utilization and manually decrease the number of tasks as needed. ## Step 1: (Optional) Analyze time series data Start by analyzing the forecast time series data. This is an optional step, but it is helpful if you want to understand the details of the forecast. 1. **Retrieve the forecast** After the forecast is created, you can query for a specific time period in the forecast. The goal of the query is to get a complete view of the time series data for a specific time period. Your query can include up to two days of future forecast data. If you have been using predictive scaling for a while, you can also access your past forecast data. However, the maximum time duration between the start and end time is 30 days. To get the forecast using the [get-predictive-scaling-forecast](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/get-predictive-scaling-forecast.html) AWS CLI command, provide the following parameters in the command: + Enter the name of the cluster name in the `resource-id` parameter. + Enter the name of the policy in the `--policy-name` parameter. + Enter the start time in the `--start-time` parameter to return only forecast data for after or at the specified time. + Enter the end time in the `--end-time` parameter to return only forecast data for before the specified time. ``` aws application-autoscaling get-predictive-scaling-forecast \ --service-namespace ecs \ --resource-id service/MyCluster/test \ --policy-name cpu40-predictive-scaling-policy \ --scalable-dimension ecs:service:DesiredCount \ --start-time "2021-05-19T17:00:00Z" \ --end-time "2021-05-19T23:00:00Z" ``` If successful, the command returns data similar to the following example. ``` { "LoadForecast": [ { "Timestamps": [ "2021-05-19T17:00:00+00:00", "2021-05-19T18:00:00+00:00", "2021-05-19T19:00:00+00:00", "2021-05-19T20:00:00+00:00", "2021-05-19T21:00:00+00:00", "2021-05-19T22:00:00+00:00", "2021-05-19T23:00:00+00:00" ], "Values": [ 153.0655799339254, 128.8288551285919, 107.1179447150675, 197.3601844551528, 626.4039934516954, 596.9441277518481, 677.9675713779869 ], "MetricSpecification": { "TargetValue": 40.0, "PredefinedMetricPairSpecification": { "PredefinedMetricType": "ASGCPUUtilization" } } } ], "CapacityForecast": { "Timestamps": [ "2021-05-19T17:00:00+00:00", "2021-05-19T18:00:00+00:00", "2021-05-19T19:00:00+00:00", "2021-05-19T20:00:00+00:00", "2021-05-19T21:00:00+00:00", "2021-05-19T22:00:00+00:00", "2021-05-19T23:00:00+00:00" ], "Values": [ 2.0, 2.0, 2.0, 2.0, 4.0, 4.0, 4.0 ] }, "UpdateTime": "2021-05-19T01:52:50.118000+00:00" } ``` The response includes two forecasts: `LoadForecast` and `CapacityForecast`. `LoadForecast` shows the hourly load forecast. `CapacityForecast` shows forecast values for the capacity that is needed on an hourly basis to handle the forecasted load while maintaining a `TargetValue` of 40.0 (40% average CPU utilization). 1. **Identify the target time period** Identify the hour or hours when the one-time demand fluctuation should take place. Remember that dates and times shown in the forecast are in UTC. ## Step 2: Create two scheduled actions Next, create two scheduled actions for a specific time period when your application will have a higher than forecasted load. For example, if you have a marketing event that will drive traffic to your site for a limited period of time, you can schedule a one-time action to update the minimum capacity when it starts. Then, schedule another action to return the minimum capacity to the original setting when the event ends. 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, and then choose the service. The service details page appears. 1. Choose **Service Auto Scaling**. The policies page appears. 1. Choose **Scheduled actions**, and then choose **Create**. The **Create Schedule action** page appears. 1. For **Action name**, enter a unique name. 1. For **Time zone**, choose a time zone. All of the time zones listed are from the IANA Time Zone database. For more information, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). 1. For **Start time**, enter the **Date** and **Time** the action starts. 1. For **Recurrence**, choose **Once**. 1. Under **Task adjustments**, For Minimum, enter a value less than or equal to the maximum number of tasks.. 1. Choose **Create scheduled action**. The policies page appears. 1. Configure a second scheduled action to return the minimum number of tasks to the original setting at the end of the event. Predictive scaling can scale the number of tasks only when the value you set for **Minimum** is lower than the forecast values. **To create two scheduled actions for one-time events (AWS CLI)** To use the AWS CLI to create the scheduled actions, use the [put-scheduled-update-group-action](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/put-scheduled-update-group-action.html) command. For example, let's define a schedule that maintains a minimum capacity of three instances on May 19 at 5:00 PM for eight hours. The following commands show how to implement this scenario. The first [put-scheduled-update-group-action](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/put-scheduled-update-group-action.html) command instructs Amazon EC2 Auto Scaling to update the minimum capacity of the specified Auto Scaling group at 5:00 PM UTC on May 19, 2021. ``` aws autoscaling put-scheduled-update-group-action --scheduled-action-name my-event-start \ --auto-scaling-group-name my-asg --start-time "2021-05-19T17:00:00Z" --minimum-capacity 3 ``` The second command instructs Amazon EC2 Auto Scaling to set the group's minimum capacity to one at 1:00 AM UTC on May 20, 2021. ``` aws autoscaling put-scheduled-update-group-action --scheduled-action-name my-event-end \ --auto-scaling-group-name my-asg --start-time "2021-05-20T01:00:00Z" --minimum-capacity 1 ``` After you add these scheduled actions to the Auto Scaling group, Amazon EC2 Auto Scaling does the following: + At 5:00 PM UTC on May 19, 2021, the first scheduled action runs. If the group currently has fewer than three instances, the group scales out to three instances. During this time and for the next eight hours, Amazon EC2 Auto Scaling can continue to scale out if the predicted capacity is higher than the actual capacity or if there is a dynamic scaling policy in effect. + At 1:00 AM UTC on May 20, 2021, the second scheduled action runs. This returns the minimum capacity to its original setting at the end of the event. ### Scaling based on recurring schedules To override the forecast for the same time period every week, create two scheduled actions and provide the time and date logic using a cron expression. The cron expression format consists of five fields separated by spaces: [Minute] [Hour] [Day\$1of\$1Month] [Month\$1of\$1Year] [Day\$1of\$1Week]. Fields can contain any allowed values, including special characters. For example, the following cron expression runs the action every Tuesday at 6:30 AM. The asterisk is used as a wildcard to match all values for a field. ``` 30 6 * * 2 ``` ### See also For more information about how to manage scheduled actions, see [Use scheduled actions to scale Amazon ECS services](service-autoscaling-schedulescaling.md). # Advanced predictive scaling policy using custom metrics for Amazon ECS Use custom metrics You can use predefined or custom metrics in a predictive scaling policy. Custom metrics are useful when the predefined metrics, such as CPU, memory, etc) aren't enough to sufficiently describe your application load. When creating a predictive scaling policy with custom metrics, you can specify other CloudWatch metrics provided by AWS. Alternatively, you can specify metrics that you define and publish yourself. You can also use metric math to aggregate and transform existing metrics into a new time series that AWS doesn't automatically track. An example is combining values in your data by calculating new sums or averages called *aggregating*. The resulting data is called an *aggregate*. The following section contains best practices and examples of how to construct the JSON structure for the policy. ## Prerequisites To add custom metrics to your predictive scaling policy, you must have `cloudwatch:GetMetricData` permissions. To specify your own metrics instead of the metrics that AWS provides, you must first publish your metrics to CloudWatch. For more information, see [Publishing custom metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/publishingMetrics.html) in the *Amazon CloudWatch User Guide*. If you publish your own metrics, make sure to publish the data points at a minimum frequency of five minutes. Data points are retrieved from CloudWatch based on the length of the period that it needs. For example, the load metric specification uses hourly metrics to measure the load on your application. CloudWatch uses your published metric data to provide a single data value for any one-hour period by aggregating all data points with timestamps that fall within each one-hour period. ## Best practices The following best practices can help you use custom metrics more effectively: + The most useful metric for the load metric specification is a metric that represents the load on an Auto Scaling group as a whole. + The most useful metric for the scaling metric specification to scale by is an average throughput or utilization per task metric. + The target utilization must match the type of scaling metric. For a policy configuration that uses CPU utilization, this is a target percentage, for example. + If these recommendations are not followed, the forecasted future values of the time series will probably be incorrect. To validate that the data is correct, you can view the forecasted values in the console. Alternatively, after you create your predictive scaling policy, inspect the `LoadForecast` objects returned by a call to the [GetPredictiveScalingForecast](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_GetPredictiveScalingForecast.html) API. + We strongly recommend that you configure predictive scaling in forecast only mode so that you can evaluate the forecast before predictive scaling starts actively scaling. ## Limitations + You can query data points of up to 10 metrics in one metric specification. + For the purposes of this limit, one expression counts as one metric. ## Troubleshooting a predictive scaling policy with custom metrics Considerations for custom metrics If an issue occurs while using custom metrics, we recommend that you do the following: + If you encounter an issue in a blue/green deployment while using a search expression, make sure you created an search expression that's looking for a partial match and not an exact match. You should also check that the query is only finding Auto Scaling groups running in the specific application. For more information about the search expression syntax, see [CloudWatch search expression syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/search-expression-syntax.html) in the *Amazon CloudWatch User Guide*. + The [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html) command validates an expression when you create your scaling policy. However, there's a possibility that this command might fail to identify the exact cause of the detected errors. To fix the issues, troubleshoot the errors that you receive in a response from a request to the [get-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-data.html) command. You can also troubleshoot the expression from the CloudWatch console. + You must specify `false` for `ReturnData` if `MetricDataQueries` specifies the SEARCH() function on its own without a math function like SUM(). This is because search expressions might return multiple time series, and a metric specification based on an expression can return only one time series. + All metrics involved in a search expression should be of the same resolution. # Constructing the JSON for predictive scaling custom metrics with Amazon ECS The following section contains examples for how to configure predictive scaling to query data from CloudWatch. There are two different methods to configure this option, and the method that you choose affects which format you use to construct the JSON for your predictive scaling policy. When you use metric math, the format of the JSON varies further based on the metric math being performed. 1. To create a policy that gets data directly from other CloudWatch metrics provided by AWS or metrics that you publish to CloudWatch, see [Example predictive scaling policy with custom load and scaling metrics using the AWS CLI](#predictive-scaling-custom-metrics-example1). ## Example predictive scaling policy with custom load and scaling metrics using the AWS CLI To create a predictive scaling policy with custom load and scaling metrics with the AWS CLI, store the arguments for `--predictive-scaling-configuration` in a JSON file named `config.json`. You start adding custom metrics by replacing the replaceable values in the following example with those of your metrics and your target utilization. ``` { "MetricSpecifications": [ { "TargetValue": 50, "CustomizedScalingMetricSpecification": { "MetricDataQueries": [ { "Id": "scaling_metric", "MetricStat": { "Metric": { "MetricName": "MyUtilizationMetric", "Namespace": "MyNameSpace", "Dimensions": [ { "Name": "MyOptionalMetricDimensionName", "Value": "MyOptionalMetricDimensionValue" } ] }, "Stat": "Average" } } ] }, "CustomizedLoadMetricSpecification": { "MetricDataQueries": [ { "Id": "load_metric", "MetricStat": { "Metric": { "MetricName": "MyLoadMetric", "Namespace": "MyNameSpace", "Dimensions": [ { "Name": "MyOptionalMetricDimensionName", "Value": "MyOptionalMetricDimensionValue" } ] }, "Stat": "Sum" } } ] } } ] } ``` For more information, see [MetricDataQuery](https://docs.aws.amazon.com/autoscaling/ec2/APIReference/API_MetricDataQuery.html) in the *Amazon EC2 Auto Scaling API Reference*. **Note** Following are some additional resources that can help you find metric names, namespaces, dimensions, and statistics for CloudWatch metrics: For information about the available metrics for AWS services, see [AWS services that publish CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html) in the *Amazon CloudWatch User Guide*. To get the exact metric name, namespace, and dimensions (if applicable) for a CloudWatch metric with the AWS CLI, see [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html). To create this policy, run the [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/put-scaling-policy.html) command using the JSON file as input, as demonstrated in the following example. ``` aws application-autoscaling put-scaling-policy --policy-name my-predictive-scaling-policy \ --auto-scaling-group-name my-asg --policy-type PredictiveScaling \ --predictive-scaling-configuration file://config.json ``` If successful, this command returns the policy's Amazon Resource Name (ARN). ``` { "PolicyARN": "arn:aws:autoscaling:region:account-id:scalingPolicy:2f4f5048-d8a8-4d14-b13a-d1905620f345:autoScalingGroupName/my-asg:policyName/my-predictive-scaling-policy", "Alarms": [] } ``` # Use metric math expressions The following section provides information about using metric math with predictive scaling policies in your policy. ## Understand metric math If all you want to do is aggregate existing metric data, CloudWatch metric math saves you the effort and cost of publishing another metric to CloudWatch. You can use any metric that AWS provides, and you can also use metrics that you define as part of your applications. For more information, see [Using metric math](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html) in the *Amazon CloudWatch User Guide*. If you choose to use a metric math expression in your predictive scaling policy, consider the following points: + Metric math operations use the data points of the unique combination of metric name, namespace, and dimension keys/value pairs of metrics. + You can use any arithmetic operator (\$1 - \$1 / ^), statistical function (such as AVG or SUM), or other function that CloudWatch supports. + You can use both metrics and the results of other math expressions in the formulas of the math expression. + Your metric math expressions can be made up of different aggregations. However, it's a best practice for the final aggregation result to use `Average` for the scaling metric and `Sum` for the load metric. + Any expressions used in a metric specification must eventually return a single time series. To use metric math, do the following: + Choose one or more CloudWatch metrics. Then, create the expression. For more information, see [Using metric math](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html) in the *Amazon CloudWatch User Guide*. + Verify that the metric math expression is valid by using the CloudWatch console or the CloudWatch [GetMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricData.html) API. ## Example predictive scaling policy that combines metrics using metric math (AWS CLI) Sometimes, instead of specifying the metric directly, you might need to first process its data in some way. For example, you might have an application that pulls work from an Amazon SQS queue, and you might want to use the number of items in the queue as criteria for predictive scaling. The number of messages in the queue does not solely define the number of instances that you need. Therefore, more work is needed to create a metric that can be used to calculate the backlog per instance. The following is an example predictive scaling policy for this scenario. It specifies scaling and load metrics that are based on the Amazon SQS `ApproximateNumberOfMessagesVisible` metric, which is the number of messages available for retrieval from the queue. It also uses the Amazon EC2 Auto Scaling `GroupInServiceInstances` metric and a math expression to calculate the backlog per instance for the scaling metric. ``` aws application-autoscaling put-scaling-policy --policy-name my-sqs-custom-metrics-policy \ --policy-type PredictiveScaling \ --predictive-scaling-configuration file://config.json --service-namespace ecs \ --resource-id service/MyCluster/test \ "MetricSpecifications": [ { "TargetValue": 100, "CustomizedScalingMetricSpecification": { "MetricDataQueries": [ { "Label": "Get the queue size (the number of messages waiting to be processed)", "Id": "queue_size", "MetricStat": { "Metric": { "MetricName": "ApproximateNumberOfMessagesVisible", "Namespace": "AWS/SQS", "Dimensions": [ { "Name": "QueueName", "Value": "my-queue" } ] }, "Stat": "Sum" }, "ReturnData": false }, { "Label": "Get the group size (the number of running instances)", "Id": "running_capacity", "MetricStat": { "Metric": { "MetricName": "GroupInServiceInstances", "Namespace": "AWS/AutoScaling", "Dimensions": [ { "Name": "AutoScalingGroupName", "Value": "my-asg" } ] }, "Stat": "Sum" }, "ReturnData": false }, { "Label": "Calculate the backlog per instance", "Id": "scaling_metric", "Expression": "queue_size / running_capacity", "ReturnData": true } ] }, "CustomizedLoadMetricSpecification": { "MetricDataQueries": [ { "Id": "load_metric", "MetricStat": { "Metric": { "MetricName": "ApproximateNumberOfMessagesVisible", "Namespace": "AWS/SQS", "Dimensions": [ { "Name": "QueueName", "Value": "my-queue" } ], }, "Stat": "Sum" }, "ReturnData": true } ] } } ] } ``` The example returns the policy's ARN. ``` { "PolicyARN": "arn:aws:autoscaling:region:account-id:scalingPolicy:2f4f5048-d8a8-4d14-b13a-d1905620f345:autoScalingGroupName/my-asg:policyName/my-sqs-custom-metrics-policy", "Alarms": [] } ```