# Automatically manage Amazon ECS capacity with cluster auto scaling Amazon ECS can manage the scaling of Amazon EC2 instances that are registered to your cluster. This is referred to as Amazon ECS *cluster auto scaling*. You turn on managed scaling when you create the Amazon ECS Auto Scaling group capacity provider. Then, you set a target percentage (the `targetCapacity`) for the instance utilization in this Auto Scaling group. Amazon ECS creates two custom CloudWatch metrics and a target tracking scaling policy for your Auto Scaling group. Amazon ECS then manages the scale-in and scale-out actions based on the resource utilization that your tasks use. For each Auto Scaling group capacity provider that's associated with a cluster, Amazon ECS creates and manages the following resources: + A low metric value CloudWatch alarm + A high metric value CloudWatch alarm + A target tracking scaling policy **Note** Amazon ECS creates the target tracking scaling policy and attaches it to the Auto Scaling group. To update the target tracking scaling policy, update the capacity provider managed scaling settings, rather than updating the scaling policy directly. When you turn off managed scaling or disassociate the capacity provider from a cluster, Amazon ECS removes both CloudWatch metrics and the target tracking scaling policy resources. Amazon ECS uses the following metrics to determine what actions to take: `CapacityProviderReservation` The percent of container instances in use for a specific capacity provider. Amazon ECS generates this metric. Amazon ECS sets the `CapacityProviderReservation` value to a number between 0-100. Amazon ECS uses the following formula to represent the ratio of how much capacity remains in the Auto Scaling group. Then, Amazon ECS publishes the metric to CloudWatch. For more information about how the metric is calculated, see [ Deep Dive on Amazon ECS Cluster Auto Scaling](https://aws.amazon.com/blogs/containers/deep-dive-on-amazon-ecs-cluster-auto-scaling/). ``` CapacityProviderReservation = (number of instances needed) / (number of running instances) x 100 ``` `DesiredCapacity` The amount of capacity for the Auto Scaling group. This metric isn't published to CloudWatch. Amazon ECS publishes the `CapacityProviderReservation` metric to CloudWatch in the `AWS/ECS/ManagedScaling` namespace. The `CapacityProviderReservation` metric causes one of the following actions to occur: **The `CapacityProviderReservation` value equals `targetCapacity`** The Auto Scaling group doesn't need to scale in or scale out. The target utilization percentage has been reached. **The `CapacityProviderReservation` value is greater than `targetCapacity`** There are more tasks using a higher percentage of the capacity than your `targetCapacity` percentage. The increased value of the `CapacityProviderReservation` metric causes the associated CloudWatch alarm to act. This alarm updates the `DesiredCapacity` value for the Auto Scaling group. The Auto Scaling group uses this value to launch EC2 instances, and then register them with the cluster. When the `targetCapacity` is the default value of 100 %, the new tasks are in the `PENDING` state during the scale-out because there is no available capacity on the instances to run the tasks. After the new instances register with ECS, these tasks will start on the new instances. **The `CapacityProviderReservation` value is less than `targetCapacity`** There are less tasks using a lower percentage of the capacity than your `targetCapacity` percentage and there is at least one instance that can be terminated. The decreased value of the `CapacityProviderReservation` metric causes the associated CloudWatch alarm to act. This alarm updates the `DesiredCapacity` value for the Auto Scaling group. The Auto Scaling group uses this value to terminate EC2 container instances, and then deregister them from the cluster. The Auto Scaling group follows the group termination policy to determine which instances it terminates first during scale-in events. Additionally it avoids instances with the instance scale-in protection setting turned on. Cluster auto scaling can manage which instances have the instance scale-in protection setting if you turn on managed termination protection. For more information about managed termination protection, see [Control the instances Amazon ECS terminates](managed-termination-protection.md). For more information about how Auto Scaling groups terminate instances, see [Control which Auto Scaling instances terminate during scale in](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-instance-protection.html) in the *Amazon EC2 Auto Scaling User Guide*. Consider the following when using cluster auto scaling: + Don't change or manage the desired capacity for the Auto Scaling group that's associated with a capacity provider with any scaling policies other than the one Amazon ECS manages. + When Amazon ECS scales out from 0 instances, it automatically launches 2 instances. + Amazon ECS uses the `AWSServiceRoleForECS` service-linked IAM role for the permissions that it requires to call AWS Auto Scaling on your behalf. For more information, see [Using service-linked roles for Amazon ECS](using-service-linked-roles.md). + When using capacity providers with Auto Scaling groups, the user, group, or role that creates the capacity providers requires the `autoscaling:CreateOrUpdateTags` permission. This is because Amazon ECS adds a tag to the Auto Scaling group when it associates it with the capacity provider. **Important** Make sure any tooling that you use doesn't remove the `AmazonECSManaged` tag from the Auto Scaling group. If this tag is removed, Amazon ECS can't manage the scaling. + Cluster auto scaling doesn't modify the **MinimumCapacity** or **MaximumCapacity** for the group. For the group to scale out, the value for **MaximumCapacity** must be greater than zero. + When Auto Scaling (managed scaling) is turned on, a capacity provider can only be connected to one cluster at the same time. If your capacity provider has managed scaling turned off, you can associate it with multiple clusters. + When managed scaling is turned off, the capacity provider doesn't scale in or scale out. You can use a capacity provider strategy to balance your tasks between capacity providers. + The `binpack` strategy is the most efficient strategy in terms of capacity. + When the target capacity is less than 100%, within the placement strategy, the `binpack` strategy must have a higher order than the `spread` strategy. This prevents the capacity provider from scaling out until each task has a dedicated instance or the limit is reached. ## Turn on cluster auto scaling You can turn on cluster auto scaling by using the Console or the AWS CLI. When you create a cluster that uses EC2 capacity providers using the console, Amazon ECS creates an Auto Scaling group on your behalf and sets the target capacity. For more information, see [Creating an Amazon ECS cluster for Amazon EC2 workloads](create-ec2-cluster-console-v2.md). You can also create an Auto Scaling group, and then assign it to a cluster. For more information, see [Updating an Amazon ECS capacity provider](update-capacity-provider-console-v2.md). When you use the AWS CLI, after you create the cluster 1. Before you create the capacity provider, you need to create an Auto Scaling group. For more information, see[ Auto Scaling groups](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html) in the *Amazon EC2 Auto Scaling User Guide*. 1. Use `put-cluster-capacity-providers` to modify the cluster capacity provider. For more information, see [Turning on Amazon ECS cluster auto scaling](turn-on-cluster-auto-scaling.md). # Optimize Amazon ECS cluster auto scaling Customers who run Amazon ECS on Amazon EC2 can take advantage of cluster auto scaling to manage the scaling of Amazon EC2 Auto Scaling groups. With cluster auto scaling, you can configure Amazon ECS to scale your Auto Scaling group automatically, and just focus on running your tasks. Amazon ECS ensures the Auto Scaling group scales in and out as needed with no further intervention required. Amazon ECS capacity providers are used to manage the infrastructure in your cluster by ensuring there are enough container instances to meet the demands of your application. To learn how cluster auto scaling works under the hood, see [Deep Dive on Amazon ECS Cluster Auto Scaling](https://aws.amazon.com/blogs/containers/deep-dive-on-amazon-ecs-cluster-auto-scaling/). Cluster auto scaling relies on a CloudWatch based integration with Auto Scaling group for adjusting cluster capacity. Therefore it has inherent latency associated with + Publishing the CloudWatch metrics, + The time taken for the metric `CapacityProviderReservation` to breach CloudWatch alarms (both high and low) + The time taken by a newly launched Amazon EC2 instance to warm-up. You can take the following actions to make cluster auto scaling more responsive for faster deployments: ## Capacity provider step scaling sizes Amazon ECS capacity providers will grow/shrink the container instances to meet the demands of your application. The minimum number of instances that Amazon ECS will launch is set to 1 by default. This may add additional time to your deployments, if several instances are required for placing your pending tasks. You can increase the [https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ManagedScaling.html](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ManagedScaling.html) via the Amazon ECS API to increase the minimum number of instances that Amazon ECS scales in or out at a time. A [https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ManagedScaling.html](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ManagedScaling.html) that is too low can limit how many container instances are scaled in or out at a time, which can slow down your deployments. **Note** This configuration is currently only available via the [https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCapacityProvider.html](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCapacityProvider.html) or [https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateCapacityProvider.html](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateCapacityProvider.html) APIs. ## Instance warm-up period The instance warm-up period is the period of time after which a newly launched Amazon EC2 instance can contribute to CloudWatch metrics for the Auto Scaling group. After the specified warm-up period expires, the instance is counted toward the aggregated metrics of the Auto Scaling group, and cluster auto scaling proceeds with its next iteration of calculations to estimate the number instances required. The default value for [https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ManagedScaling.html#ECS-Type-ManagedScaling-instanceWarmupPeriod](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ManagedScaling.html#ECS-Type-ManagedScaling-instanceWarmupPeriod) is 300 seconds, which you can configure to a lower value via the [https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCapacityProvider.html](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCapacityProvider.html) or [https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateCapacityProvider.html](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateCapacityProvider.html) APIs for more responsive scaling. We recommend that you set the value to greater than 60 seconds so that you can avoid over-provisioning. ## Spare capacity If your capacity provider has no container instances available for placing tasks, then it needs to increase (scale out) cluster capacity by launching Amazon EC2 instances on the fly, and wait for them to boot up before it can launch containers on them. This can significantly lower the task launch rate. You have two options here. In this case, having spare Amazon EC2 capacity already launched and ready to run tasks will increase the effective task launch rate. You can use the `Target Capacity` configuration to indicate that you wish to maintain spare capacity in your clusters. For example, by setting `Target Capacity` at 80%, you indicate that your cluster needs 20% spare capacity at all times. This spare capacity can allow any standalone tasks to be immediately launched, ensuring task launches are not throttled. The trade-off for this approach is potential increased costs of keeping spare cluster capacity. An alternate approach you can consider is adding headroom to your service, not to the capacity provider. This means that instead of reducing `Target Capacity` configuration to launch spare capacity, you can increase the number of replicas in your service by modifying the target tracking scaling metric or the step scaling thresholds of the service auto scaling. Note that this approach will only be helpful for spiky workloads, but won't have an effect when you’re deploying new services and going from 0 to N tasks for the first time. For more information about the related scaling policies, see [Target Tracking Scaling Policies](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-autoscaling-targettracking.html) or [Step Scaling Policies](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-autoscaling-stepscaling.html) in the *Amazon Elastic Container Service Developer Guide*. # Amazon ECS managed scaling behavior When you have Auto Scaling group capacity providers that use managed scaling, Amazon ECS estimates the optimal number of instances to add to your cluster and uses the value to determine how many instances to request or release. ## Managed scale-out behavior Amazon ECS selects a capacity provider for each task by following the capacity provider strategy from the service, standalone task, or the cluster default. Amazon ECS follows the rest of these steps for a single capacity provider. Tasks without a capacity provider strategy are ignored by capacity providers. A pending task that doesn't have a capacity provider strategy won't cause any capacity provider to scale out. Tasks or services can't set a capacity provider strategy if that task or service sets a launch type. The following describes the scale-out behavior in more detail. + Group all of the provisioning tasks for this capacity provider so that each group has the same exact resource requirements. + When you use multiple instance types in an Auto Scaling group, the instance types in the Auto Scaling group are sorted by their parameters. These parameters include vCPU, memory, elastic network interfaces (ENIs), ports, and GPUs. The smallest and the largest instance types for each parameter are selected. For more information about how to choose the instance type, see [Amazon EC2 container instances for Amazon ECS](create-capacity.md). **Important** If a group of tasks have resource requirements that are greater than the smallest instance type in the Auto Scaling group, then that group of tasks can’t run with this capacity provider. The capacity provider doesn’t scale the Auto Scaling group. The tasks remain in the `PROVISIONING` state. To prevent tasks from staying in the `PROVISIONING` state, we recommend that you create separate Auto Scaling groups and capacity providers for different minimum resource requirements. When you run tasks or create services, only add capacity providers to the capacity provider strategy that can run the task on the smallest instance type in the Auto Scaling group. For other parameters, you can use placement constraints + For each group of tasks, Amazon ECS calculates the number of instances that are required to run the unplaced tasks. This calculation uses a `binpack` strategy. This strategy accounts for the vCPU, memory, elastic network interfaces (ENI), ports, and GPUs requirements of the tasks. It also accounts for the resource availability of the Amazon EC2 instances. The values for the largest instance types are treated as the maximum calculated instance count. The values for the smallest instance type are used as protection. If the smallest instance type can't run at least one instance of the task, the calculation considers the task as not compatible. As a result, the task is excluded from scale-out calculation. When all the tasks aren't compatible with the smallest instance type, cluster auto scaling stops and the `CapacityProviderReservation` value remains at the `targetCapacity` value. + Amazon ECS publishes the `CapacityProviderReservation` metric to CloudWatch with respect to the `minimumScalingStepSize` if either of the following is the case. + The maximum calculated instance count is less than the minimum scaling step size. + The lower value of either the `maximumScalingStepSize` or the maximum calculated instance count. + CloudWatch alarms use the `CapacityProviderReservation` metric for capacity providers. When the `CapacityProviderReservation` metric is greater than the `targetCapacity` value, alarms also increase the `DesiredCapacity` of the Auto Scaling group. The `targetCapacity` value is a capacity provider setting that's sent to the CloudWatch alarm during the cluster auto scaling activation phase. The default `targetCapacity` is 100%. + The Auto Scaling group launches additional EC2 instances. To prevent over-provisioning, Auto Scaling makes sure that recently launched EC2 instance capacity is stabilized before it launches new instances. Auto Scaling checks if all existing instances have passed the `instanceWarmupPeriod` (now minus the instance launch time). The scale-out is blocked for instances that are within the `instanceWarmupPeriod`. The default number of seconds for a newly launched instance to warm up is 300. For more information, see [Deep dive on Amazon ECS cluster auto scaling](https://aws.amazon.com/blogs/containers/deep-dive-on-amazon-ecs-cluster-auto-scaling/). ### Scale-out considerations Consider the following for the scale-out process: + Although there are multiple placement constraints, we recommend that you only use the `distinctInstance` task placement constraint. This prevents the scale-out process from stopping because you're using a placement constraint that's not compatible with the sampled instances. + Managed scaling works best if your Auto Scaling group uses the same or similar instance types. + When a scale-out process is required and there are no currently running container instances, Amazon ECS always scales-out to two instances initially, and then performs additional scale-out or scale-in processes. Any additional scale-out waits for the instance warmup period. For scale-in processes, Amazon ECS waits 15 minutes after a scale-out process before starting scale-in processes at all times. + The second scale-out step needs to wait until the `instanceWarmupPeriod` expires, which might affect the overall scale limit. If you need to reduce this time, make sure that `instanceWarmupPeriod` is large enough for the EC2 instance to launch and start the Amazon ECS agent (which prevents over provisioning). + Cluster auto scaling supports Launch Configuration, Launch Templates, and multiple instance types in the capacity provider Auto Scaling group. You can also use attribute-based instance type selection without multiple instances types. + When using an Auto Scaling group with On-Demand instances and multiple instance types or Spot Instances, place the larger instance types higher in the priority list and don't specify a weight. Specifying a weight isn't supported at this time. For more information, see [Auto Scaling groups with multiple instance types](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-mixed-instances-groups.html) in the *AWS Auto Scaling User Guide*. + Amazon ECS then launch either the `minimumScalingStepSize`, if the maximum calculated instance count is less than the minimum scaling step size, or the lower of either the `maximumScalingStepSize` or the maximum calculated instance count value. + If an Amazon ECS service or `run-task` launches a task and the capacity provider container instances don't have enough resources to start the task, then Amazon ECS limits the number of tasks with this status for each cluster and prevents any tasks from exceeding this limit. For more information, see [Amazon ECS service quotas](service-quotas.md). ## Managed scale-in behavior Amazon ECS monitors container instances for each capacity provider within a cluster. When a container instance isn't running any tasks, the container instance is considered empty and Amazon ECS starts the scale-in process. CloudWatch scale-in alarms require 15 data points (15 minutes) before the scale-in process for the Auto Scaling group starts. After the scale-in process starts until Amazon ECS needs to reduce the number of registered container instances, the Auto Scaling group sets the `DesireCapacity` value to be greater than one instance and less than 50% each minute. When Amazon ECS requests a scale-out (when `CapacityProviderReservation` is greater than 100) while a scale-in process is in progress, the scale-in process is stopped and starts from the beginning if required. The following describes the scale-in behavior in more detail: 1. Amazon ECS calculates the number of container instances that are empty. A container instance is considered empty even when daemon tasks are running. 1. Amazon ECS sets the `CapacityProviderReservation` value to a number between 0-100 that uses the following formula to represent the ratio of how big the Auto Scaling group needs to be relative to how big it actually is, expressed as a percentage. Then, Amazon ECS publishes the metric to CloudWatch. For more information about how the metric is calculated, see [ Deep Dive on Amazon ECS Cluster Auto Scaling](https://aws.amazon.com/blogs/containers/deep-dive-on-amazon-ecs-cluster-auto-scaling/) ``` CapacityProviderReservation = (number of instances needed) / (number of running instances) x 100 ``` 1. The `CapacityProviderReservation` metric generates a CloudWatch alarm. This alarm updates the `DesiredCapacity` value for the Auto Scaling group. Then, one of the following actions occurs: + If you don't use capacity provider managed termination, the Auto Scaling group selects EC2 instances using the Auto Scaling group termination policy and terminates the instances until the number of EC2 instances reaches the `DesiredCapacity`. The container instances are then deregistered from the cluster. + If all the container instances use managed termination protection, Amazon ECS removes the scale-in protection on the container instances that are empty. The Auto Scaling group will then be able to terminate the EC2 instances. The container instances are then deregistered from the cluster. # Control the instances Amazon ECS terminates **Important** You must turn on Auto Scaling *instance scale-in protection* on the Auto Scaling group to use the managed termination protection feature of cluster auto scaling. Managed termination protection allows cluster auto scaling to control which instances are terminated. When you used managed termination protection, Amazon ECS only terminates EC2 instances that don't have any running Amazon ECS tasks. Tasks that are run by a service that uses the `DAEMON` scheduling strategy are ignored and an instance can be terminated by cluster auto scaling even when the instance is running these tasks. This is because all of the instances in the cluster are running these tasks. Amazon ECS first turns on the *instance scale-in protection* option for the EC2 instances in the Auto Scaling group. Then, Amazon ECS places the tasks on the instances. When all non-daemon tasks are stopped on an instance, Amazon ECS initiates the scale-in process and turns off scale-in protection for the EC2 instance. The Auto Scaling group can then terminate the instance. Auto Scaling *instance scale-in protection* controls which EC2 instances can be terminated by Auto Scaling. Instances with the scale-in feature turned on can't be terminated during the scale-in process. For more information about Auto Scaling instance scale-in protection, see [Using instance scale-in protection](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-instance-protection.html) in the *Amazon EC2 Auto Scaling User Guide*. You can set the `targetCapacity` percentage so that you have spare capacity. This helps future tasks launch more quickly because the Auto Scaling group does not have to launch more instances. Amazon ECS uses the target capacity value to manage the CloudWatch metric that the service creates. Amazon ECS manages the CloudWatch metric. The Auto Scaling group is treated as a steady state so that no scaling action is required. The values can be from 0-100%. For example, to configure Amazon ECS to keep 10% free capacity on top of that used by Amazon ECS tasks, set the target capacity value to 90%. Consider the following when setting the `targetCapacity` value on a capacity provider. + A `targetCapacity` value of less than 100% represents the amount of free capacity (Amazon EC2 instances) that need to be present in the cluster. Free capacity means that there are no running tasks. + Placement constraints such as Availability Zones, without additional `binpack` forces Amazon ECS to eventually run one task for each instance, which might not be the desired behavior. You must turn on Auto Scaling instance scale-in protection on the Auto Scaling group to use managed termination protection. If you don't turn on scale-in protection, then turning on managed termination protection can lead to undesirable behavior. For example, you may have instances stuck in draining state. For more information, see [Using instance scale-in protection](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-instance-protection.html) in the *Amazon EC2 Auto Scaling User Guide*. When you use termination protection with a capacity provider, don't perform any manual actions, like detaching the instance, on the Auto Scaling group associated with the capacity provider. Manual actions can break the scale-in operation of the capacity provider. If you detach an instance from the Auto Scaling group, you need to also [deregister the detached instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deregister_container_instance.html) from the Amazon ECS cluster. # Updating managed termination protection for Amazon ECS capacity providers When you use managed termination protection, you need to update the setting for existing capacity providers. ## 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 page, chooset the **Infrastructure** tab. 1. Choose the capacity provider. 1. Choose **Update** to modify the capacity provider settings. 1. Under **Auto Scaling group settings**, toggle **Managed termination protection** to enable or disable the feature. 1. Choose **Update**. ## AWS CLI You can update a capacity provider's managed termination protection setting using the `update-capacity-provider` command: To enable managed termination protection: ``` aws ecs update-capacity-provider \ --name CapacityProviderName \ --auto-scaling-group-provider "managedScaling={status=ENABLED,targetCapacity=70,minimumScalingStepSize=1,maximumScalingStepSize=10},managedTerminationProtection=ENABLED" ``` To disable managed termination protection: ``` aws ecs update-capacity-provider \ --name CapacityProviderName \ --auto-scaling-group-provider "managedScaling={status=ENABLED,targetCapacity=70,minimumScalingStepSize=1,maximumScalingStepSize=10},managedTerminationProtection=DISABLED" ``` **Note** It might take a few minutes for the changes to take effect across your cluster. When enabling managed termination protection, instances that are already running tasks will be protected from scale-in events. When disabling managed termination protection, the protection flag will be removed from instances during the next ECS capacity provider management cycle. ## Console for running tasks 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 page, chooset the **Tasks** tab. 1. Choose the task. 1. Under **Configuration**, toggle **Managed termination protection** to enable or disable the feature. 1. Choose **Configure task scale-in protection**. The **Configure task scale-in protection** dialog box displays 1. Under **Task scale-in protection**, toggle **Turn on**. 1. For **Expires in minutes**, enter the number of minutes before task scale-in protection ends. 1. Choose **Update** # Turning on Amazon ECS cluster auto scaling You turn on cluster auto scaling so that Amazon ECS manages the scaling of Amazon EC2 instances that are registered to your cluster. If you want to use the console to turn on Cluster auto scaling, see see [Creating a capacity provider for Amazon ECS](create-capacity-provider-console-v2.md). Before you begin, create an Auto Scaling group and a capacity provider. For more information, see [Amazon ECS capacity providers for EC2 workloads](asg-capacity-providers.md). To turn on cluster auto scaling, you associate the capacity provider with the cluster, Then you turn on cluster auto scaling. 1. Use the `put-cluster-capacity-providers` command to associate one or more capacity providers with the cluster. To add the AWS Fargate capacity providers, include the `FARGATE` and `FARGATE_SPOT` capacity providers in the request. For more information, see `[put-cluster-capacity-providers](https://docs.aws.amazon.com/cli/latest/reference/ecs/put-cluster-capacity-providers.html)` in the *AWS CLI Command Reference*. ``` aws ecs put-cluster-capacity-providers \ --cluster ClusterName \ --capacity-providers CapacityProviderName FARGATE FARGATE_SPOT \ --default-capacity-provider-strategy capacityProvider=CapacityProvider,weight=1 ``` To add an Auto Scaling group for EC2, include the Auto Scaling group name in the request. For more information, see `[put-cluster-capacity-providers](https://docs.aws.amazon.com/cli/latest/reference/ecs/put-cluster-capacity-providers.html)` in the *AWS CLI Command Reference*. ``` aws ecs put-cluster-capacity-providers \ --cluster ClusterName \ --capacity-providers CapacityProviderName \ --default-capacity-provider-strategy capacityProvider=CapacityProvider,weight=1 ``` 1. Use the `describe-clusters` command to verify that the association was successful. For more information, see `[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-clusters.html)` in the *AWS CLI Command Reference*. ``` aws ecs describe-clusters \ --cluster ClusterName \ --include ATTACHMENTS ``` 1. Use the `update-capacity-provider` command to turn on managed auto scaling for the capacity provider. For more information, see `[update-capacity-provider](https://docs.aws.amazon.com/cli/latest/reference/ecs/update-capacity-provider.html)` in the *AWS CLI Command Reference*. ``` aws ecs update-capacity-provider \ --name CapacityProviderName \ --auto-scaling-group-provider "managedScaling={status=ENABLED}" ``` # Turning off Amazon ECS cluster auto scaling You turn off cluster auto scaling when you need more granular control of the EC2 instances that are registered to your cluster, To turn off cluster auto scaling for a cluster, you can either disassociate the capacity provider with managed scaling turned on from the cluster or update the capacity provider to turn off managed scaling. ## Disassociate the capacity provider Use the following steps to disassociate a capacity provider with a cluster. 1. Use the `put-cluster-capacity-providers` command to disassociate the Auto Scaling group capacity provider with the cluster. The cluster can keep the association with the AWS Fargate capacity providers. For more information, see `[put-cluster-capacity-providers](https://docs.aws.amazon.com/cli/latest/reference/ecs/put-cluster-capacity-providers.html)` in the *AWS CLI Command Reference*. ``` aws ecs put-cluster-capacity-providers \ --cluster ClusterName \ --capacity-providers FARGATE FARGATE_SPOT \ --default-capacity-provider-strategy '[]' ``` Use the `put-cluster-capacity-providers` command to disassociate the Auto Scaling group capacity provider with the cluster. For more information, see `[put-cluster-capacity-providers](https://docs.aws.amazon.com/cli/latest/reference/ecs/put-cluster-capacity-providers.html)` in the *AWS CLI Command Reference*. ``` aws ecs put-cluster-capacity-providers \ --cluster ClusterName \ --capacity-providers [] \ --default-capacity-provider-strategy '[]' ``` 1. Use the `describe-clusters` command to verify that the disassociation was successful. For more information, see `[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-clusters.html)` in the *AWS CLI Command Reference*. ``` aws ecs describe-clusters \ --cluster ClusterName \ --include ATTACHMENTS ``` ## Turn off managed scaling for the capacity provider Use the following steps to turn off managed scaling for the capacity provider. + Use the `update-capacity-provider` command to turn off managed auto scaling for the capacity provider. For more information, see `[update-capacity-provider](https://docs.aws.amazon.com/cli/latest/reference/ecs/update-capacity-provider.html)` in the *AWS CLI Command Reference*. ``` aws ecs update-capacity-provider \ --name CapacityProviderName \ --auto-scaling-group-provider "managedScaling={status=DISABLED}" ``` # Creating a capacity provider for Amazon ECS After the cluster creation completes, you can create a new capacity provider (Auto Scaling group) for EC2. Capacity providers help to manage and scale your the infrastructure for your applications. Before you create the capacity provider, you need to create an Auto Scaling group. For more information, see[ Auto Scaling groups](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html) in the *Amazon EC2 Auto Scaling User Guide*. **To create a capacity provider for the cluster (Amazon ECS console)** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose the cluster. 1. On the **Cluster : *name*** page, choose **Infrastructure**, and then choose **Create**. 1. On the **Create capacity providers** page, configure the following options. 1. Under **Basic details**, for **Capacity provider name**, enter a unique capacity provider name. 1. Under **Auto Scaling group**, for **Use an existing Auto Scaling group**, choose the Auto Scaling group. 1. (Optional) To configure a scaling policy, under **Scaling policies**, configure the following options. + To have Amazon ECS manage the scale-in and scale-out actions, select **Turn on managed scaling**. + To prevent EC2 instance with running Amazon ECS tasks from being terminated, select **Turn on scaling protection**. + For **Set target capacity**, enter the target value for the CloudWatch metric used in the Amazon ECS-managed target tracking scaling policy. 1. Choose **Create**. # Updating an Amazon ECS capacity provider When you use an Auto Scaling group as a capacity provider, you can modify the group's scaling policy. **To update a capacity provider for the cluster (Amazon ECS console)** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose the cluster. 1. On the **Cluster : *name*** page, choose **Infrastructure**, and then choose **Update**. 1. On the **Create capacity providers** page, configure the following options. 1. Under **Auto Scaling group**, under **Scaling policies**, configure the following options. + To have Amazon ECS manage the scale-in and scale-out actions, select **Turn on managed scaling**. + To prevent EC2 instances with running Amazon ECS tasks from being terminated, select **Turn on scaling protection**. + For **Set target capacity**, enter the target value for the CloudWatch metric used in the Amazon ECS-managed target tracking scaling policy. 1. Choose **Update**. # Deleting an Amazon ECS capacity provider If you are finished using an Auto Scaling group capacity provider, you can delete it. After the group is deleted, the Auto Scaling group capacity provider transitions to the `INACTIVE` state. Capacity providers with an `INACTIVE` status may remain discoverable in your account for a period of time. However, this behavior is subject to change in the future, so you should not rely on `INACTIVE` capacity providers persisting. Before the Auto Scaling group capacity provider is deleted, the capacity provider must be removed from the capacity provider strategy from all services. You can use the `UpdateService` API or the update service workflow in the Amazon ECS console to remove a capacity provider from a service's capacity provider strategy. Use the **Force new deployment** option to ensure that any tasks using the Amazon EC2 instance capacity provided by the capacity provider are transitioned to use the capacity from the remaining capacity providers. **To delete a capacity provider for the cluster (Amazon ECS console)** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose the cluster. 1. On the **Cluster : *name*** page, choose **Infrastructure**, the Auto Scaling group, and then choose **Delete**. 1. In the confirmation box, enter **delete *Auto Scaling group name*** 1. Choose **Delete**. # Safely stop Amazon ECS workloads running on EC2 instances Managed instance draining facilitates graceful termination of Amazon EC2 instances. This allows your workloads to stop safely and be rescheduled to non-terminating instances. Infrastructure maintenance and updates are performed without worrying about disruption to workloads. By using managed instance draining, you simplify your infrastructure management workflows that require replacement of Amazon EC2 instances while you ensure resilience and availability of your applications. Amazon ECS managed instance draining works with Auto Scaling group instance replacements. Based on instance refresh and maximum instance lifetime, customers can ensure that they stay compliant with the latest OS and security mandates for their capacity. Managed instance draining can only be used with Amazon ECS capacity providers. You can turn on managed instance draining when you create or update your Auto Scaling group capacity providers using the Amazon ECS console, AWS CLI, or SDK. The following events are covered by Amazon ECS managed instance draining. + [Auto Scaling group instance refresh](https://docs.aws.amazon.com/autoscaling/ec2/userguide/asg-instance-refresh.html) ‐ Use instance refresh to perform rolling replacement of your Amazon EC2 instances in your Auto Scaling group instead of manually doing it in batches. This is useful when you need to replace a large number of instances. An instance refresh is initiated through the Amazon EC2 console or the `StartInstanceRefresh` API. Make sure you select `Replace` for Scale-in protection when calling `StartInstanceRefresh` if you're using managed termination protection. + [Maximum instance lifetime](https://docs.aws.amazon.com/autoscaling/ec2/userguide/asg-max-instance-lifetime.html) ‐ You can define a maximum lifetime when it comes to replacing Auto Scaling group instances. This is helpful for scheduling replacement instances based on internal security policies or compliance. + Auto Scaling group scale-in ‐ Based on scaling policies and scheduled scaling actions, Auto Scaling group supports automatic scaling of instances. By using an Auto Scaling group as an Amazon ECS capacity provider, you can scale-in Auto Scaling group instances when no tasks are running in them. + [Auto Scaling group health checks](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-health-checks.html) ‐ Auto Scaling group supports many health checks to manage termination of unhealthy instances. + [CloudFormation stack updates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-direct.html) ‐ You can add an `UpdatePolicy` attribute to your CloudFormation stack to perform rolling updates when group changes. + [Spot capacity rebalancing](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-interruptions.html) ‐ The Auto Scaling group tries to proactively replace Spot Instances that have a higher risk of interruption based on Amazon EC2 capacity rebalance notice. The Auto Scaling group terminates the old instance when the replacement is launched and healthy. Amazon ECS managed instance draining drains the Spot Instance the same way it drains a non-Spot Instance. + [Spot interruption](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-capacity-rebalancing.html) ‐ Spot Instances are terminated with a two minute notice. Amazon ECS-managed instance draining puts the instance in draining state in response. **Amazon EC2 Auto Scaling lifecycle hooks with managed instance draining** Auto Scaling group lifecycle hooks enable customer to create solutions that are triggered by certain events in the instance lifecycle and perform a custom action when that certain event occurs. An Auto Scaling group allows for up to 50 hooks. Multiple termination hooks can exist and are performed in parallel, and Auto Scaling group waits for all hooks to finish before terminating an instance. In addition to the Amazon ECS-managed hook termination, you can also configure your own lifecycle termination hooks. Lifecycle hooks have a `default action`, and we recommend setting `continue` as the default to ensure other hooks, such as the Amazon ECS managed hook, aren't impacted by any errors from custom hooks. If you've already configured an Auto Scaling group termination lifecycle hook and also enabled Amazon ECS managed instance draining, both lifecycle hooks are performed. The relative timings, however, are not guaranteed. Lifecycle hooks have a `default action` setting to specify the action to take when timeout elapses. In case of failures we recommend using `continue` as the default result in your custom hook. This ensures other hooks, particularly the Amazon ECS managed hooks, aren't impacted by any errors in your custom lifecycle hook. The alternative result of `abandon` causes all other hooks to be skipped and should be avoided. For more information about Auto Scaling group lifecycle hooks see [Amazon EC2 Auto Scaling lifecycle hooks](https://docs.aws.amazon.com/autoscaling/ec2/userguide/lifecycle-hooks.html) in the *Amazon EC2* Auto Scaling User Guide. **Tasks and managed instance draining** Amazon ECS managed instance draining uses the existing draining feature found in container instances. The [container instance draining](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/container-instance-draining.html) feature performs replacement and stops for replica tasks that belong to an Amazon ECS service. A standalone task, like one invoked by `RunTask`, that is in the `PENDING` or `RUNNING` state remain unaffected. You have to wait for these to either complete or stop them manually. The container instance remains in the `DRAINING` state until either all tasks are stopped or 48 hours has passed. Daemon tasks are the last to stop after all replica tasks have stopped. **Managed instance draining and managed termination protection** Managed instance draining works even if managed termination is disabled. For information about managed termination protection, see [Control the instances Amazon ECS terminates](managed-termination-protection.md). The following table summarizes the behavior for different combinations of managed termination and managed draining. | Managed termination | Managed draining | Outcome | | --- | --- | --- | | Enabled | Enabled | Amazon ECS protects Amazon EC2 instances that are running tasks from being terminated by scale-in events. Any instances undergoing termination, such as those that don't have termination protection set, have received Spot interruption, or are forced by instance refresh are gracefully drained. | | Disabled | Enabled | Amazon ECS doesn't protect Amazon EC2 instances running tasks from being scaled-in. However, any instances that are being terminated are gracefully drained. | | Enabled | Disabled | Amazon ECS protects Amazon EC2 instances that are running tasks from being terminated by scale-in events. However, instances can still get terminated by Spot interruption or forced instance refresh, or if they aren't running any tasks. Amazon ECS doesn't perform graceful draining for these instances, and launches replacement service tasks after they stop. | | Disabled | Disabled | Amazon EC2 instances can be scaled-in or terminated at any time, even if they are running Amazon ECS tasks. Amazon ECS will launch replacement service tasks after they stop. | **Managed instance draining and Spot Instance draining** With Spot Instance draining, you can set an environment variable `ECS_ENABLE_SPOT_INSTANCE_DRAINING` on the Amazon ECS agent which enables Amazon ECS to place an instance in the draining status in response to the two-minute Spot interruption. Amazon ECS managed instance draining facilitates graceful shutdown of Amazon EC2 instances undergoing termination due to many reasons, not just Spot interruption. For instance, you can use Amazon EC2 Auto Scaling capacity rebalancing to proactively replace Spot Instance at elevated risk of interruption, and managed instance draining performs graceful shutdown of Spot Instance being replaced. When you use managed instance draining, you don't need to enable Spot instance draining separately, so `ECS_ENABLE_SPOT_INSTANCE_DRAINING` in Auto Scaling group user data is redundant. For more information about Spot Instance draining, see [Spot Instances](create-capacity.md#container-instance-spot). ## How managed instance draining works with EventBridge Amazon ECS managed instance draining events are published to Amazon EventBridge, and Amazon ECS creates an EventBridge managed rule in your account’s default bus to support managed instance draining. You can filter these events to other AWS services like Lambda, Amazon SNS, and Amazon SQS to monitor and troubleshoot. + Amazon EC2 Auto Scaling sends an event to EventBridge when a lifecycle hook is invoked. + Spot interruption notices are published to EventBridge. + Amazon ECS generates error messages that you can retrieve through the Amazon ECS console and APIs. + EventBridge has retry mechanisms built in as mitigations for temporary failures. # Configuring Amazon ECS capacity providers to safely shut down instances You can turn on managed instance draining when you create or update your Auto Scaling group capacity providers using the Amazon ECS console and AWS CLI. **Note** Managed instance draining is on by default when you create a capacity provider. The following are examples using the AWS CLI for creating a capacity provider with managed instance draining enabled and enabling managed instance draining for a cluster's existing capacity provider. **Create a capacity provider with managed instance draining enabled** To create a capacity provider with managed instance draining enabled, use the `create-capacity-provider` command. Set the `managedDraining` parameter to `ENABLED`. ``` aws ecs create-capacity-provider \ --name capacity-provider \ --auto-scaling-group-provider '{ "autoScalingGroupArn": "asg-arn", "managedScaling": { "status": "ENABLED", "targetCapacity": 100, "minimumScalingStepSize": 1, "maximumScalingStepSize": 1 }, "managedDraining": "ENABLED", "managedTerminationProtection": "ENABLED", }' ``` Response: ``` { "capacityProvider": { "capacityProviderArn": "capacity-provider-arn", "name": "capacity-provider", "status": "ACTIVE", "autoScalingGroupProvider": { "autoScalingGroupArn": "asg-arn", "managedScaling": { "status": "ENABLED", "targetCapacity": 100, "minimumScalingStepSize": 1, "maximumScalingStepSize": 1 }, "managedTerminationProtection": "ENABLED" "managedDraining": "ENABLED" } } } ``` **Enable managed instance draining for a cluster's existing capacity provider** Enable managed instance draining for a cluster's existing capacity provider uses the `update-capacity-provider` command. You see that `managedDraining` currently says `DISABLED` and `updateStatus` says `UPDATE_IN_PROGRESS`. ``` aws ecs update-capacity-provider \ --name cp-draining \ --auto-scaling-group-provider '{ "managedDraining": "ENABLED" } ``` Response: ``` { "capacityProvider": { "capacityProviderArn": "cp-draining-arn", "name": "cp-draining", "status": "ACTIVE", "autoScalingGroupProvider": { "autoScalingGroupArn": "asg-draining-arn", "managedScaling": { "status": "ENABLED", "targetCapacity": 100, "minimumScalingStepSize": 1, "maximumScalingStepSize": 1, "instanceWarmupPeriod": 300 }, "managedTerminationProtection": "DISABLED", "managedDraining": "DISABLED" // before update }, "updateStatus": "UPDATE_IN_PROGRESS", // in progress and need describe again to find out the result "tags": [ ] } } ``` Use the `describe-clusters` command and include `ATTACHMENTS`. The `status` of the managed instance draining attachment is `PRECREATED`, and the overall `attachmentsStatus` is `UPDATING`. ``` aws ecs describe-clusters --clusters cluster-name --include ATTACHMENTS ``` Response: ``` { "clusters": [ { ... "capacityProviders": [ "cp-draining" ], "defaultCapacityProviderStrategy": [], "attachments": [ # new precreated managed draining attachment { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "type": "managed_draining", "status": "PRECREATED", "details": [ { "name": "capacityProviderName", "value": "cp-draining" }, { "name": "autoScalingLifecycleHookName", "value": "ecs-managed-draining-termination-hook" } ] }, ... ], "attachmentsStatus": "UPDATING" } ], "failures": [] } ``` When the update is finished, use `describe-capacity-providers`, and you see `managedDraining` is now `ENABLED`. ``` aws ecs describe-capacity-providers --capacity-providers cp-draining ``` Response: ``` { "capacityProviders": [ { "capacityProviderArn": "cp-draining-arn", "name": "cp-draining", "status": "ACTIVE", "autoScalingGroupProvider": { "autoScalingGroupArn": "asg-draning-arn", "managedScaling": { "status": "ENABLED", "targetCapacity": 100, "minimumScalingStepSize": 1, "maximumScalingStepSize": 1, "instanceWarmupPeriod": 300 }, "managedTerminationProtection": "DISABLED", "managedDraining": "ENABLED" // successfully update }, "updateStatus": "UPDATE_COMPLETE", "tags": [] } ] } ``` ## Amazon ECS Managed instance draining troubleshooting You might need to troubleshoot issues with managed instance draining. The following is an example of an issue and resolution you may come across while using it. **Instances don't terminate after exceeding maximum instance lifetime when using auto scaling.** If your instances aren't terminating even after reaching and exceeding the maximum instance lifetime while using an auto scaling group, it may be because they're protected from scale-in. You can turn off managed termination and allow managed draining to handle instance recycling. ## Draining behavior for Amazon ECS Managed Instances Amazon ECS Managed Instances termination ensures graceful workload transitions while optimizing costs and maintaining system health. The termination system provides three distinct decision paths for instance termination, each with different timing characteristics and customer impact profiles. ### Termination decision paths Customer-initiated termination Provides direct control over instance removal when you need to remove container instances from service immediately. You invoke the DeregisterContainerInstance API with the force flag set to true, indicating that immediate termination is required despite any running workloads. System-initiated idle termination Amazon ECS Managed Instances continuously monitors and proactively optimizes costs by terminating idle Amazon ECS container instances not running any tasks. ECS uses a heuristic delay to give container instances a chance to acquire newly launched tasks before being terminated. This can be customized with the `scaleInAfter` Amazon ECS Managed Instances capacity provider configuration parameter. Infrastructure refresh termination Amazon ECS Managed Instances automatically manages and updates software on managed container instances to ensure security and compliance while maintaining workload availability. For more information, see [patching in Amazon ECS Managed Instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/managed-instances-patching.html). ### Graceful draining and workload migration The graceful draining system implements sophisticated coordination with Amazon ECS service management to ensure that service-managed tasks are properly migrated away from instances scheduled for termination. **Service task draining coordination** When an instance transitions to DRAINING state, the Amazon ECS scheduler automatically stops placing new tasks on the instance while implementing graceful shutdown procedures for existing service tasks. The service task draining includes coordination with service deployment strategies, health check requirements, and your draining preferences to ensure optimal migration timing and success rates. **Standalone task handling** Standalone tasks require different handling because they do not benefit from automatic service management. The system evaluates standalone task characteristics including task duration estimates, completion probability analysis, and customer impact assessment. The graceful completion strategy allows standalone tasks to complete naturally during an extended grace period, while forced termination ensures infrastructure refresh occurs within acceptable timeframes when tasks have not completed naturally. ### Two-phase completion strategy The termination system implements a two-phase approach that balances workload continuity against infrastructure management requirements. **Phase 1: Graceful completion period** During this phase, the system implements graceful draining strategies that prioritize workload continuity. Service tasks are gracefully drained through normal Amazon ECS scheduling processes, standalone tasks continue running and may complete naturally, and the system monitors for all tasks to reach stopped state through natural completion processes. **Phase 2: Hard deadline enforcement** When graceful completion does not achieve termination objectives within acceptable timeframes, the system implements hard deadline enforcement. The hard deadline is typically set to draining initiation time plus seven days, providing substantial time for graceful completion while maintaining operational requirements. The enforcement includes automatic invocation of force deregistration procedures and immediate termination of all remaining tasks regardless of completion status. # Creating resources for Amazon ECS cluster auto scaling using the AWS Management Console Learn how to create the resources for cluster auto scaling using the AWS Management Console. Where resources require a name, we use the prefix `ConsoleTutorial` to ensure they all have unique names and to make them easy to locate. **Topics** + [Prerequisites](#console-tutorial-prereqs) + [Step 1: Create an Amazon ECS cluster](#console-tutorial-cluster) + [Step 2: Register a task definition](#console-tutorial-register-task-definition) + [Step 3: Run a task](#console-tutorial-run-task) + [Step 4: Verify](#console-tutorial-verify) + [Step 5: Clean up](#console-tutorial-cleanup) ## Prerequisites This tutorial assumes that the following prerequisites have been completed: + The steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) have been completed. + Your IAM user has the required permissions specified in the [AmazonECS\$1FullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonECS_FullAccess) IAM policy example. + The Amazon ECS container instance IAM role is created. For more information, see [Amazon ECS container instance IAM role](instance_IAM_role.md). + The Amazon ECS service-linked IAM role is created. For more information, see [Using service-linked roles for Amazon ECS](using-service-linked-roles.md). + The Auto Scaling service-linked IAM role is created. For more information, see [Service-Linked Roles for Amazon EC2 Auto Scaling](https://docs.aws.amazon.com/autoscaling/ec2/userguide/autoscaling-service-linked-role.html) in the *Amazon EC2 Auto Scaling User Guide*. + You have a VPC and security group created to use. For more information, see [Create a virtual private cloud](get-set-up-for-amazon-ecs.md#create-a-vpc). ## Step 1: Create an Amazon ECS cluster Use the following steps to create an Amazon ECS cluster. Amazon ECS creates an Amazon EC2 Auto Scaling launch template and Auto Scaling group on your behalf as part of the CloudFormation stack. 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**, and then choose **Create cluster**. 1. Under **Cluster configuration**, for **Cluster name**, enter `ConsoleTutorial-cluster`. 1. Under **Infrastructure**, clear AWS Fargate (serverless), and then select **Amazon EC2 instances**. Next, configure the Auto Scaling group which acts as the capacity provider. 1. Under ** Auto Scaling group (ASG) **. Select **Create new ASG**, and then provide the following details about the group: + For **Operating system/Architecture**, choose **Amazon Linux 2**. + For **EC2 instance type**, choose **t3.nano**. + For **Capacity**, enter the minimum number and the maximum number of instances to launch in the Auto Scaling group. 1. (Optional) To manage the cluster tags, expand **Tags**, and then perform one of the following operations: [Add a tag] Choose **Add tag** and do the following: + For **Key**, enter the key name. + For **Value**, enter the key value. [Remove a tag] Choose **Remove** to the right of the tag’s Key and Value. 1. Choose **Create**. ## Step 2: Register a task definition Before you can run a task on your cluster, you must register a task definition. Task definitions are lists of containers grouped together. The following example is a simple task definition that uses an `amazonlinux` image from Docker Hub and simply sleeps. For more information about the available task definition parameters, see [Amazon ECS task definitions](task_definitions.md). 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Task definitions**. 1. Choose **Create new task definition**, **Create new task definition with JSON**. 1. In the **JSON editor** box, paste the following contents. ``` { "family": "ConsoleTutorial-taskdef", "containerDefinitions": [ { "name": "sleep", "image": "public.ecr.aws/amazonlinux/amazonlinux:latest", "memory": 20, "essential": true, "command": [ "sh", "-c", "sleep infinity" ] } ], "requiresCompatibilities": [ "EC2" ] } ``` 1. Choose **Create**. ## Step 3: Run a task After you have registered a task definition for your account, you can run a task in the cluster. For this tutorial, you run five instances of the `ConsoleTutorial-taskdef` task definition in your `ConsoleTutorial-cluster` cluster. 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 **ConsoleTutorial-cluster**. 1. Under **Tasks**, choose **Run new task**. 1. In the **Environment** section, under ** Compute options**, choose **Capacity provider strategy**. 1. Under **Deployment configuration**, for **Application type**, choose **Task**. 1. Choose **ConsoleTutorial-taskdef** from the ** Family ** dropdown list. 1. Under **Desired tasks**, enter 5. 1. Choose **Create**. ## Step 4: Verify At this point in the tutorial, you should have a cluster with five tasks running and an Auto Scaling group with a capacity provider. The capacity provider has Amazon ECS managed scaling enabled. We can verify that everything is working properly by viewing the CloudWatch metrics, the Auto Scaling group settings, and finally the Amazon ECS cluster task count. **To view the CloudWatch metrics for your cluster** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. On the navigation bar at the top of the screen, select the Region. 1. On the navigation pane, under ** Metrics**, choose **All metrics**. 1. On the **All metrics** page, under the **Browse** tab, choose `AWS/ECS/ManagedScaling`. 1. Choose **CapacityProviderName, ClusterName**. 1. Select the check box that corresponds to the `ConsoleTutorial-cluster` ** ClusterName**. 1. Under the **Graphed metrics** tab, change **Period** to **30 seconds** and **Statistic** to **Maximum**. The value displayed in the graph shows the target capacity value for the capacity provider. It should begin at `100`, which was the target capacity percent we set. You should see it scale up to `200`, which will trigger an alarm for the target tracking scaling policy. The alarm will then trigger the Auto Scaling group to scale out. Use the following steps to view your Auto Scaling group details to confirm that the scale-out action occurred. **To verify the Auto Scaling group scaled out** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. On the navigation bar at the top of the screen, select the Region. 1. On the navigation pane, under **Auto Scaling**, choose **Auto Scaling Groups**. 1. Choose the `ConsoleTutorial-cluster` Auto Scaling group created in this tutorial. View the value under **Desired capacity ** and view the instances under the ** Instance management ** tab to confirm your group scaled out to two instances. Use the following steps to view your Amazon ECS cluster to confirm that the Amazon EC2 instances were registered with the cluster and your tasks transitioned to a `RUNNING` status. **To verify the instances in the Auto Scaling group** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose the `ConsoleTutorial-cluster` cluster. 1. On the **Tasks** tab, confirm you see five tasks in the `RUNNING` status. ## Step 5: Clean up When you have finished this tutorial, clean up the resources associated with it to avoid incurring charges for resources that you aren't using. Deleting capacity providers and task definitions are not supported, but there is no cost associated with these resources. **To clean up the tutorial resources** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose **ConsoleTutorial-cluster**. 1. On the **ConsoleTutorial-cluster** page, choose the **Tasks** tab, and then choose **Stop**, **Stop all**. 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose **ConsoleTutorial-cluster**. 1. In the upper-right of the page, choose **Delete cluster**. 1. In the confirmation box, enter **delete **ConsoleTutorial-cluster**** and choose **Delete**. 1. Delete the Auto Scaling groups using the following steps. 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. On the navigation bar at the top of the screen, select the Region. 1. On the navigation pane, under **Auto Scaling**, choose **Auto Scaling Groups**. 1. Select the `ConsoleTutorial-cluster` Auto Scaling group, then choose ** Actions**. 1. From the **Actions** menu, choose **Delete**. Enter ** delete** in the confirmation box and then choose **Delete**.