# Amazon ECS clusters
An Amazon ECS cluster is a logical grouping of tasks or services that provides the infrastructure capacity for your containerized applications. When creating a cluster, you choose from the three primary infrastructure types, each optimized for different use cases and operational requirements.
## Choosing the right cluster type
Amazon ECS offers three infrastructure types for your clusters. Choose the type that best matches your workload requirements, operational preferences, and cost optimization goals:
Amazon ECS Managed Instances (Recommended)
**Best for most workloads** - AWS fully manages the underlying Amazon EC2 instances, including provisioning, patching, and scaling. This option provides the optimal balance of performance, cost-effectiveness, and operational simplicity.
**Use when:**
+ You want AWS to handle infrastructure management
+ You need cost-effective compute with automatic optimization
+ You want to focus on your applications rather than infrastructure
+ You need predictable performance with flexible scaling
Fargate
**Serverless compute** - Pay only for the resources your tasks use without managing any infrastructure. Ideal for variable workloads and getting started quickly.
**Use when:**
+ You want completely serverless operations
+ You have unpredictable or variable workloads
+ You want to minimize operational overhead
+ You need rapid deployment and scaling
Amazon EC2 instances
**Full control** - You manage the underlying Amazon EC2 instances directly, including instance selection, configuration, and maintenance.
**Use when:**
+ You need specific instance types or configurations
+ You have existing Amazon EC2 infrastructure to leverage
+ You require custom AMIs or specialized software
+ You need maximum control over the underlying infrastructure
**Note**
Amazon ECS Managed Instances is the recommended choice for most new workloads as it provides the best combination of performance, cost optimization, and operational simplicity while allowing AWS to handle infrastructure management tasks.
## Cluster components
In addition to the infrastructure capacity, a cluster consists of the following resources:
+ The network (VPC and subnet) where your tasks and services run
When you use Amazon ECS Managed Instances or Amazon EC2 instances for the capacity, the subnet can be in Availability Zones, Local Zones, Wavelength Zones, or AWS Outposts.
+ An optional namespace
A namespace is used for service-to-service communication with Service Connect.
+ A monitoring option
CloudWatch Container Insights comes at an additional cost and is a fully managed service. It automatically collects, aggregates, and summarizes Amazon ECS metrics and logs.
## Cluster concepts
The following are general concepts about Amazon ECS clusters.
+ You create clusters to separate your resources.
+ Clusters are AWS Region specific.
+ Clusters can be in any of the following states.
ACTIVE
The cluster is ready to accept tasks and, if applicable, you can register container instances with the cluster.
PROVISIONING
The cluster has capacity providers associated with it and the resources needed for the capacity provider are being created.
DEPROVISIONING
The cluster has capacity providers associated with it and the resources needed for the capacity provider are being deleted.
FAILED
The cluster has capacity providers associated with it and the resources needed for the capacity provider have failed to create.
INACTIVE
The cluster has been deleted. Clusters with an `INACTIVE` status may remain discoverable in your account for a period of time. This behavior is subject to change in the future, so make sure you do not rely on `INACTIVE` clusters persisting.
+ A cluster can contain a mix of tasks that are hosted on Amazon ECS Managed Instances, AWS Fargate, Amazon EC2 instances, or external instances. Tasks can run on Amazon ECS Managed Instances, Fargate or EC2 infrastructure as a launch type or a capacity provider strategy. If you use EC2 capacity providers, Amazon ECS doesn't track and scale the capacity of Amazon EC2 Auto Scaling groups.
+ A cluster can contain a mix of Amazon ECS Managed Instances capacity providers, Auto Scaling group capacity providers, and Fargate capacity providers. A capacity provider strategy can only contain Amazon ECS Managed Instances capacity providers, Auto Scaling group capacity providers, or Fargate capacity providers.
+ You can use different instance types for the Amazon ECS Managed Instances and EC2, or Auto Scaling group capacity providers. An instance can only be registered to one cluster at a time.
+ You can restrict access to clusters by creating custom IAM policies. For information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies) section in [Identity-based policy examples for Amazon Elastic Container Service](security_iam_id-based-policy-examples.md).
+ You can use Service Auto Scaling to scale Fargate tasks. For more information, see [Automatically scale your Amazon ECS service](service-auto-scaling.md).
+ You can configure a default Service Connect namespace for a cluster. After you set a default Service Connect namespace, any new services created in the cluster can be added as client services in the namespace by turning on Service Connect. No additional configuration is required. For more information, see [Use Service Connect to connect Amazon ECS services with short names](service-connect.md).
## Capacity providers
Amazon ECS capacity providers manage the scaling of infrastructure for tasks in your clusters. Each cluster can have one or more capacity providers and an optional capacity provider strategy. You can assign a default capacity provider strategy to the cluster. The capacity provider strategy determines how the tasks are spread across the cluster's capacity providers. When you run a standalone task or create a service, you either use the cluster's default capacity provider strategy or a capacity provider strategy that overrides the default one. The cluster's default capacity provider strategy only applies when you don't specify a launch type, or capacity provider strategy for your task or service. If you provide either of these parameters, the default strategy isn't used.
Amazon ECS offers three types of capacity providers for your clusters:
Amazon ECS Managed Instances capacity providers
AWS fully manages the underlying Amazon EC2 instances, including provisioning, patching, scaling, and lifecycle management. This provides the optimal balance of performance, cost-effectiveness, and operational simplicity. Amazon ECS Managed Instances capacity providers automatically optimize instance selection and scaling based on your workload requirements.
With Amazon ECS Managed Instances, you benefit from:
+ Automatic instance provisioning and scaling
+ Managed patching and security updates
+ Cost optimization through intelligent instance selection
+ Reduced operational overhead
Fargate capacity providers
Serverless compute where you pay only for the resources your tasks use without managing any infrastructure. You just need to associate the pre-defined capacity providers (Fargate and Fargate Spot) with the cluster.
Auto Scaling group capacity providers
When you use Amazon EC2 instances for your capacity, you use Auto Scaling group to manage the Amazon EC2 instances. Auto Scaling helps ensure that you have the correct number of Amazon EC2 instances available to handle the application load. You have full control over the underlying infrastructure.
A cluster can contain a mix of tasks that are hosted on Amazon ECS Managed Instances, AWS Fargate, Amazon EC2 instances, or external instances. Tasks can run on Amazon ECS Managed Instances, Fargate or EC2 infrastructure as a launch type or a capacity provider strategy. If you use EC2 as a launch type, Amazon ECS doesn't track and scale the capacity of Amazon EC2 Auto Scaling groups.
A cluster can contain a mix of Amazon ECS Managed Instances capacity providers, Auto Scaling group capacity providers, and Fargate capacity providers. A capacity provider strategy can only contain Amazon ECS Managed Instances capacity providers, Auto Scaling group capacity providers, or Fargate capacity providers.
# Clusters for Amazon ECS Managed Instances
Amazon ECS capacity providers manage the scaling of infrastructure for tasks in your clusters. After you create the cluster, you create one or more capacity providers and an optional capacity provider strategy for the cluster. The capacity provider strategy determines how the tasks are spread across the cluster's capacity providers. When you run a standalone task or create a service, you either use the cluster's default capacity provider strategy or a capacity provider strategy that overrides the default one.
Amazon ECS Managed Instances has the following capacity providers.
| Type | Criteria used to choose instances |
| --- | --- |
| Default | The most cost-effective instances that meet the following task definition and service parameter requirements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/managed-instance-clusters.html) |
| Custom | The instances that meet the attribute and type requirements that you specify when you creaate the cluster. For information about attributes, see [Amazon ECS container instance attributes](task-placement-constraints.md#attributes). For information about instance types, see [Amazon EC2 instance type specifications](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-instance-type-specifications.html) in Amazon EC2 Instance Types. |
Amazon ECS launches the instances and associates them with the Amazon ECS Managed Instances capacity provider. For the custom capacity provider, Amazon ECS also creates the capacity provider.
# Creating a cluster for Amazon ECS Managed Instances
You create a cluster to define the infrastructure your tasks and services run on.
When you create a cluster for Amazon ECS Managed Instances, Amazon ECS automatically creates a managed instances capacity provider with default configurations. This capacity provider selects the most cost-optimized instance types for your workloads. You can also create custom capacity providers if you need specific instance attributes or types.
To make the cluster creation process as easy as possible, the console has default selections for many choices.
+ Creates a default namespace in AWS Cloud Map that is the same name as the cluster. A namespace allows services that you create in the cluster to connect to the other services in the namespace without additional configuration.
For more information, see [Interconnect Amazon ECS services](interconnecting-services.md).
You can modify the following options:
+ Change the default namespace associated with the cluster.
A namespace allows services that you create in the cluster to connect to the other services in the namespace without additional configuration. The default namespace is the same as the cluster name. For more information, see [Interconnect Amazon ECS services](interconnecting-services.md).
+ Assign a AWS KMS key for your managed storage. For information about how to create a key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*.
+ Add tags to help you identify your cluster.
## Prerequisites
Before you begin, be sure that you've completed the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) and assign the appropriate IAM permission. For more information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies).
The user creating the cluster must have an additional permission: `iam:CreateServiceLinkedRole`.
When you don't specify `instanceRequirements`, Amazon ECS automatically selects the most cost-optimized instance types based on your task definition requirements. To use specific instance attributes or types, create a capacity provider with `instanceRequirements`.
Understand how to choose your instances. For more information, see [Instance selection best practices for Amazon ECS Managed Instances](managed-instances-instance-selection-best-practices.md).
You have the required IAM roles for Amazon ECS Managed Instances. This includes:
+ **Infrastructure role** - Allows Amazon ECS to make calls to AWS services on your behalf to manage Amazon ECS Managed Instances infrastructure.
For more information, see [Amazon ECS infrastructure IAM role](infrastructure_IAM_role.md).
+ **Instance profile** - Provides permissions for the Amazon ECS container agent and Docker daemon running on managed instances.
For more information, see [Amazon ECS Managed Instances instance profile](managed-instances-instance-profile.md).
## Console procedure
**To create a new cluster (Amazon ECS console)**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, choose **Create cluster**.
1. Under **Cluster configuration**, configure the following:
+ For **Cluster name**, enter a unique name.
The name can contain up to 255 letters (uppercase and lowercase), numbers, and hyphens.
+ (Optional) To have the namespace used for Service Connect be different from the cluster name, for **Namespace**, enter a unique name.
1. For **Custom Capacity Provider**, do the following:
+ For **Select a method of obtaining EC2 capacity**, choose **Amazon ECS Managed Instances**.
+ For Instance profile, choose the instance profile role.
+ For Infrastructure role, choose the infrastructure role.
+ To use a custom capacity provider, for **Instance selection**, choose **Use custom**. Then, for each attribute, enter the **Attribute value**.
1. (Optional) Use Container Insights, expand **Monitoring**, and then choose one of the following options:
+ To use the recommended Container Insights with enhanced observability, choose **Container Insights with enhanced observability**.
+ To use Container Insights, choose **Container Insights**.
1. (Optional) Encrypt the data on managed storage. Under **Encryption**, for **Managed storage**, enter the ARN of the AWS KMS key you want to use to encrypt the managed storage data.
1. (Optional) To help identify your cluster, expand **Tags**, and then configure your tags.
[Add a tag] Choose **Add tag** and do the following:
+ For **Key**, enter the key name.
+ For **Value**, enter the key value.
1. Choose **Create**.
## AWS CLI procedure
You can create a cluster for Amazon ECS Managed Instances using the AWS CLI. Use the latest version of the AWS CLI. For more information on how to upgrade to the latest version, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
**Note**
You can use dual-stack service endpoints to interact with Amazon ECS from the AWS AWS CLI, SDKs, and the Amazon ECS API over both IPv4 and IPv6. For more information, see [Using Amazon ECS dual-stack endpoints](dual-stack-endpoint.md).
**To create a new cluster (AWS CLI)**
1. Create your cluster with a unique name using the following command:
```
aws ecs create-cluster --cluster-name managed-instances-cluster
```
Output:
```
{
"cluster": {
"status": "ACTIVE",
"defaultCapacityProviderStrategy": [],
"statistics": [],
"capacityProviders": [],
"tags": [],
"clusterName": "managed-instances-cluster",
"settings": [
{
"name": "containerInsights",
"value": "disabled"
}
],
"registeredContainerInstancesCount": 0,
"pendingTasksCount": 0,
"runningTasksCount": 0,
"activeServicesCount": 0,
"clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/managed-instances-cluster"
}
}
```
1. (Optional) To enable Container Insights with enhanced observability for your cluster, use the following command:
```
aws ecs put-account-setting --name containerInsights --value enhanced
```
1. (Optional) To add tags to your cluster, use the following command:
```
aws ecs tag-resource --resource-arn arn:aws:ecs:region:aws_account_id:cluster/managed-instances-cluster --tags key=Environment,value=Production
```
## Next steps
Create a task definition for Amazon ECS Managed Instances. For more information, see [Creating an Amazon ECS task definition using the console](create-task-definition.md).
Run your applications as standalone tasks, or as part of a service. For more information, see the following:
+ [Running an application as an Amazon ECS task](standalone-task-create.md)
+ [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md)
# Updating a cluster to use Amazon ECS Managed Instances
You can update an existing cluster to use Amazon ECS Managed Instances.
When you add Amazon ECS Managed Instances to your cluster, Amazon ECS automatically creates a managed instances capacity provider with default configurations. This capacity provider selects the most cost-optimized general-purpose instance types for your workloads. You can also create custom capacity providers if you need specific instance attributes or types.
## Prerequisites
When you don't specify `instanceRequirements`, Amazon ECS automatically selects the most cost-optimized instance types based on your task definition requirements. To use specific instance attributes or types, create a capacity provider with `instanceRequirements`.
You have the required IAM roles for Amazon ECS Managed Instances. This includes:
+ **Infrastructure role** - Allows Amazon ECS to make calls to AWS services on your behalf to manage Amazon ECS Managed Instances infrastructure.
For more information, see [Amazon ECS infrastructure IAM role](infrastructure_IAM_role.md).
+ **Instance profile** - Provides permissions for the Amazon ECS container agent and Docker daemon running on managed instances.
For more information, see [Amazon ECS Managed Instances instance profile](managed-instances-instance-profile.md).
## Update considerations
When updating a cluster for Amazon ECS Managed Instances, consider the following:
+ Running tasks - Updating cluster settings does not affect currently running tasks. Changes will apply to new tasks launched after the update.
+ Capacity provider changes - If you modify capacity provider settings, existing managed instances will continue to run, but new instances will use the updated configuration.
+ Monitoring changes - Enabling or disabling Container Insights will affect metric collection for the entire cluster.
## Console procedure
**To update a cluster (Amazon ECS console)**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, select the cluster you want to update.
1. Choose **Update cluster**.
1. (Optional) To modify capacity provider settings, under **Custom Capacity Provider**, update the following as needed:
+ For **Instance profile**, choose a different instance profile role if needed.
+ For **Infrastructure role**, choose a different infrastructure role if needed.
+ To use a custom capacity provider, for **Instance selection**, update the **Attribute value** settings.
1. Choose **Update**.
## AWS CLI procedure
You can update a cluster for Amazon ECS Managed Instances using the AWS CLI. Use the latest version of the AWS CLI. For more information on how to upgrade to the latest version, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
**Note**
You can use dual-stack service endpoints to interact with Amazon ECS from the AWS AWS CLI, SDKs, and the Amazon ECS API over both IPv4 and IPv6. For more information, see [Using Amazon ECS dual-stack endpoints](dual-stack-endpoint.md).
**To update a cluster (AWS CLI)**
1. Create a capacity provider for . Run the following command:
Replace the *user-input* with your values.
```
aws ecs create-capacity-provider \
--name my-managed-instances-provider \
--managed-instances-provider \
--instance-profile arn:aws:iam::123456789012:instance-profile/ecsInstanceProfile \
--infrastructure-role-arn arn:aws:iam::123456789012:role/ecsInfrastructureRole \
--instance-requirements '{
"vCpuCount": {"min": 2, "max": 8},
"memoryMiB": {"min": 4096, "max": 16384}
}
```
1. Add the capacity provider to the cluster, use the following command:
Replace the *user-input* with your values.
```
aws ecs put-cluster-capacity-providers --cluster managed-instances-cluster --capacity-providers my-managed-instances-provider --default-capacity-provider-strategy capacityProvider=my-managed-instances-provider,weight=1
```
# Amazon ECS Managed Instances capacity providers
Amazon ECS Managed Instances capacity providers provide a container compute model that gives you access to the full range of AWS capabilities and Amazon EC2 offerings while AWS manages operational and security responsibilities. AWS handles software and OS patching, instance scaling, and maintenance, giving you the operational benefits of Fargate while maintaining access to all AWS capabilities and integrations.
Amazon ECS creates launch templates for your Amazon ECS Managed Instances. This defines how Amazon ECS launches Amazon ECS Managed Instances, including the instance profile for your tasks, network and storage configuration, capacity options, and instance requirements for flexible instance type selection.
## When to use custom capacity providers
Consider custom capacity providers when your workloads require:
+ Specific compute requirements: Applications requiring accelerated compute, specific CPU instruction sets, high network performance, or large memory configurations that aren't available with standard Fargate options.
+ GPU workloads: Machine learning inference, real-time image rendering, video encoding, or other GPU-accelerated applications that need access to NVIDIA or AMD GPUs.
+ Capacity reservations: Mission-critical workloads that require predictable capacity availability.
+ Advanced observability: Security and monitoring tools that require privileged access to the underlying OS, such as eBPF-based monitoring solutions or network analysis tools.
+ Cost optimization: Workloads that can benefit from multi-task placement, shared infrastructure components, or need to maximize utilization of larger instance types.
## Monitoring options
Amazon ECS Managed Instances provide comprehensive monitoring capabilities to help you track performance, health, and resource utilization of your containerized workloads. You can choose from different monitoring levels based on your operational requirements.
+ **Basic monitoring** – Provides essential metrics at 5-minute intervals for most metrics and 1-minute intervals for status checks. This is enabled by default and incurs no additional charges.
+ **Detailed monitoring** – Offers enhanced visibility with all metrics available at 1-minute intervals, enabling faster detection and response to operational issues. For more information, see [Detailed monitoring for Amazon ECS Managed Instances](monitoring-managed-instances.md#detailed-monitoring-managed-instances).
Both monitoring options integrate seamlessly with CloudWatch to provide dashboards, alarms, and automated responses to help maintain optimal application performance and availability.
## Capacity provider considerations
A cluster can contain a mix of Amazon ECS Managed Instances capacity providers, Auto Scaling group capacity providers, and Fargate capacity providers. A capacity provider strategy can only contain Amazon ECS Managed Instances capacity providers, Auto Scaling group capacity providers, or Fargate capacity providers.
## Tag propagation
Capacity providers for Amazon ECS Managed Instances support tag propagation. With tag propagation, all resources managed by the capacity provider — the managed instance, the Amazon ECS container instance, launch template, volumes, Elastic Network Interfaces — are tagged with the same tags specified at the capacity provider level. You can specify tags during capacity provider creation and enable tag propagation by specifying the `propagateTags` parameter as `CAPACITY_PROVIDER`.
For more information about tagging Amazon ECS Managed Instances, see [Tags for Amazon ECS Managed Instances](instance-details-tags-managed-instances.md).
# Best practices for updating capacity providers for Amazon ECS Managed Instances
For the highest level of safety and rollback support, we recommend treating capacity providers as immutable resources. When you need to update a capacity provider configuration, follow this recommended workflow:
1. **Create a new capacity provider** with your updated configuration instead of modifying the existing one.
1. **Update each service** to use the new capacity provider and allow the deployments to complete.
1. **Delete the old capacity provider** after confirming the new configuration works as expected.
This approach provides several benefits:
+ **Controlled rollout** - You can update services one at a time and monitor the impact.
+ **Easy rollback** - If issues occur, you can quickly revert services to use the previous capacity provider.
+ **Reduced blast radius** - Problems with the new configuration don't immediately affect all workloads.
**Note**
If you're using CloudFormation, consider keeping the old capacity provider until a later deployment to preserve the ability to roll back your stack changes.
While you can update capacity providers in place, this approach creates a larger uncontrolled blast radius. In-place updates apply new settings to all new capacity provisioned going forward, but don't trigger service deployments. This means you might not discover configuration issues until much later when your services need to scale.
# Creating a capacity provider for Amazon ECS Managed Instances
Amazon ECS Managed Instances uses capacity providers to manage compute capacity for your workloads. When you create a capacity provider without specifying `instanceRequirements`, Amazon ECS automatically selects the most cost-optimized [general-purpose instance types](https://aws.amazon.com/ec2/instance-types/general-purpose/). You can create capacity providers with `instanceRequirements` to specify instance attributes such as instance types, CPU manufacturers, accelerator types, and other requirements.
Custom capacity providers use attribute-based instance type selection, which allows you to express instance requirements as a set of attributes. These requirements are automatically translated to all matching Amazon EC2 instance types, simplifying the creation and maintenance of instance type configurations. To learn more about instance requirements and attribute-based selection, see the [Amazon EC2 Fleet attribute-based instance type selection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-fleet-attribute-based-instance-type-selection.html) documentation in the *Amazon EC2 User Guide*.
## Prerequisites
Before you begin, ensure that you have completed the following:
+ Determine what type of monitoring to use. For more information, see [Detailed monitoring for Amazon ECS Managed Instances](monitoring-managed-instances.md#detailed-monitoring-managed-instances).
+ Have an existing cluster or plan to create one. For more information, see [Creating a cluster for Amazon ECS Managed Instances](create-cluster-managed-instances.md).
+ You have the required IAM roles for Amazon ECS Managed Instances. This includes:
+ **Infrastructure role** - Allows Amazon ECS to make calls to AWS services on your behalf to manage Amazon ECS Managed Instances infrastructure.
For more information, see [Amazon ECS infrastructure IAM role](infrastructure_IAM_role.md).
+ **Instance profile** - Provides permissions for the Amazon ECS container agent and Docker daemon running on managed instances.
For more information, see [Amazon ECS Managed Instances instance profile](managed-instances-instance-profile.md).
Understand how to choose your instances. For more information, see [Instance selection best practices for Amazon ECS Managed Instances](managed-instances-instance-selection-best-practices.md).
## Console procedure
**To create a capacity provider for Amazon ECS Managed Instances (Amazon ECS console)**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, choose your cluster name.
1. On the cluster page, choose the **Infrastructure** tab.
1. In the **Capacity providers** section, choose **Create capacity provider**.
1. Under **Capacity provider configuration**, configure the following:
+ For **Capacity provider name**, enter a unique name for your capacity provider.
+ For **Capacity provider type**, choose **Amazon ECS Managed Instances**.
1. Under **Instance configuration**, configure the following:
+ For **Instance profile**, choose the instance profile role created for Amazon ECS Managed Instances.
+ For **Infrastructure role**, choose the infrastructure role created for Amazon ECS Managed Instances.
1. Under **Instance requirements**, specify the attributes for your instances. You can configure any combination of the following:
+ **vCPU count** - Specify the number of vCPUs (for example, `4` or `8-16` for a range).
+ **Memory (MiB)** - Specify the amount of memory in MiB (for example, `8192` or `16384-32768` for a range).
+ **Instance types** - Specify specific instance types (for example, `m5.large,m5.xlarge,c5.large`).
+ **CPU manufacturers** - Choose from `intel`, `amd`, or `amazon-web-services`.
+ **Accelerator types** - Specify accelerator types such as `gpu`, `fpga`, or `inference`.
+ **Accelerator count** - Specify the number of accelerators (for example, `1` or `2-4` for a range).
1. Under **Advanced configuration**, choose one of the following monitoring options:
+ To have CloudWatch send status-check metrics, choose **Basic**.
+ To have CloudWatch send all metrics metrics, choose **Detailed**.
1. (Optional) To help identify your capacity provider, expand **Tags**, and then configure your tags.
To enable tag propagation from capacity provider to managed resources such as instances launched from the capacity provider, for **Propagate tags from**, choose **Capacity provider**.
[Add a tag] Choose **Add tag** and do the following:
+ For **Key**, enter the key name.
+ For **Value**, enter the key value.
1. Choose **Create**.
## AWS CLI procedure
You can create a capacity provider for Amazon ECS Managed Instances using the AWS CLI. Use the latest version of the AWS CLI. For more information on how to upgrade to the latest version, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
**To create a capacity provider for Amazon ECS Managed Instances (AWS CLI)**
1. Run the following command:
```
aws ecs create-capacity-provider --cli-input-json file://capacity-provider-definition.json
```
The following `capacity-provider-definition.json` can be used to specify basic instance requirements, instance storage size, and enable tag propagation:
```
{
"name": "my-managed-instances-provider",
"cluster": "my-cluster",
"tags": [
{
"key": "version",
"value": "test"
}
],
"managedInstancesProvider": {
"infrastructureRoleArn": "arn:aws:iam::123456789012:role/ecsInfrastructureRole",
"instanceLaunchTemplate": {
"ec2InstanceProfileArn": "arn:aws:iam::123456789012:instance-profile/ecsInstanceRole",
"instanceRequirements": {
"vCpuCount": {
"min": 4,
"max": 8
},
"memoryMiB": {
"min": 8192,
"max": 16384
}
},
"networkConfiguration": {
"subnets": [
"subnet-abcdef01234567",
"subnet-bcdefa98765432"
],
"securityGroups": [
"sg-0123456789abcdef"
]
},
"storageConfiguration": {
"storageSizeGiB": 100
},
"monitoring": "basic"
},
"propagateTags": "CAPACITY_PROVIDER"
}
}
```
1. Verify that your capacity provider was created successfully:
```
aws ecs describe-capacity-providers \
--capacity-providers my-managed-instances-provider
```
## Next steps
After creating your capacity provider, you can use it when creating services or running tasks:
+ To use the capacity provider with a service, see [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md).
+ To use the capacity provider with standalone tasks, see [Running an application as an Amazon ECS task](standalone-task-create.md).
# Updating Amazon ECS Managed Instances monitoring
You can modify the monitoring option for your Amazon ECS Managed Instances capacity provider to change between basic and detailed monitoring. This allows you to adjust the level of monitoring data collected without recreating the capacity provider.
For more information about monitoring options, see [Monitoring Amazon ECS Managed Instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/monitoring-managed-instances.html).
## Console procedure
**To update monitoring for Amazon ECS Managed Instances (Amazon ECS console)**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, choose your cluster name.
1. On the cluster page, choose the **Infrastructure** tab.
1. Under **Advanced configuration**, choose one of the following monitoring options:
+ To have CloudWatch send status-check metrics, choose **Basic**.
+ To have CloudWatch send all metrics metrics, choose **Detailed**.
1. Choose **Update**.
To update tags associated with an existing Amazon ECS Managed Instances capacity provider, follow these steps:
1. In the navigation pane, choose **Clusters**.
1. On the clusters page, choose **Infrastructure**.
1. On the infrastructure page, choose the capacity provider that you created.
1. On the capacity provider page, choose **Tags**.
1. Under **Tags**, choose **Manage tags**.
1. To add a tag, specify the key and value of the tag that you want to add and then choose **Save**. To add multiple tags at once, choose **Add tag** for each tag that you want to add. You can add a maximum of 50 tags.
To remove a tag, choose **Remove**.
**Note**
If tag propagation is enabled, tags added or removed after capacity provider creation don't apply to resources previously created by the capacity provider.
## AWS CLI procedure
You can update a capacity provider for Amazon ECS Managed Instances using the AWS CLI. Use the latest version of the AWS CLI. For more information on how to upgrade to the latest version, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
**To update monitoring for Amazon ECS Managed Instances (AWS CLI)**
1. To enable detailed monitoring, use the following command:
```
aws ecs update-capacity-provider \
--name my-managed-instances-provider \
--managed-instances-provider '{
"instanceLaunchTemplateUpdate": {
"monitoring": "DETAILED"
}
}'
```
1. To enable basic monitoring, use the following command:
```
aws ecs update-capacity-provider \
--name my-managed-instances-provider \
--managed-instances-provider '{
"instanceLaunchTemplateUpdate": {
"monitoring": "BASIC"
}
}'
```
# Deleting an Amazon ECS Managed Instances capacity provider
If you are finished using an Amazon ECS Managed Instances capacity provider, you can delete it. After the group is deleted, the Amazon ECS Managed Instances 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 Amazon ECS Managed Instances 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 ECS Managed Instances 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 Amazon ECS Managed Instances capacity provider, and then choose **Delete**.
1. In the confirmation box, enter **delete *Amazon ECS Managed Instances capacity provider name***
1. Choose **Delete**.
# Safely stop Amazon ECS workloads running on Amazon ECS Managed Instances
You can use Amazon ECS task scale-in protection to protect your tasks from being terminated by scale-in events from either service scaling or deployments.
Certain applications require a mechanism to safeguard mission-critical tasks from termination by scale-in events during times of low utilization or during service deployments. For example:
+ You have a queue-processing asynchronous application such as a video transcoding job where some tasks need to run for hours even when cumulative service utilization is low.
+ You have a gaming application that runs game servers as tasks that need to continue running even if all users have logged-out to reduce start-up latency of a server reboot.
+ When you deploy a new code version, you need tasks to continue running because it would be expensive to reprocess.
To protect tasks that belong to your service from terminating in a scale-in event, set the `ProtectionEnabled` attribute to `true`. When you set `ProtectionEnabled` to true, tasks are protected for 2 hours by default. You can then customize the protection period by using the `ExpiresInMinutes` attribute. You can protect your tasks for a minimum of 1 minute and up to a maximum of 2880 minutes (48 hours). If you're using the AWS CLI, you can specify the `--protection-enabled` option.
After a task finishes its requisite work, you can set the `ProtectionEnabled` attribute to `false`, allowing the task to be terminated by subsequent scale-in events. If you're using the AWS CLI, you can specify the `--no-protection-enabled` option.
## Task scale-in protection mechanisms
You can set and get task scale-in protection using either the Amazon ECS container agent endpoint or the Amazon ECS API.
+ **Amazon ECS container agent endpoint**
We recommend using the Amazon ECS container agent endpoint for tasks that can self-determine the need to be protected. Use this approach for queue-based or job-processing workloads.
When a container starts processing work, for example by consuming an SQS message, you can set the `ProtectionEnabled` attribute through the task scale-in protection endpoint path `$ECS_AGENT_URI/task-protection/v1/state` from within the container. Amazon ECS will not terminate this task during scale-in events. After your task finishes its work, you can clear the `ProtectionEnabled` attribute using the same endpoint, making the task eligible for termination during subsequent scale-in events.
For more information about the Amazon ECS container agent endpoint, see [Amazon ECS task scale-in protection endpoint](managed-instance-task-scale-in-protection-endpoint.md).
+ **Amazon ECS API**
You can use the Amazon ECS API to set and retrieve task scale-in protection if your application has a component that tracks the status of active tasks. Use `UpdateTaskProtection` to mark one or more tasks as protected. Use `GetTaskProtection` to retrieve the protection status.
An example of this approach would be if your application is hosting game server sessions as Amazon ECS tasks. When a user logs in to a session on the server (task), you can mark the task as protected. After the user logs out, you can either clear the protection specifically for this task or periodically clear protection for similar tasks that no longer have active sessions, depending on your requirement to keep idle servers.
For more information, see [UpdateTaskProtection](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateTaskProtection.html) and [GetTaskProtection](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_GetTaskProtection.html) in the *Amazon Elastic Container Service API Reference*.
You can combine both approaches. For example, use the Amazon ECS agent endpoint to set task protection from within a container and use the Amazon ECS API to remove task protection from your external controller service.
## Considerations
Consider the following points before using task scale-in protection:
+ Task scale-in protection is only supported with tasks deployed from a service.
+ Task scale-in protection is supported with tasks deployed from a service running on Amazon ECS Managed Instances.
+ We recommend using the Amazon ECS container agent endpoint because the Amazon ECS agent has built-in retry mechanisms and a simpler interface.
+ You can reset the task scale-in protection expiration period by calling `UpdateTaskProtection` for a task that already has protection turned on.
+ Determine how long a task would need to complete its requisite work and set the `expiresInMinutes` property accordingly. If you set the protection expiration longer than necessary, then you will incur costs and face delays in the deployment of new tasks.
+ Deployment considerations:
+ If the service uses a rolling update, new tasks will be created but tasks running older version will not be terminated until `protectionEnabled` is cleared or expires. You can adjust the `maximumPercentage` parameter in deployment configuration to a value that allows new tasks to be created when old tasks are protected.
+ If you use CloudFormation, the update-stack has a 3 hour timeout. Therefore, if you set your task protection for longer than 3 hours, then your CloudFormation deployment may result in failure and rollback.
During the time your old tasks are protected, the CloudFormation stack shows `UPDATE_IN_PROGRESS`. If task scale-in protection is removed or expires within the 3 hour window, your deployment will succeed and move to the `UPDATE_COMPLETE` status. If the deployment is stuck in `UPDATE_IN_PROGRESS` for more than 3 hours, it will fail and show `UPDATE_FAILED` state, and will then be rolled back to old task set.
+ Amazon ECS sends service events when protected tasks keep a deployment (rolling or blue/green) from reaching the steady state, so that you can take remedial actions. While trying to update the protection status of a task, if you receive a `DEPLOYMENT_BLOCKED` error message, it means the service has more protected tasks than the desired count of tasks for the service. To resolve this error, do one the following:
+ Wait for the current task protection to expire. Then set task protection.
+ Determine which tasks can be stopped. Then use `UpdateTaskProtection`with the `protectionEnabled` option set to `false` for these tasks.
+ Increase the desired task count of the service to more than the number of protected tasks.
## IAM permissions required for task scale-in protection
The task must have the Amazon ECS task role with the following permissions:
+ `ecs:GetTaskProtection`: Allows the Amazon ECS container agent to call `GetTaskProtection`.
+ `ecs:UpdateTaskProtection`: Allows the Amazon ECS container agent to call `UpdateTaskProtection`.
# Amazon ECS task scale-in protection endpoint
The Amazon ECS container agent automatically injects the `ECS_AGENT_URI` environment variable into the containers of Amazon ECS tasks to provide a method to interact with the container agent API endpoint.
We recommend using the Amazon ECS container agent endpoint for tasks that can self-determine the need to be protected.
When a container starts processing work, you can set the `protectionEnabled` attribute using the task scale-in protection endpoint path `$ECS_AGENT_URI/task-protection/v1/state` from within the container.
Use a PUT request to this URI from within a container to set task scale-in protection. A GET request to this URI returns the current protection status of a task.
## Task scale-in protection request parameters
You can set task scale-in protection using the `${ECS_AGENT_URI}/task-protection/v1/state` endpoint with the following request parameters.
`ProtectionEnabled`
Specify `true` to mark a task for protection. Specify `false` to remove protection and make the task eligible for termination.
Type: Boolean
Required: Yes
`ExpiresInMinutes`
The number of minutes the task is protected. You can specify a minimum of 1 minute to up to 2,880 minutes (48 hours). During this time period, your task will not be terminated by scale-in events from service Auto Scaling or deployments. After this time period lapses, the `protectionEnabled` parameter is set to `false`.
If you don't specify the time, then the task is automatically protected for 120 minutes (2 hours).
Type: Integer
Required: No
The following examples show how to set task protection with different durations.
**Example of how to protect a task with the default time period**
This example shows how to protect a task with the default time period of 2 hours.
```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true}'
```
**Example of how to protect a task for 60 minutes**
This example shows how to protect a task for 60 minutes using the `expiresInMinutes` parameter.
```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":60}'
```
**Example of how to protect a task for 24 hours**
This example shows how to protect a task for 24 hours using the `expiresInMinutes` parameter.
```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":1440}'
```
The PUT request returns the following response.
```
{
"protection": {
"ExpirationDate": "2023-12-20T21:57:44.837Z",
"ProtectionEnabled": true,
"TaskArn": "arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
}
}
```
## Task scale-in protection response parameters
The following information is returned from the task scale-in protection endpoint `${ECS_AGENT_URI}/task-protection/v1/state` in the JSON response.
`ExpirationDate`
The epoch time when protection for the task will expire. If the task is not protected, this value is null.
`ProtectionEnabled`
The protection status of the task. If scale-in protection is enabled for a task, the value is `true`. Otherwise, it is `false`.
`TaskArn`
The full Amazon Resource Name (ARN) of the task that the container belongs to.
The following example shows the details returned for a protected task.
```
curl --request GET ${ECS_AGENT_URI}/task-protection/v1/state
```
```
{
"protection":{
"ExpirationDate":"2023-12-20T21:57:44Z",
"ProtectionEnabled":true,
"TaskArn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
}
}
```
The following information is returned when a failure occurs.
`Arn`
The full Amazon Resource Name (ARN) of the task.
`Detail`
The details related to the failure.
`Reason`
The reason for the failure.
The following example shows the details returned for a task that is not protected.
```
{
"failure":{
"Arn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0",
"Detail":null,
"Reason":"TASK_NOT_VALID"
}
}
```
The following information is returned when an exception occurs.
`requestID`
The AWS request ID for the Amazon ECS API call that results in an exception.
`Arn`
The full Amazon Resource Name (ARN) of the task or service.
`Code`
The error code.
`Message`
The error message.
If a `RequestError` or `RequestTimeout` error appears, it is likely that it's a networking issue. Try using VPC endpoints for Amazon ECS.
The following example shows the details returned when an error occurs.
```
{
"requestID":"12345-abc-6789-0123-abc",
"error":{
"Arn":"arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
"Code":"AccessDeniedException",
"Message":"User: arn:aws:sts::444455556666:assumed-role/my-ecs-task-role/1234567890abcdef0 is not authorized to perform: ecs:GetTaskProtection on resource: arn:aws:ecs:us-west-2:555555555555:task/test/1234567890abcdef0 because no identity-based policy allows the ecs:GetTaskProtection action"
}
}
```
The following error appears if the Amazon ECS agent is unable to get a response from the Amazon ECS endpoint for reasons such as network issues or the Amazon ECS control plane is down.
```
{
"error": {
"Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
"Code": "RequestCanceled",
"Message": "Timed out calling Amazon ECS Task Protection API"
}
}
```
The following error appears when the Amazon ECS agent gets a throttling exception from Amazon ECS.
```
{
"requestID": "12345-abc-6789-0123-abc",
"error": {
"Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
"Code": "ThrottlingException",
"Message": "Rate exceeded"
}
}
```
# Amazon ECS clusters for Fargate
With Amazon ECS on AWS Fargate capacity providers, you can use both Fargate and Fargate Spot capacity with your Amazon ECS tasks.
With Fargate Spot, you can run interruption tolerant Amazon ECS tasks at a rate that's discounted compared to the Fargate price. Fargate Spot runs tasks on spare compute capacity. When AWS needs the capacity back, your tasks are interrupted with a two-minute warning.
When tasks that use the Fargate and Fargate Spot capacity providers are stopped, the task state change event is sent to Amazon EventBridge. The stopped reason describes the cause. For more information, see [Amazon ECS task state change events](ecs_task_events.md).
A cluster can contain a mix of Fargate and Auto Scaling group capacity providers. However, a capacity provider strategy can only contain either Fargate or Auto Scaling group capacity providers, but not both. For more information, see [Auto Scaling Group Capacity Providers](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cluster-auto-scaling.html#asg-capacity-providers).
Consider the following when using capacity providers:
+ You must associate a capacity provider with a cluster before you associate it with the capacity provider strategy.
+ You can specify a maximum of 20 capacity providers for a capacity provider strategy.
+ You can't update a service using an Auto Scaling group capacity provider to use a Fargate capacity provider. The opposite is also the case.
+ In a capacity provider strategy, if no `weight` value is specified for a capacity provider in the console, then the default value of `1` is used. If using the API or AWS CLI, the default value of `0` is used.
+ When multiple capacity providers are specified within a capacity provider strategy, at least one of the capacity providers must have a weight value that's greater than zero. Any capacity providers with a weight of zero aren't used to place tasks. If you specify multiple capacity providers in a strategy with all the same weight of zero, then any `RunTask` or `CreateService` actions using the capacity provider strategy fail.
+ In a capacity provider strategy, only one capacity provider can have a defined *base* value. If no base value is specified, the default value of zero is used.
+ A cluster can contain a mix of both Auto Scaling group capacity providers and Fargate capacity providers. However, a capacity provider strategy can only contain Auto Scaling group, or Fargate capacity providers, but not both.
+ A cluster can contain a mix of services and standalone tasks that use both capacity providers. A service can be updated to use a capacity provider strategy rather than a launch type. However, you must force a new deployment when doing so.
## Fargate Spot termination notices
During periods of extremely high demand, Fargate Spot capacity might be unavailable. This can cause Fargate Spot tasks to be delayed. When this happens, Amazon ECS services retry launching tasks until the required capacity becomes available. Fargate doesn't replace Spot capacity with on-demand capacity.
When tasks using Fargate Spot capacity are stopped due to a Spot interruption, a two-minute warning is sent before a task is stopped. The warning is sent as a task state change event to Amazon EventBridge and as a SIGTERM signal to the running task. If you use Fargate Spot as part of a service, then in this scenario the service scheduler receives the interruption signal and attempts to launch additional tasks on Fargate Spot if there's capacity available. A service with only one task is interrupted until capacity is available. For more information about a graceful shutdown, see [Graceful shutdowns with ECS](https://aws.amazon.com/blogs/containers/graceful-shutdowns-with-ecs/).
To ensure that your containers exit gracefully before the task stops, you can configure the following:
+ A `stopTimeout` value of `120` seconds or less can be specified in the container definition that the task is using. The default `stopTimeout` value is 30 seconds. You can specify a longer `stopTimeout` value to give yourself more time between the moment that the task state change event is received and the point in time when the container is forcefully stopped. For more information, see [Container timeouts](task_definition_parameters.md#container_definition_timeout).
+ The SIGTERM signal must be received from within the container to perform any cleanup actions. Failure to process this signal results in the task receiving a SIGKILL signal after the configured `stopTimeout` and may result in data loss or corruption.
The following is a snippet of a task state change event. This snippet displays the stopped reason and stop code for a Fargate Spot interruption.
```
{
"version": "0",
"id": "9bcdac79-b31f-4d3d-9410-fbd727c29fab",
"detail-type": "ECS Task State Change",
"source": "aws.ecs",
"account": "111122223333",
"resources": [
"arn:aws:ecs:us-east-1:111122223333:task/b99d40b3-5176-4f71-9a52-9dbd6f1cebef"
],
"detail": {
"clusterArn": "arn:aws:ecs:us-east-1:111122223333:cluster/default",
"createdAt": "2016-12-06T16:41:05.702Z",
"desiredStatus": "STOPPED",
"lastStatus": "RUNNING",
"stoppedReason": "Your Spot Task was interrupted.",
"stopCode": "SpotInterruption",
"taskArn": "arn:aws:ecs:us-east-1:111122223333:task/b99d40b3-5176-4f71-9a52-9dbd6fEXAMPLE",
...
}
}
```
The following is an event pattern that's used to create an EventBridge rule for Amazon ECS task state change events. You can optionally specify a cluster in the `detail` field. Doing so means that you will receive task state change events for that cluster. For more information about creating an EventBridge rule, see [Getting started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html) in the *Amazon EventBridge User Guide*.
```
{
"source": [
"aws.ecs"
],
"detail-type": [
"ECS Task State Change"
],
"detail": {
"clusterArn": [
"arn:aws:ecs:us-west-2:111122223333:cluster/default"
]
}
}
```
# Creating an Amazon ECS cluster for Fargate workloads
You create a cluster to define the infrastructure your tasks and services run on.
Before you begin, be sure that you've completed the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) and assign the appropriate IAM permission. For more information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies). The Amazon ECS console creates the resources that are needed by an Amazon ECS cluster by creating a CloudFormation stack.
The console automatically associates the Fargate and Fargate Spot capacity providers with the cluster.
You can modify the following options:
+ Add a namespace to the cluster.
A namespace allows services that you create in the cluster can connect to the other services in the namespace without additional configuration. For more information, see [Interconnect Amazon ECS services](interconnecting-services.md).
+ Enable task events to receive EventBridge notifications for task state changes.
+ Add tags to help you identify your cluster.
+ Assign an AWS KMS key for your managed storage. For information about how to create a key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*.
+ Assign an AWS KMS key for your Fargate ephemeral storage. For information about how to create a key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*.
+ Configure the AWS KMS key and logging for ECS Exec.
## Procedure
**To create a new cluster (Amazon ECS console)**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, choose **Create cluster**.
1. Under **Cluster configuration**, configure the following:
+ For **Cluster name**, enter a unique name.
The name can contain up to 255 letters (uppercase and lowercase), numbers, and hyphens.
+ (Optional) To have the namespace used for Service Connect be different from the cluster name, under **Service Connect defaults**, for **Default namespace**, choose or enter a namespace name. To use a shared namespace, choose or enter a namespace ARN. For more information about using shared namespaces, see [Amazon ECS Service Connect with shared AWS Cloud Map namespaces](service-connect-shared-namespaces.md).
1. (Optional) Use Container Insights, expand **Monitoring**, and then choose one of the following options:
+ To use the recommended Container Insights with enhanced observability, choose **Container Insights with enhanced observability**.
+ To use Container Insights, choose **Container Insights**.
1. (Optional) To enable task events, expand **Task events**, and then turn on **Enable task events**.
When you enable task events, Amazon ECS sends task state change events to EventBridge. This allows you to monitor and respond to task lifecycle changes automatically.
1. (Optional) To use ECS Exec to debug tasks in the cluster, expand **Troubleshooting configuration**, and then configure the following:
+ (Optional) For **AWS KMS key for ECS Exec**, enter the ARN of the AWS KMS key you want to use to encrypt the ECS Exec session data.
+ (Optional) For **ECS Exec logging**, choose the log destination:
+ To send logs to CloudWatch Logs, choose **Amazon CloudWatch**.
+ To send logs to Amazon S3, choose **Amazon S3**.
+ To disable logging, choose **None**.
1. (Optional), Under **Encryption**, you can configure the following:
+ Encrypt your data on Fargate ephemeral storage. Under **Encryption**, for **Fargate ephemeral storage**, enter the ARN of the AWS KMS key you want to use to encrypt the Fargate ephemeral storage data.
+ Encrypt the data on managed storage. Under **Encryption**, for **Managed storage**, enter the ARN of the AWS KMS key you want to use to encrypt the managed storage data.
1. (Optional) To help identify your cluster, expand **Tags**, and then configure your tags.
[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**.
## Next steps
After you create the cluster, you can create task definitions for your applications and then run them as standalone tasks, or as part of a service. For more information, see the following:
+ [Amazon ECS task definitions](task_definitions.md)
+ [Running an application as an Amazon ECS task](standalone-task-create.md)
+ [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md)
# Amazon ECS capacity providers for EC2 workloads
When you use Amazon EC2 instances for your capacity, you use Auto Scaling groups to manage the Amazon EC2 instances registered to their clusters. Auto Scaling helps ensure that you have the correct number of Amazon EC2 instances available to handle the application load.
You can use the managed scaling feature to have Amazon ECS manage the scale-in and scale-out actions of the Auto Scaling group, or you can manage the scaling actions yourself. For more information, see [Automatically manage Amazon ECS capacity with cluster auto scaling](cluster-auto-scaling.md).
We recommend that you create a new empty Auto Scaling group. If you use an existing Auto Scaling group, any Amazon EC2 instances that are associated with the group that were already running and registered to an Amazon ECS cluster before the Auto Scaling group being used to create a capacity provider might not be properly registered with the capacity provider. This might cause issues when using the capacity provider in a capacity provider strategy. Use `DescribeContainerInstances` to confirm whether a container instance is associated with a capacity provider or not.
**Note**
To create an empty Auto Scaling group, set the desired count to zero. After you created the capacity provider and associated it with a cluster, you can then scale it out.
When you use the Amazon ECS console, Amazon ECS creates an Amazon EC2 launch template and Auto Scaling group on your behalf as part of the CloudFormation stack. They are prefixed with `EC2ContainerService-`. You can use the Auto Scaling group as a capacity provider for that cluster.
We recommend you use managed instance draining to allow for graceful termination of Amazon EC2 instances that won't disrupt your workloads. This feature is on by default. For more information, see [Safely stop Amazon ECS workloads running on EC2 instances](managed-instance-draining.md)
Consider the following when using Auto Scaling group capacity providers in the console:
+ An Auto Scaling group must have a `MaxSize` greater than zero to scale out.
+ The Auto Scaling group can't have instance weighting settings.
+ If the Auto Scaling group can't scale out to accommodate the number of tasks run, the tasks fails to transition beyond the `PROVISIONING` state.
+ Don't modify the scaling policy resource associated with your Auto Scaling groups that are managed by capacity providers.
+ If managed scaling is turned on when you create a capacity provider, the Auto Scaling group desired count can be set to `0`. When managed scaling is turned on, Amazon ECS manages the scale-in and scale-out actions of the Auto Scaling group.
+ You must associate capacity provider with a cluster before you associate it with the capacity provider strategy.
+ You can specify a maximum of 20 capacity providers for a capacity provider strategy.
+ You can't update a service using an Auto Scaling group capacity provider to use a Fargate capacity provider. The opposite is also the case.
+ In a capacity provider strategy, if no `weight` value is specified for a capacity provider in the console, then the default value of `1` is used. If using the API or AWS CLI, the default value of `0` is used.
+ When multiple capacity providers are specified within a capacity provider strategy, at least one of the capacity providers must have a weight value that's greater than zero. Any capacity providers with a weight of zero aren't used to place tasks. If you specify multiple capacity providers in a strategy with all the same weight of zero, then any `RunTask` or `CreateService` actions using the capacity provider strategy fail.
+ In a capacity provider strategy, only one capacity provider can have a defined *base* value. If no base value is specified, the default value of zero is used.
+ A cluster can contain a mix of both Auto Scaling group capacity providers and Fargate capacity providers. However, a capacity provider strategy can only contain Auto Scaling group or Fargate capacity providers, but not both.
+ A cluster can contain a mix of services and standalone tasks that use both capacity providers and launch types. A service can be updated to use a capacity provider strategy rather than a launch type. However, you must force a new deployment when doing so.
+ Amazon ECS supports Amazon EC2 Auto Scaling warm pools. A warm pool is a group of pre-initialized Amazon EC2 instances ready to be placed into service. Whenever your application needs to scale out, Amazon EC2 Auto Scaling uses the pre-initialized instances from the warm pool rather than launching cold instances. This allows for any final initialization process to run before the instance is placed into service. For more information, see [Configuring pre-initialized instances for your Amazon ECS Auto Scaling group](using-warm-pool.md).
For more information about creating an Amazon EC2 Auto Scaling launch template, see [Auto Scaling launch templates](https://docs.aws.amazon.com/autoscaling/ec2/userguide/launch-templates.html) in the *Amazon EC2 Auto Scaling User Guide*. For more information about creating an Amazon EC2 Auto Scaling group, see [Auto Scaling groups](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html) in the *Amazon EC2 Auto Scaling User Guide*.
# Amazon EC2 container instance security considerations for Amazon ECS
You should consider a single container instance and its access within your threat model. For example, a single affected task might be able to leverage the IAM permissions of a non-infected task on the same instance.
We recommend that you use the following to help prevent this:
+ Do not use administrator privileges when running your tasks.
+ Assign a task role with least-privileged access to your tasks.
The container agent automatically creates a token with a unique credential ID which are used to access Amazon ECS resources.
+ To prevent containers run by tasks that use the `awsvpc` network mode from accessing the credential information supplied to the Amazon EC2 instance profile, while still allowing the permissions that are provided by the task role set the `ECS_AWSVPC_BLOCK_IMDS` agent configuration variable to true in the agent configuration file and restart the agent.
+ Use Amazon GuardDuty Runtime Monitoring to detect threats for clusters and containers within your AWS environment. Runtime Monitoring uses a GuardDuty security agent that adds runtime visibility into individual Amazon ECS workloads, for example, file access, process execution, and network connections. For more information, see [GuardDuty Runtime Monitoring](https://docs.aws.amazon.com/guardduty/latest/ug/runtime-monitoring.html) in the *GuardDuty User Guide*.
# Creating an Amazon ECS cluster for Amazon EC2 workloads
You create a cluster to define the infrastructure your tasks and services run on.
Before you begin, be sure that you've completed the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) and assign the appropriate IAM permission. For more information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies). The Amazon ECS console provides a simple way to create the resources that are needed by an Amazon ECS cluster by creating a CloudFormation stack.
To make the cluster creation process as easy as possible, the console has default selections for many choices which we describe below. There are also help panels available for most of the sections in the console which provide further context.
You can register Amazon EC2 instances when you create the cluster or register additional instances with the cluster after it has been created.
You can modify the following default options:
+ Change the subnets where your instances launch.
+ Change the security groups used to control traffic to the container instances.
+ Add a namespace to the cluster.
A namespace allows services that you create in the cluster can connect to the other services in the namespace without additional configuration. For more information, see [Interconnect Amazon ECS services](interconnecting-services.md).
+ Enable task events to receive EventBridge notifications for task state changes.
+ Assign a AWS KMS key for your managed storage. For information about how to create a key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*.
+ Assign a AWS KMS key for your Fargate ephemeral storage. For information about how to create a key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*.
+ Configure the AWS KMS key and logging for ECS Exec.
+ Add tags to help you identify your cluster.
## Auto Scaling group options
When you use Amazon EC2 instances, you must specify an Auto Scaling group to manage the infrastructure that your tasks and services run on.
When you choose to create a new Auto Scaling group, it is automatically configured for the following behavior:
+ Amazon ECS manages the scale-in and scale-out actions of the Auto Scaling group.
+ Amazon ECS will not prevent Amazon EC2 instances that contain tasks and that are in an Auto Scaling group from being terminated during a scale-in action. For more information, see [Instance Protection](https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-instance-termination.html#instance-protection) in the *AWS Auto Scaling User Guide*.
You configure the following Auto Scaling group properties which determine the type and number of instances to launch for the group:
+ The Amazon ECS-optimized AMI.
+ The instance type.
+ The SSH key pair that proves your identity when you connect to the instance. For information about how to create SSH keys, see [Amazon EC2 key pairs and Linux instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) in the *Amazon EC2 User Guide*.
+ The minimum number of instances to launch for the Auto Scaling group.
+ The maximum number of instances that are started for the Auto Scaling group.
In order for the group to scale out, the maximum must be greater than 0.
Amazon ECS creates an Amazon EC2 Auto Scaling launch template and Auto Scaling group on your behalf as part of the CloudFormation stack. The values that you specified for the AMI, the instance types, and the SSH key pair are part of the launch template. The templates are prefixed with `EC2ContainerService-`, which makes them easy to identify. The Auto Scaling groups are prefixed with `-ECS-Infra-ECSAutoScalingGroup`.
Instances launched for the Auto Scaling group use the launch template.
## Networking options
By default instances are launched into the default subnets for the Region. The security groups, which control the traffic to your container instances, currently associated with the subnets are used. You can changed the subnets and security groups for the instances.
You can choose an existing subnet. You can either use an existing security group, or create a new one. To create tasks in an IPv6-only configuration, use subnets that include only an IPv6 CIDR block.
When you create a new security group, you need to specify at least one inbound rule.
The inbound rules determine what traffic can reach your container instances and include the following properties:
+ The protocol to allow
+ The range of ports to allow
+ The inbound traffic (source)
To allow inbound traffic from a specific address or CIDR block, use **Custom** for **Source** with the allowed CIDR.
To allow inbound traffic from all destinations, use **Anywhere** for **Source**. This automatically adds the 0.0.0.0/0 IPv4 CIDR block and ::/0 IPv6 CIDR block.
To allow inbound traffic from your local computer, use **Source group** for **Source**. This automatically adds the current IP address of your local computer as the allowed source.
**To create a new cluster (Amazon ECS console)**
Before you begin, assign the appropriate IAM permission. For more information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies).
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, choose **Create cluster**.
1. Under **Cluster configuration**, configure the following:
+ For **Cluster name**, enter a unique name.
The name can contain up to 255 letters (uppercase and lowercase), numbers, and hyphens.
+ (Optional) To have the namespace used for Service Connect be different from the cluster name, under **Service Connect defaults**, for **Default namespace**, choose or enter a namespace name. To use a shared namespace, choose or enter a namespace ARN. For more information about using shared namespaces, see [Amazon ECS Service Connect with shared AWS Cloud Map namespaces](service-connect-shared-namespaces.md).
1. Add Amazon EC2 instances to your cluster, expand **Infrastructure** and then select **Fargate and Self-managed instances**.
Next, configure the Auto Scaling group which acts as the capacity provider:
1. To using an existing Auto Scaling group, from **Auto Scaling group (ASG)**, select the group.
1. To create a Auto Scaling group, from **Auto Scaling group (ASG)**, select **Create new group**, and then provide the following details about the group:
+ For **Provisioning model**, choose whether to use **On-demand** instances or **Spot** Instances.
+ If you choose to use Spot Instances, for **Allocation Strategy**, choose what Spot capacity pools (instance types and Availability Zones) are used for the instances.
For most workloads, you can choose **Price capacity optimized**.
For more information, see [Allocation strategies for Spot Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-fleet-allocation-strategy.html) in the *Amazon EC2 User Guide*.
+ For **Container instance Amazon Machine Image (AMI)**, choose the Amazon ECS-optimized AMI for the Auto Scaling group instances.
+ For **EC2 instance type**, choose the instance type for your workloads.
Managed scaling works best if your Auto Scaling group uses the same or similar instance types.
+ For **EC2 instance role**, choose an existing container instance role, or you can create a new one.
For more information, see [Amazon ECS container instance IAM role](instance_IAM_role.md).
+ For **Capacity**, enter the minimum number and the maximum number of instances to launch in the Auto Scaling group.
+ For **SSH key pair**, choose the pair that proves your identity when you connect to the instance.
+ To allow for larger image and storage, for **Root EBS volume size**, enter the value in GiB.
1. (Optional) To change the VPC and subnets, under **Networking for Amazon EC2 instances**, perform any of the following operations:
+ To remove a subnet, under **Subnets**, choose **X** for each subnet that you want to remove.
+ To change to a VPC other than the **default** VPC, under **VPC**, choose an existing **VPC**, and then under **Subnets**, choose the subnets. For an IPv6-only configuration, choose a VPC that has an IPv6 CIDR block and subnets that have only an IPv6 CIDR block.
+ Choose the security groups. Under **Security group**, choose one of the following options:
+ To use an existing security group, choose **Use an existing security group**, and then choose the security group.
+ To create a security group, choose **Create a new security group**. Then, choose **Add rule** for each inbound rule.
For information about inbound rules, see [Networking options](#networking-options).
+ To automatically assign public IP addresses to your Amazon EC2 container instances, for **Auto-assign public IP**, choose one of the following options:
+ **Use subnet setting** – Assign a public IP address to the instances when the subnet that the instances launch in are a public subnet.
+ **Turn on** – Assign a public IP address to the instances.
1. (Optional) Use Container Insights, expand **Monitoring**, and then choose one of the following options:
+ To use the recommended Container Insights with enhanced observability, choose **Container Insights with enhanced observability**.
+ To use Container Insights, choose **Container Insights**.
1. (Optional) To enable task events, expand **Task events**, and then turn on **Enable task events**.
When you enable task events, Amazon ECS sends task state change events to EventBridge. This allows you to monitor and respond to task lifecycle changes automatically.
1. (Optional) To use ECS Exec to debug tasks in the cluster, expand **Troubleshooting configuration**, and then configure the following:
+ (Optional) For **AWS KMS key for ECS Exec**, enter the ARN of the AWS KMS key you want to use to encrypt the ECS Exec session data.
+ (Optional) For **ECS Exec logging**, choose the log destination:
+ To send logs to CloudWatch Logs, choose **Amazon CloudWatch**.
+ To send logs to Amazon S3, choose **Amazon S3**.
+ To disable logging, choose **None**.
1. (Optional)
If you use Runtime Monitoring with the manual option and you want to have this cluster monitored by GuardDuty, choose **Add tag** and do the following:
+ For **Key**, enter **guardDutyRuntimeMonitoringManaged**
+ For **Value**, enter **true**.
1. (Optional) Encrypt the data on managed storage. Under **Encryption**, for **Managed storage**, enter the ARN of the AWS KMS key you want to use to encrypt the managed storage data.
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**.
## Next steps
After you create the cluster, you can create task definitions for your applications and then run them as standalone tasks, or as part of a service. For more information, see the following:
+ [Amazon ECS task definitions](task_definitions.md)
+ [Running an application as an Amazon ECS task](standalone-task-create.md)
+ [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md)
# 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**.
# Amazon EC2 container instances for Amazon ECS
An Amazon ECS container instance is an Amazon EC2 instance that run the Amazon ECS container agent and is registered to a cluster. When you run tasks with Amazon ECS using the capacity provider, External capacity provider or an Auto Scaling group capacity provider, your tasks are placed on your active container instances. You are responsible for the container instance management and maintenance.
Although you can create your own Amazon EC2 instance AMI that meets the basic specifications needed to run your containerized workloads on Amazon ECS, the Amazon ECS-optimized AMIs are preconfigured and tested on Amazon ECS by AWS engineers. It is the simplest way for you to get started and to get your containers running on AWS quickly.
When you create a cluster using the console, Amazon ECS creates a launch template for your instances with the latest AMI associated with the selected operating system.
When you use CloudFormation to create a cluster, the SSM parameter is part of the Amazon EC2 launch template for the Auto Scaling group instances. You can configure the template to use a dynamic Systems Manager parameter to determine what Amazon ECS Optimized AMI to deploy. This parameter ensures that each time you deploy the stack it will check to see if there is available update that needs to be applied to the EC2 instances. For an example of how to use the Systems Manager parameter, see [Create an Amazon ECS cluster with the Amazon ECS-optimized Amazon Linux 2023 AMI](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-cluster.html#aws-resource-ecs-cluster--examples--Create_an_cluster_with_the_Amazon_Linux_2023_ECS-Optimized-AMI) in the *AWS CloudFormation User Guide*.
+ [Retrieving Amazon ECS-optimized Linux AMI metadata](retrieve-ecs-optimized_AMI.md)
+ [Retrieving Amazon ECS-optimized Bottlerocket AMI metadata](ecs-bottlerocket-retrieve-ami.md)
+ [Retrieving Amazon ECS-optimized Windows AMI metadata](retrieve-ecs-optimized_windows_AMI.md)
You can choose from the instance types that are compatible with your application. With larger instances, you can launch more tasks at the same time. With smaller instances, you can scale out in a more fine-grained way to save costs. You don't need to choose a single Amazon EC2 instance type that to fit all the applications in your cluster. Instead, you can create multiple Auto Scaling groups where each group has a different instance type. Then, you can create an Amazon EC2 capacity provider for each one of these groups.
Use the following guidelines to determine the instance family types and instance type to use:
+ Eliminate the instance types or instance families that don't meet the specific requirements of your application. For example, if your application requires a GPU, you can exclude any instance types that don't have a GPU.
+ Consider requirements including network throughput and storage.
+ Consider the CPU and memory. As a general rule, the CPU and memory must be large enough to hold at least one replica of the task that you want to run.
## Spot Instances
Spot capacity can provide significant cost savings over on-demand instances. Spot capacity is excess capacity that's priced significantly lower than on-demand or reserved capacity. Spot capacity is suitable for batch processing and machine-learning workloads, and development and staging environments. More generally, it's suitable for any workload that tolerates temporary downtime.
Understand that the following consequences because Spot capacity might not be available all the time.
+ During periods of extremely high demand, Spot capacity might be unavailable. This can cause Amazon EC2 Spot instance launches to be delayed. In these events, Amazon ECS services retry launching tasks, and Amazon EC2 Auto Scaling groups also retry launching instances, until the required capacity becomes available. Amazon EC2 doesn't replace Spot capacity with on-demand capacity.
+ When the overall demand for capacity increases, Spot Instances and tasks might be terminated with only a two-minute warning. After the warning is sent, tasks should begin an orderly shutdown if necessary before the instance is fully terminated. This helps minimize the possibility of errors. For more information about a graceful shutdown, see [Graceful shutdowns with ECS](https://aws.amazon.com/blogs/containers/graceful-shutdowns-with-ecs/).
To help minimize Spot capacity shortages, consider the following recommendations:
+ Use multiple Regions and Availability Zones - Spot capacity varies by Region and Availability Zone. You can improve Spot availability by running your workloads in multiple Regions and Availability Zones. If possible, specify subnets in all the Availability Zones in the Regions where you run your tasks and instances.
+ Use multiple Amazon EC2 instance types - When you use Mixed Instance Policies with Amazon EC2 Auto Scaling, multiple instance types are launched into your Auto Scaling Group. This ensures that a request for Spot capacity can be fulfilled when needed. To maximize reliability and minimize complexity, use instance types with roughly the same amount of CPU and memory in your Mixed Instances Policy. These instances can be from a different generation, or variants of the same base instance type. Note that they might come with additional features that you might not require. An example of such a list could include m4.large, m5.large, m5a.large, m5d.large, m5n.large, m5dn.large, and m5ad.large. For more information, see [Auto Scaling groups with multiple instance types and purchase options](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-mixed-instances-groups.html) in the *Amazon EC2 Auto Scaling User Guide*.
+ Use the capacity-optimized Spot allocation strategy - With Amazon EC2 Spot, you can choose between the capacity- and cost-optimized allocation strategies. If you choose the capacity-optimized strategy when launching a new instance, Amazon EC2 Spot selects the instance type with the greatest availability in the selected Availability Zone. This helps reduce the possibility that the instance is terminated soon after it launches.
For information about how to configure spot termination notices on your container instances, see:
+ [Configuring Amazon ECS Linux container instances to receive Spot Instance notices](spot-instance-draining-linux-container.md)
+ [Configuring Amazon ECS Windows container instances to receive Spot Instance notices](windows-spot-instance-draining-container.md)
# Amazon ECS-optimized Linux AMIs
**Important**
The Amazon ECS-Optimized Amazon Linux 2 AMI reaches end-of-life on June 30, 2026, mirroring the same EOL date of the upstream Amazon Linux 2 operating system (for more information, see the [Amazon Linux 2 FAQs](https://aws.amazon.com/amazon-linux-2/faqs/)). We encourage customers to upgrade their applications to use Amazon Linux 2023, which includes long term support through 2028. For information about migrating from Amazon Linux 2 to Amazon Linux 2023, see [Migrating from the Amazon Linux 2 Amazon ECS-optimized AMI to the Amazon Linux 2023 Amazon ECS-optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/al2-to-al2023-ami-transition.html).
By default, the deprecation date of all Amazon ECS-optimized AMIs are set to two years after the AMI creation date. You can use the Amazon EC2 `DescribeImages` API to check the deprecation status and date of an AMI. For more information, see [DescribeImages](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html) in the *Amazon Elastic Compute Cloud API Reference*.
Amazon ECS provides the Amazon ECS-optimized AMIs that are preconfigured with the requirements and recommendations to run your container workloads. We recommend that you use the Amazon ECS-optimized Amazon Linux 2023 AMI for your Amazon EC2 instances. Launching your container instances from the most recent Amazon ECS-Optimized AMI ensures that you receive the current security updates and container agent version. For information about how to launch an instance, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
When you create a cluster using the console, Amazon ECS creates a launch template for your instances with the latest AMI associated with the selected operating system.
When you use CloudFormation to create a cluster, the SSM parameter is part of the Amazon EC2 launch template for the Auto Scaling group instances. You can configure the template to use a dynamic Systems Manager parameter to determine what Amazon ECS Optimized AMI to deploy. This parameter ensures that each time you deploy the stack it will check to see if there is available update that needs to be applied to the EC2 instances. For an example of how to use the Systems Manager parameter, see [Create an Amazon ECS cluster with the Amazon ECS-optimized Amazon Linux 2023 AMI](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-cluster.html#aws-resource-ecs-cluster--examples--Create_an_cluster_with_the_Amazon_Linux_2023_ECS-Optimized-AMI) in the *AWS CloudFormation User Guide*.
If you need to customize the Amazon ECS-optimized AMI, see [Amazon ECS Optimized AMI Build Recipes](https://github.com/aws/amazon-ecs-ami) on GitHub.
The following variants of the Amazon ECS-optimized AMI are available for your Amazon EC2 instances with the Amazon Linux 2023 operating system.
| Operating system | AMI | Description | Storage configuration |
| --- | --- | --- | --- |
| Amazon Linux 2023 | Amazon ECS-optimized Amazon Linux 2023 AMI | Amazon Linux 2023 is the next generation of Amazon Linux from AWS. For most cases, recommended for launching your Amazon EC2 instances for your Amazon ECS workloads. For more information, see [What is Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/what-is-amazon-linux.html) in the *Amazon Linux 2023 User Guide*. | By default, the Amazon ECS-optimized Amazon Linux 2023 AMI ships with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2023 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| Amazon Linux 2023 (arm64) | Amazon ECS-optimized Amazon Linux 2023 (arm64) AMI | Based on Amazon Linux 2023, this AMI is recommended for use when launching your Amazon EC2 instances, which are powered by Arm-based AWS Graviton/Graviton 2/Graviton 3/Graviton 4 Processors, for your Amazon ECS workloads. For more information, see [Specifications for the Amazon EC2 general purpose instances](https://docs.aws.amazon.com/ec2/latest/instancetypes/gp.html) in the *Amazon EC2 Instance Types guide*. | By default, the Amazon ECS-optimized Amazon Linux 2023 AMI ships with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2023 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| Amazon Linux 2023 (Neuron) | Amazon ECS-optimized Amazon Linux 2023 AMI | Based on Amazon Linux 2023, this AMIis for Amazon EC2 Inf1, Trn1 or Inf2 instances. It comes pre-configured with AWS Inferentia and AWS Trainium drivers and the AWS Neuron runtime for Docker which makes running machine learning inference workloads easier on Amazon ECS. For more information, see [Amazon ECS task definitions for AWS Neuron machine learning workloads](ecs-inference.md). The Amazon ECS-optimized Amazon Linux 2023 (Neuron) AMI does not come with the AWS CLI preinstalled. | By default, the Amazon ECS-optimized Amazon Linux 2023 AMI ships with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2023 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| Amazon Linux 2023 GPU | Amazon ECS optimized Amazon Linux 2023 GPU AMI | Based on Amazon Linux 2023, this AMI is recommended for use when launching your Amazon EC2 GPU-based instances for your Amazon ECS workloads. It comes pre-configured with NVIDIA kernel drivers and a Docker GPU runtime which makes running workloads that take advantage of GPUs on Amazon ECS. For more information, see [Amazon ECS task definitions for GPU workloads](ecs-gpu.md). | By default, the Amazon ECS-optimized Amazon Linux 2023 AMI ships with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2023 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
The following variants of the Amazon ECS-optimized AMI are available for your Amazon EC2 instances with the Amazon Linux 2 operating system.
| Operating system | AMI | Description | Storage configuration |
| --- | --- | --- | --- |
| **Amazon Linux 2** | Amazon ECS-optimized Amazon Linux 2 kernel 5.10 AMI | Based on Amazon Linux 2, this AMI is for use when launching your Amazon EC2 instances and you want to use Linux kernel 5.10 instead of kernel 4.14 for your Amazon ECS workloads. The Amazon ECS-optimized Amazon Linux 2 kernel 5.10 AMI does not come with the AWS CLI preinstalled. | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| **Amazon Linux 2** | Amazon ECS-optimized Amazon Linux 2 AMI | This is for your Amazon ECS workloads. The Amazon ECS-optimized Amazon Linux 2 AMI does not come with the AWS CLI preinstalled. | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| **Amazon Linux 2 (arm64)** | Amazon ECS-optimized Amazon Linux 2 kernel 5.10 (arm64) AMI | Based on Amazon Linux 2, this AMI is for your Amazon EC2 instances, which are powered by Arm-based AWS Graviton/Graviton 2/Graviton 3/Graviton 4 Processors, and you want to use Linux kernel 5.10 instead of Linux kernel 4.14 for your Amazon ECS workloads. For more information, see [Specifications for Amazon EC2 general purpose instances](https://docs.aws.amazon.com/ec2/latest/instancetypes/gp.html) in the *Amazon EC2 Instance Types guide*. The Amazon ECS-optimized Amazon Linux 2 (arm64) AMI does not come with the AWS CLI preinstalled. | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| Amazon Linux 2 (arm64) | Amazon ECS-optimized Amazon Linux 2 (arm64) AMI | Based on Amazon Linux 2, this AMI is for use when launching your Amazon EC2 instances, which are powered by Arm-based AWS Graviton/Graviton 2/Graviton 3/Graviton 4 Processors, for your Amazon ECS workloads. The Amazon ECS-optimized Amazon Linux 2 (arm64) AMI does not come with the AWS CLI preinstalled. | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| **Amazon Linux 2 (GPU)** | Amazon ECS GPU-optimized kernel 5.10 AMI | Based on Amazon Linux 2, this AMI is recommended for use when launching your Amazon EC2 GPU-based instances with Linux kernel 5.10 for your Amazon ECS workloads. It comes pre-configured with NVIDIA kernel drivers and a Docker GPU runtime which makes running workloads that take advantage of GPUs on Amazon ECS. For more information, see [Amazon ECS task definitions for GPU workloads](ecs-gpu.md). | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| Amazon Linux 2 (GPU) | Amazon ECS GPU-optimized AMI | Based on Amazon Linux 2, this AMI is recommended for use when launching your Amazon EC2 GPU-based instances with Linux kernel 4.14 for your Amazon ECS workloads. It comes pre-configured with NVIDIA kernel drivers and a Docker GPU runtime which makes running workloads that take advantage of GPUs on Amazon ECS. For more information, see [Amazon ECS task definitions for GPU workloads](ecs-gpu.md). | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| Amazon Linux 2 (Neuron) | Amazon ECS optimized Amazon Linux 2 (Neuron) kernel 5.10 AMI | Based on Amazon Linux 2, this AMI is for Amazon EC2 Inf1, Trn1 or Inf2 instances. It comes pre-configured with AWS Inferentia with Linux kernel 5.10 and AWS Trainium drivers and the AWS Neuron runtime for Docker which makes running machine learning inference workloads easier on Amazon ECS. For more information, see [Amazon ECS task definitions for AWS Neuron machine learning workloads](ecs-inference.md). The Amazon ECS optimized Amazon Linux 2 (Neuron) AMI does not come with the AWS CLI preinstalled. | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
| Amazon Linux 2 (Neuron) | Amazon ECS optimized Amazon Linux 2 (Neuron) AMI | Based on Amazon Linux 2, this AMI is for Amazon EC2 Inf1, Trn1 or Inf2 instances. It comes pre-configured with AWS Inferentia and AWS Trainium drivers and the AWS Neuron runtime for Docker which makes running machine learning inference workloads easier on Amazon ECS. For more information, see [Amazon ECS task definitions for AWS Neuron machine learning workloads](ecs-inference.md). The Amazon ECS optimized Amazon Linux 2 (Neuron) AMI does not come with the AWS CLI preinstalled. | By default, the Amazon Linux 2-based Amazon ECS-optimized AMIs (Amazon ECS-optimized Amazon Linux 2 AMI, Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, and Amazon ECS GPU-optimized AMI) ship with a single 30-GiB root volume. You can modify the 30-GiB root volume size at launch time to increase the available storage on your container instance. This storage is used for the operating system and for Docker images and metadata. The default filesystem for the Amazon ECS-optimized Amazon Linux 2 AMI is `xfs`, and Docker uses the `overlay2` storage driver. For more information, see [Use the OverlayFS storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) in the Docker documentation. |
Amazon ECS provides a changelog for the Linux variant of the Amazon ECS-optimized AMI on GitHub. For more information, see [Changelog](https://github.com/aws/amazon-ecs-ami/blob/main/CHANGELOG.md).
The Linux variants of the Amazon ECS-optimized AMI use the Amazon Linux 2 AMI or Amazon Linux 2023 AMI as their base. You can retrieve the AMI name for each variant by querying the Systems Manager Parameter Store API. For more information, see [Retrieving Amazon ECS-optimized Linux AMI metadata](retrieve-ecs-optimized_AMI.md). The Amazon Linux 2 AMI release notes are available as well. For more information, see [Amazon Linux 2 release notes](https://docs.aws.amazon.com/AL2/latest/relnotes/relnotes-al2.html). The Amazon Linux 2023 release notes are available as well. For more information see, [Amazon Linux 2023 release notes](https://docs.aws.amazon.com/linux/al2023/release-notes/relnotes.html).
The following pages provide additional information about the changes:
+ [Source AMI release](https://github.com/aws/amazon-ecs-ami/releases) notes on GitHub
+ [Docker Engine release notes](https://docs.docker.com/engine/release-notes/) in the Docker documentation
+ [NVIDIA Driver Documentation](https://docs.nvidia.com/datacenter/tesla/index.html) in the NVIDIA documentation
+ [Amazon ECS agent changelog](https://github.com/aws/amazon-ecs-agent/blob/master/CHANGELOG.md) on GitHub
The source code for the `ecs-init` application and the scripts and configuration for packaging the agent are now part of the agent repository. For older versions of `ecs-init` and packaging, see [Amazon ecs-init changelog](https://github.com/aws/amazon-ecs-init/blob/master/CHANGELOG.md) on GitHub
## Applying security updates to the Amazon ECS-optimized AMI
The Amazon ECS-optimized AMIs based on Amazon Linux contain a customized version of cloud-init. Cloud-init is a package that is used to bootstrap Linux images in a cloud computing environment and perform desired actions when launching an instance. By default, all Amazon ECS-optimized AMIs based on Amazon Linux released before June 12, 2024 have all "Critical" and "Important" security updates applied upon instance launch.
Beginning with the June 12, 2024 releases of the Amazon ECS-optimized AMIs based on Amazon Linux 2, the default behavior will no longer include updating packages at launch. Instead, we recommend that you update to a new Amazon ECS-optimized AMI as releases are made available. The Amazon ECS-optimized AMIs are released when there are available security updates or base AMI changes. This will ensure you are receiving the latest package versions and security updates, and that the package versions are immutable through instance launches. For more information on retrieving the latest Amazon ECS-optimized AMI, see [Retrieving Amazon ECS-optimized Linux AMI metadata](retrieve-ecs-optimized_AMI.md).
We recommend automating your environment to update to a new AMI as they are made available. For information about the available options, see [Amazon ECS enables easier EC2 capacity management, with managed instance draining](https://aws.amazon.com/blogs/containers/amazon-ecs-enables-easier-ec2-capacity-management-with-managed-instance-draining/).
To continue applying "Critical" and "Important" security updates manually on an AMI version, you can run the following command on your Amazon EC2 instance.
```
yum update --security
```
**Warning**
Updating docker or containerd packages will stop all running containers on the host, which means all running Amazon ECS tasks will be stopped. Plan accordingly to minimize service disruption.
If you want to re-enable security updates at launch, you can add the following line to the `#cloud-config` section of the cloud-init user data when launching your Amazon EC2 instance. For more information, see [Using cloud-init on Amazon Linux 2](https://docs.aws.amazon.com/linux/al2/ug/amazon-linux-cloud-init.html) in the *Amazon Linux User Guide*.
```
#cloud-config
repo_upgrade: security
```
## Version-locked packages in Amazon ECS-optimized AL2023 GPU AMIs
Certain packages are critical for correct, performant behavior of GPU functionality in Amazon ECS-optimized AL2023 GPU AMIs. These include:
+ NVIDIA drivers (`nvidia*`)
+ Kernel modules (`kmod*`)
+ NVIDIA libraries (`libnvidia*`)
+ Kernel packages (`kernel*`)
**Note**
This is not an exhaustive list. The complete list of locked packages are available with `dnf versionlock list`
These packages are version-locked to ensure stability and prevent unintentional changes that could disrupt GPU workloads. As a result, these packages should generally be modified within the bounds of a managed process that gracefully handles potential issues and maintains GPU functionality.
To prevent unintended modifications, the `dnf versionlock` plugin is used on these packages.
If you wish to modify a locked package, you can:
```
# unlock a single package
sudo dnf versionlock delete $PACKAGE_NAME
# unlock all packages
sudo dnf versionlock clear
```
**Important**
When updates to these packages are necessary, customers should consider using the latest AMI version that includes the required updates. If updating existing instances is required, a careful approach involving unlocking, updating, and re-locking packages should be employed, always ensuring GPU functionality is maintained throughout the process.
# Retrieving Amazon ECS-optimized Linux AMI metadata
You can programmatically retrieve the Amazon ECS-optimized AMI metadata. The metadata includes the AMI name, Amazon ECS container agent version, and Amazon ECS runtime version which includes the Docker version.
When you create a cluster using the console, Amazon ECS creates a launch template for your instances with the latest AMI associated with the selected operating system.
When you use CloudFormation to create a cluster, the SSM parameter is part of the Amazon EC2 launch template for the Auto Scaling group instances. You can configure the template to use a dynamic Systems Manager parameter to determine what Amazon ECS Optimized AMI to deploy. This parameter ensures that each time you deploy the stack it will check to see if there is available update that needs to be applied to the EC2 instances. For an example of how to use the Systems Manager parameter, see [Create an Amazon ECS cluster with the Amazon ECS-optimized Amazon Linux 2023 AMI](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-cluster.html#aws-resource-ecs-cluster--examples--Create_an_cluster_with_the_Amazon_Linux_2023_ECS-Optimized-AMI) in the *AWS CloudFormation User Guide*.
The AMI ID, image name, operating system, container agent version, source image name, and runtime version for each variant of the Amazon ECS-optimized AMIs can be programmatically retrieved by querying the Systems Manager Parameter Store API. For more information about the Systems Manager Parameter Store API, see [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html) and [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html).
**Note**
Your administrative user must have the following IAM permissions to retrieve the Amazon ECS-optimized AMI metadata. These permissions have been added to the `AmazonECS_FullAccess` IAM policy.
ssm:GetParameters
ssm:GetParameter
ssm:GetParametersByPath
## Systems Manager Parameter Store parameter format
The following is the format of the parameter name for each Amazon ECS-optimized AMI variant.
**Linux Amazon ECS-optimized AMIs**
+ Amazon Linux 2023 AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2023/
```
+ Amazon Linux 2023 (arm64) AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2023/arm64/
```
+ Amazon Linux 2023 (Neuron) AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2023/neuron/
```
+ Amazon Linux 2023 (GPU) AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2023/gpu/
```
Amazon Linux 2 AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/
```
+ Amazon Linux 2 kernel 5.10 AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/
```
+ Amazon Linux 2 (arm64) AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/arm64/
```
+ Amazon Linux 2 kernel 5.10 (arm64) AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/arm64/
```
+ Amazon ECS GPU-optimized kernel 5.10 AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/gpu/
```
+ Amazon Linux 2 (GPU) AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/
```
+ Amazon ECS optimized Amazon Linux 2 (Neuron) kernel 5.10 AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/inf/
```
+ Amazon Linux 2 (Neuron) AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/inf/
```
The following parameter name format retrieves the image ID of the latest recommended Amazon ECS-optimized Amazon Linux 2 AMI by using the sub-parameter `image_id`.
```
/aws/service/ecs/optimized-ami/amazon-linux-2/recommended/image_id
```
The following parameter name format retrieves the metadata of a specific Amazon ECS-optimized AMI version by specifying the AMI name.
+ Amazon ECS-optimized Amazon Linux 2 AMI metadata:
```
/aws/service/ecs/optimized-ami/amazon-linux-2/amzn2-ami-ecs-hvm-2.0.20181112-x86_64-ebs
```
**Note**
All versions of the Amazon ECS-optimized Amazon Linux 2 AMI are available for retrieval. Only Amazon ECS-optimized AMI versions `amzn-ami-2017.09.l-amazon-ecs-optimized` (Linux) and later can be retrieved.
## Examples
The following examples show ways in which you can retrieve the metadata for each Amazon ECS-optimized AMI variant.
### Retrieving the metadata of the latest recommended Amazon ECS-optimized AMI
You can retrieve the latest recommended Amazon ECS-optimized AMI using the AWS CLI with the following AWS CLI commands.
**Linux Amazon ECS-optimized AMIs**
+ **For the Amazon ECS-optimized Amazon Linux 2023 AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/recommended --region us-east-1
```
+ **For the Amazon ECS-optimized Amazon Linux 2023 (arm64) AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/arm64/recommended --region us-east-1
```
+ **For the Amazon ECS-optimized Amazon Linux 2023 (Neuron) AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/neuron/recommended --region us-east-1
```
+ **For the Amazon ECS-optimized Amazon Linux 2023 GPU AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/gpu/recommended --region us-east-1
```
+ **For the Amazon ECS-optimized Amazon Linux 2 kernel 5.10 AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/recommended --region us-east-1
```
+ **For the Amazon ECS-optimized Amazon Linux 2 AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended --region us-east-1
```
+ **For the Amazon ECS-optimized Amazon Linux 2 kernel 5.10 (arm64) AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/arm64/recommended --region us-east-1
```
+ **For the Amazon ECS-optimized Amazon Linux 2 (arm64) AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/arm64/recommended --region us-east-1
```
+ **For the Amazon ECS GPU-optimized kernel 5.10 AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/gpu/recommended --region us-east-1
```
+ **For the Amazon ECS GPU-optimized AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended --region us-east-1
```
+ **For the Amazon ECS optimized Amazon Linux 2 (Neuron) kernel 5.10 AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/inf/recommended --region us-east-1
```
+ **For the Amazon ECS optimized Amazon Linux 2 (Neuron) AMIs:**
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/inf/recommended --region us-east-1
```
### Retrieving the image ID of the latest recommended Amazon ECS-optimized Amazon Linux 2023 AMI
You can retrieve the image ID of the latest recommended Amazon ECS-optimized Amazon Linux 2023 AMI ID by using the sub-parameter `image_id`.
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/recommended/image_id --region us-east-1
```
To retrieve the `image_id` value only, you can query the specific parameter value; for example:
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/recommended/image_id --region us-east-1 --query "Parameters[0].Value"
```
### Retrieving the metadata of a specific Amazon ECS-optimized Amazon Linux 2 AMI version
Retrieve the metadata of a specific Amazon ECS-optimized Amazon Linux AMI version using the AWS CLI with the following AWS CLI command. Replace the AMI name with the name of the Amazon ECS-optimized Amazon Linux AMI to retrieve.
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/amzn2-ami-ecs-hvm-2.0.20200928-x86_64-ebs --region us-east-1
```
### Retrieving the Amazon ECS-optimized Amazon Linux 2 kernel 5.10 AMI metadata using the Systems Manager GetParametersByPath API
Retrieve the Amazon ECS-optimized Amazon Linux 2 AMI metadata with the Systems Manager GetParametersByPath API using the AWS CLI with the following command.
```
aws ssm get-parameters-by-path --path /aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/ --region us-east-1
```
### Retrieving the image ID of the latest recommended Amazon ECS-optimized Amazon Linux 2 kernel 5.10 AMI
You can retrieve the image ID of the latest recommended Amazon ECS-optimized Amazon Linux 2 kernel 5.10 AMI ID by using the sub-parameter `image_id`.
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/recommended/image_id --region us-east-1
```
To retrieve the `image_id` value only, you can query the specific parameter value; for example:
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended/image_id --region us-east-1 --query "Parameters[0].Value"
```
### Using the latest recommended Amazon ECS-optimized AMI in an CloudFormation template
You can reference the latest recommended Amazon ECS-optimized AMI in an CloudFormation template by referencing the Systems Manager parameter store name.
**Linux example**
```
Parameters:kernel-5.10
LatestECSOptimizedAMI:
Description: AMI ID
Type: AWS::SSM::Parameter::Value
Default: /aws/service/ecs/optimized-ami/amazon-linux-2/kernel-5.10/recommended/image_id
```
# Migrating from an Amazon Linux 2 to an Amazon Linux 2023 Amazon ECS-optimized AMI
Following [Amazon Linux](https://aws.amazon.com/amazon-linux-2/faqs), Amazon ECS ends standard support for Amazon Linux 2 Amazon ECS-optimized AMIs effective June 30, 2026. After this date, the Amazon ECS agent version is pinned and new Amazon Linux 2 Amazon ECS-optimized AMIs are only published when the source Amazon Linux 2 AMI is updated. Complete End of Life (EOL) occurs on June 30, 2026, after which no more Amazon ECS-optimized Amazon Linux 2 AMIs are published, even if the source AMI is updated.
Amazon Linux 2023 provides a secure-by-default approach with preconfigured security policies, SELinux in permissive mode, IMDSv2-only mode enabled by default, optimized boot times, and improved package management for enhanced security and performance.
There is a high degree of compatibility between the Amazon Linux 2 and Amazon Linux 2023 Amazon ECS-optimized AMIs, and most customers will experience minimal-to-zero changes in their workloads between the two operating systems.
For more information, see [Comparing Amazon Linux 2 and *Amazon Linux 2023*](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) in the *Amazon Linux 2023 User Guide* and the [AL2023 FAQs](https://aws.amazon.com/linux/amazon-linux-2023/faqs).
## Compatibility considerations
### Package management and OS updates
Unlike previous versions of Amazon Linux, Amazon ECS-optimized Amazon Linux 2023 AMIs are locked to a specific version of the Amazon Linux repository. This insulates users from inadvertently updating packages that might bring in unwanted or breaking changes. For more information, see [Managing repositories and OS updates in Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/managing-repos-os-updates.html) in the *Amazon Linux 2023 User Guide*.
### Linux kernel versions
Amazon Linux 2 AMIs are based on Linux kernels 4.14 and 5.10, while Amazon Linux 2023 uses Linux kernel 6.1 and 6.12. For more information, see [Comparing Amazon Linux 2 and Amazon Linux 2023 kernels](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2-kernel.html) in the *Amazon Linux 2023 User Guide*.
### Package availability changes
The following are notable package changes in Amazon Linux 2023:
+ Some source binary packages in Amazon Linux 2 are no longer available in Amazon Linux 2023. For more information, see [Packages removed from Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/release-notes/removed.html) in the *Amazon Linux 2023 Release Notes*.
+ Changes in how Amazon Linux supports different versions of packages. The `amazon-linux-extras` system used in Amazon Linux 2 does not exist in Amazon Linux 2023. All packages are simply available in the "core" repository.
+ Extra packages for Enterprise Linux (EPEL) are not supported in Amazon Linux 2023. For more information, see [EPEL compatibility in Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/epel.html) in the *Amazon Linux 2023 User Guide*.
+ 32-bit applications are not supported in Amazon Linux 2023. For more information, see [Deprecated features from Amazon Linux 2](https://docs.aws.amazon.com/linux/al2023/ug/deprecated-al2.html#deprecated-32bit-rpms) in the *Amazon Linux 2023 User Guide*.
### Control Groups (cgroups) changes
A Control Group (cgroup) is a Linux kernel feature to hierarchically organize processes and distribute system resources between them. Control Groups are used extensively to implement a container runtime, and by `systemd`.
The Amazon ECS agent, Docker, and containerd all support both cgroupv1 and cgroupv2. cgroupv2 changes how container memory usage is calculated. In cgroupv1 (Amazon Linux 2), container memory utilization as reported by the container runtime typically excludes page cache. In cgroupv2 (Amazon Linux 2023), page cache is included in the reported memory usage. The same workload may report higher memory utilization on Amazon Linux 2023 compared to Amazon Linux 2, even when actual application memory consumption has not changed.
We recommend benchmarking memory usage on Amazon Linux 2023 instances before migrating production workloads, and adjusting task and container memory limits if needed. You can use [Container Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-metrics-ECS.html) to compare memory utilization between Amazon Linux 2 and Amazon Linux 2023.
For further details on cgroupv2, see [Control groups v2 in Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/cgroupv2.html) in the *Amazon Linux 2023 User Guide*.
### Instance Metadata Service (IMDS) changes
Amazon Linux 2023 requires Instance Metadata Service version 2 (IMDSv2) by default. IMDSv2 has several benefits that help improve security posture. It uses a session-oriented authentication method that requires the creation of a secret token in a simple HTTP PUT request to start the session. A session's token can be valid for anywhere between 1 second and 6 hours.
For more information on how to transition from IMDSv1 to IMDSv2, see [Transition to using Instance Metadata Service Version 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.html) in the *Amazon EC2 User Guide*.
If you would like to use IMDSv1, you can still do so by manually overriding the settings using instance metadata option launch properties.
### Memory swappiness changes
Per-container memory swappiness is not supported on Amazon Linux 2023 and cgroups v2. For more information, see [Managing container swap memory space on Amazon ECS](container-swap.md).
### FIPS validation changes
Amazon Linux 2 is certified under FIPS 140-2 and Amazon Linux 2023 is certified under FIPS 140-3.
To enable FIPS mode on Amazon Linux 2023, install the necessary packages on your Amazon EC2 instance and follow the configuration steps using the instructions in [Enable FIPS Mode on Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/fips-mode.html) in the *Amazon Linux 2023 User Guide*.
### Accelerated instance support
The Amazon ECS-optimized Amazon Linux 2023 AMIs support both Neuron and GPU accelerated instance types. For more information, see [Amazon ECS-optimized Linux AMIs](ecs-optimized_AMI.md).
## Building custom AMIs
While we recommend moving to officially supported and published Amazon ECS-optimized AMIs for Amazon Linux 2023, you can continue to build custom Amazon Linux 2 Amazon ECS-optimized AMIs using the open-source build scripts that are used to build the Linux variants of the Amazon ECS-optimized AMI. For more information, see [Amazon ECS-optimized Linux AMI build script](ecs-ami-build-scripts.md).
## Migration strategies
We recommend creating and implementing a migration plan that includes thorough application testing. The following sections outline different migration strategies based on how you manage your Amazon ECS infrastructure.
### Migrating with Amazon ECS capacity providers
1. Create a new capacity provider with a new launch template. This should reference an Auto Scaling group with a launch template similar to your existing one, but instead of the Amazon Linux 2 Amazon ECS-optimized AMI, it should specify one of the Amazon Linux 2023 variants. Add this new capacity provider to your existing Amazon ECS cluster.
1. Update your cluster's default capacity provider strategy to include both the existing Amazon Linux 2 capacity provider and the new Amazon Linux 2023 capacity provider. Start with a higher weight on the Amazon Linux 2 provider and a lower weight on the Amazon Linux 2023 provider (for example, Amazon Linux 2: weight 80, Amazon Linux 2023: weight 20). This causes Amazon ECS to begin provisioning Amazon Linux 2023 instances as new tasks are scheduled. Verify that the instances register correctly and that tasks are able to run successfully on the new instances.
1. Gradually adjust the capacity provider weights in your cluster's default strategy, increasing the weight for the Amazon Linux 2023 provider while decreasing the Amazon Linux 2 provider weight over time (for example, 60/40, then 40/60, then 20/80). You can also update individual service capacity provider strategies to prioritize Amazon Linux 2023 instances. Monitor task placement to ensure they're successfully running on Amazon Linux 2023 instances.
1. Optionally drain Amazon Linux 2 container instances to accelerate task migration. If you have sufficient Amazon Linux 2023 replacement capacity, you can manually drain your Amazon Linux 2 container instances through the Amazon ECS console or AWS CLI to speed up the transition of your tasks from Amazon Linux 2 to Amazon Linux 2023. After the migration is complete, remove the Amazon Linux 2 capacity provider from your cluster and delete the associated Auto Scaling group.
### Migrating with an Amazon EC2 Auto Scaling group
1. Create a new Amazon EC2 Auto Scaling group with a new launch template. This should be similar to your existing launch template, but instead of the Amazon Linux 2 Amazon ECS-optimized AMI, it should specify one of the Amazon Linux 2023 variants. This new Auto Scaling group can launch instances to your existing cluster.
1. Scale up the Auto Scaling group so that you begin to have Amazon Linux 2023 instances registering to your cluster. Verify that the instances register correctly and that tasks are able to run successfully on the new instances.
1. After your tasks have been verified to work on Amazon Linux 2023, scale up the Amazon Linux 2023 Auto Scaling group while gradually scaling down the Amazon Linux 2 Auto Scaling group, until you have completely replaced all Amazon Linux 2 instances.
1. If you have sufficient Amazon Linux 2023 replacement capacity, you might want to explicitly drain the container instances to speed up the transition of your tasks from Amazon Linux 2 to Amazon Linux 2023. For more information, see [Draining Amazon ECS container instances](container-instance-draining.md).
### Migrating with manually managed instances
1. Manually launch (or adjust scripts that launch) new Amazon EC2 instances using the Amazon ECS-optimized Amazon Linux 2023 AMI instead of Amazon Linux 2. Ensure these instances use the same security groups, subnets, IAM roles, and cluster configuration as your existing Amazon Linux 2 instances. The instances should automatically register to your existing Amazon ECS cluster upon launch.
1. Verify the new Amazon Linux 2023 instances are successfully registering to your Amazon ECS cluster and are in an `ACTIVE` state. Test that tasks can be scheduled and run properly on these new instances by either waiting for natural task placement or manually stopping/starting some tasks to trigger rescheduling.
1. Gradually replace your Amazon Linux 2 instances by launching additional Amazon Linux 2023 instances as needed, then manually draining and terminating the Amazon Linux 2 instances one by one. You can drain instances through the Amazon ECS console by setting the instance to `DRAINING` status, which will stop placing new tasks on it and allow existing tasks to finish or be rescheduled elsewhere.
# Amazon ECS-optimized Linux AMI build script
Amazon ECS has open-sourced the build scripts that are used to build the Linux variants of the Amazon ECS-optimized AMI. These build scripts are now available on GitHub. For more information, see [amazon-ecs-ami](https://github.com/aws/amazon-ecs-ami) on GitHub.
If you need to customize the Amazon ECS-optimized AMI , see [Amazon ECS Optimized AMI Build Recipies](https://github.com/aws/amazon-ecs-ami) on GitHub.
The build scripts repository includes a [HashiCorp packer](https://developer.hashicorp.com/packer/docs) template and build scripts to generate each of the Linux variants of the Amazon ECS-optimized AMI. These scripts are the source of truth for Amazon ECS-optimized AMI builds, so you can follow the GitHub repository to monitor changes to our AMIs. For example, perhaps you want your own AMI to use the same version of Docker that the Amazon ECS team uses for the official AMI.
For more information, see the Amazon ECS AMI repository at [aws/amazon-ecs-ami](https://github.com/aws/amazon-ecs-ami) on GitHub.
**To build an Amazon ECS-optimized Linux AMI**
1. Clone the `aws/amazon-ecs-ami` GitHub repo.
```
git clone https://github.com/aws/amazon-ecs-ami.git
```
1. Add an environment variable for the AWS Region to use when creating the AMI. Replace the `us-west-2` value with the Region to use.
```
export REGION=us-west-2
```
1. A Makefile is provided to build the AMI. From the root directory of the cloned repository, use one of the following commands, corresponding to the Linux variant of the Amazon ECS-optimized AMI you want to build.
+ Amazon ECS-optimized Amazon Linux 2 AMI
```
make al2
```
+ Amazon ECS-optimized Amazon Linux 2 (arm64) AMI
```
make al2arm
```
+ Amazon ECS GPU-optimized AMI
```
make al2gpu
```
+ Amazon ECS optimized Amazon Linux 2 (Neuron) AMI
```
make al2inf
```
+ Amazon ECS-optimized Amazon Linux 2023 AMI
```
make al2023
```
+ Amazon ECS-optimized Amazon Linux 2023 (arm64) AMI
```
make al2023arm
```
+ Amazon ECS-optimized Amazon Linux 2023 GPU AMI
```
make al2023gpu
```
+ Amazon ECS optimized Amazon Linux 2023 (Neuron) AMI
```
make al2023neu
```
# Amazon ECS-optimized Bottlerocket AMIs
Bottlerocket is a Linux based open-source operating system that is purpose built by AWS for running containers on virtual machines or bare metal hosts. The Amazon ECS-optimized Bottlerocket AMI is secure and only includes the minimum number of packages that's required to run containers. This improves resource usage, reduces security attack surface, and helps lower management overhead. The Bottlerocket AMI is also integrated with Amazon ECS to help reduce the operational overhead involved in updating container instances in a cluster.
Bottlerocket differs from Amazon Linux in the following ways:
+ Bottlerocket doesn't include a package manager, and its software can only be run as containers. Updates to Bottlerocket are both applied and can be rolled back in a single step, which reduces the likelihood of update errors.
+ The primary mechanism to manage Bottlerocket hosts is with a container scheduler. Unlike Amazon Linux, logging into individual Bottlerocket instances is intended to be an infrequent operation for advanced debugging and troubleshooting purposes only.
For more information about Bottlerocket, see the [documentation](https://github.com/bottlerocket-os/bottlerocket/blob/develop/README.md) and [releases](https://github.com/bottlerocket-os/bottlerocket/releases) on GitHub.
There are variants of the Amazon ECS-optimized Bottlerocket AMI for kernel 6.1 and kernel 5.10.
The following variants use kernel 6.1:
+ `aws-ecs-2`
+ `aws-ecs-2-nvidia`
The following variants use kernel 5.10:
+ `aws-ecs-1`
+ `aws-ecs-1-nvidia`
For more information about the `aws-ecs-1-nvidia` variant, see [Announcing NVIDIA GPU support for Bottlerocket on Amazon ECS](https://aws.amazon.com/blogs/containers/announcing-nvidia-gpu-support-for-bottlerocket-on-amazon-ecs/).
## Considerations
Consider the following when using a Bottlerocket AMI with Amazon ECS.
+ Bottlerocket supports Amazon EC2 instances with `x86_64` and `arm64` processors. The Bottlerocket AMI isn't recommended for use with Amazon EC2 instances with an Inferentia chip.
+ Bottlerocket images don't include an SSH server or a shell. However, you can use out-of-band management tools to gain SSH administrator access and perform bootstrapping.
For more information, see these sections in the [bottlerocket README.md](https://github.com/bottlerocket-os/bottlerocket) on GitHub:
+ [Exploration](https://github.com/bottlerocket-os/bottlerocket#exploration)
+ [Admin container](https://github.com/bottlerocket-os/bottlerocket#admin-container)
+ By default, Bottlerocket has a [control container](https://github.com/bottlerocket-os/bottlerocket-control-container) that's enabled. This container runs the [AWS Systems Manager agent](https://github.com/aws/amazon-ssm-agent) that you can use to run commands or start shell sessions on Amazon EC2 Bottlerocket instances. For more information, see [Setting up Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html) in the *AWS Systems Manager User Guide*.
+ Bottlerocket is optimized for container workloads and has a focus on security. Bottlerocket doesn't include a package manager and is immutable.
For information about the security features and guidance, see [Security Features](https://github.com/bottlerocket-os/bottlerocket/blob/develop/SECURITY_FEATURES.md) and [Security Guidance](https://github.com/bottlerocket-os/bottlerocket/blob/develop/SECURITY_GUIDANCE.md) on GitHub.
+ The `awsvpc` network mode is supported for Bottlerocket AMI version `1.1.0` or later.
+ App Mesh in a task definition is supported for Bottlerocket AMI version `1.15.0` or later.
+ The `initProcessEnabled` task definition parameter is supported for Bottlerocket AMI version `1.19.0` or later.
+ The Bottlerocket AMIs also don't support the following services and features:
+ ECS Anywhere
+ Service Connect
+ Amazon EFS in encrypted mode
+ Amazon EFS in `awsvpc` network mode
+ Amazon EBS volumes can't be mounted
+ Elastic Inference Accelerator
# Retrieving Amazon ECS-optimized Bottlerocket AMI metadata
You can retrieve the Amazon Machine Image (AMI) ID for Amazon ECS-optimized AMIs by querying the AWS Systems Manager Parameter Store API. Using this parameter, you don't need to manually look up Amazon ECS-optimized AMI IDs. For more information about the Systems Manager Parameter Store API, see [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html). The user that you use must have the `ssm:GetParameter` IAM permission to retrieve the Amazon ECS-optimized AMI metadata.
## `aws-ecs-2` Bottlerocket AMI variant
You can retrieve the latest stable `aws-ecs-2` Bottlerocket AMI variant by AWS Region and architecture with the AWS CLI or the AWS Management Console.
+ **AWS CLI** – You can retrieve the image ID of the latest recommended Amazon ECS-optimized Bottlerocket AMI with the following AWS CLI command by using the subparameter `image_id`. Replace the `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub. To retrieve a version other than the latest, replace `latest` with the version number.
+ For the 64-bit (`x86_64`) architecture:
```
aws ssm get-parameter --region us-east-2 --name "/aws/service/bottlerocket/aws-ecs-2/x86_64/latest/image_id" --query Parameter.Value --output text
```
+ For the 64-bit Arm (`arm64`) architecture:
```
aws ssm get-parameter --region us-east-2 --name "/aws/service/bottlerocket/aws-ecs-2/arm64/latest/image_id" --query Parameter.Value --output text
```
+ **AWS Management Console** – You can query for the recommended Amazon ECS-optimized AMI ID using a URL in the AWS Management Console. The URL opens the Amazon EC2 Systems Manager console with the value of the ID for the parameter. In the following URL, replace `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub.
+ For the 64-bit (`x86_64`) architecture:
```
https://console.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-2/x86_64/latest/image_id/description?region=region#
```
+ For the 64-bit Arm (`arm64`) architecture:
```
https://console.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-2/arm64/latest/image_id/description?region=region#
```
## `aws-ecs-2-nvidia` Bottlerocket AMI variant
You can retrieve the latest stable `aws-ecs-2-nvdia` Bottlerocket AMI variant by Region and architecture with the AWS CLI or the AWS Management Console.
+ **AWS CLI** – You can retrieve the image ID of the latest recommended Amazon ECS-optimized Bottlerocket AMI with the following AWS CLI command by using the subparameter `image_id`. Replace the `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub. To retrieve a version other than the latest, replace `latest` with the version number.
+ For the 64-bit (`x86_64`) architecture:
```
aws ssm get-parameter --region us-east-1 --name "/aws/service/bottlerocket/aws-ecs-2-nvidia/x86_64/latest/image_id" --query Parameter.Value --output text
```
+ For the 64 bit Arm (`arm64`) architecture:
```
aws ssm get-parameter --region us-east-1 --name "/aws/service/bottlerocket/aws-ecs-2-nvidia/arm64/latest/image_id" --query Parameter.Value --output text
```
+ **AWS Management Console** – You can query for the recommended Amazon ECS optimized AMI ID using a URL in the AWS Management Console. The URL opens the Amazon EC2 Systems Manager console with the value of the ID for the parameter. In the following URL, replace `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub.
+ For the 64 bit (`x86_64`) architecture:
```
https://regionconsole.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-2-nvidia/x86_64/latest/image_id/description?region=region#
```
+ For the 64 bit Arm (`arm64`) architecture:
```
https://regionconsole.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-2-nvidia/arm64/latest/image_id/description?region=region#
```
## `aws-ecs-1` Bottlerocket AMI variant
You can retrieve the latest stable `aws-ecs-1` Bottlerocket AMI variant by AWS Region and architecture with the AWS CLI or the AWS Management Console.
+ **AWS CLI** – You can retrieve the image ID of the latest recommended Amazon ECS-optimized Bottlerocket AMI with the following AWS CLI command by using the subparameter `image_id`. Replace the `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub. To retrieve a version other than the latest, replace `latest` with the version number.
+ For the 64-bit (`x86_64`) architecture:
```
aws ssm get-parameter --region us-east-1 --name "/aws/service/bottlerocket/aws-ecs-1/x86_64/latest/image_id" --query Parameter.Value --output text
```
+ For the 64-bit Arm (`arm64`) architecture:
```
aws ssm get-parameter --region us-east-1 --name "/aws/service/bottlerocket/aws-ecs-1/arm64/latest/image_id" --query Parameter.Value --output text
```
+ **AWS Management Console** – You can query for the recommended Amazon ECS-optimized AMI ID using a URL in the AWS Management Console. The URL opens the Amazon EC2 Systems Manager console with the value of the ID for the parameter. In the following URL, replace `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub.
+ For the 64-bit (`x86_64`) architecture:
```
https://region.console.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-1/x86_64/latest/image_id/description
```
+ For the 64-bit Arm (`arm64`) architecture:
```
https://region.console.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-1/arm64/latest/image_id/description
```
## `aws-ecs-1-nvidia` Bottlerocket AMI variant
You can retrieve the latest stable `aws-ecs-1-nvdia` Bottlerocket AMI variant by Region and architecture with the AWS CLI or the AWS Management Console.
+ **AWS CLI** – You can retrieve the image ID of the latest recommended Amazon ECS-optimized Bottlerocket AMI with the following AWS CLI command by using the subparameter `image_id`. Replace the `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub.
+ For the 64-bit (`x86_64`) architecture:
```
aws ssm get-parameter --region us-east-1 --name "/aws/service/bottlerocket/aws-ecs-1-nvidia/x86_64/latest/image_id" --query Parameter.Value --output text
```
+ For the 64 bit Arm (`arm64`) architecture:
```
aws ssm get-parameter --region us-east-1 --name "/aws/service/bottlerocket/aws-ecs-1-nvidia/arm64/latest/image_id" --query Parameter.Value --output text
```
+ **AWS Management Console** – You can query for the recommended Amazon ECS optimized AMI ID using a URL in the AWS Management Console. The URL opens the Amazon EC2 Systems Manager console with the value of the ID for the parameter. In the following URL, replace `region` with the Region code that you want the AMI ID for.
For information about the supported AWS Regions, see [Finding an AMI](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md#finding-an-ami) on GitHub.
+ For the 64 bit (`x86_64`) architecture:
```
https://console.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-1-nvidia/x86_64/latest/image_id/description?region=region#
```
+ For the 64 bit Arm (`arm64`) architecture:
```
https://console.aws.amazon.com/systems-manager/parameters/aws/service/bottlerocket/aws-ecs-1-nvidia/arm64/latest/image_id/description?region=region#
```
## Next steps
For a detailed tutorial on how to get started with the Bottlerocket operating system on Amazon ECS, see [Using a Bottlerocket AMI with Amazon ECS](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md) on GitHub and [ Getting started withBottlerocket and Amazon ECS](https://aws.amazon.com/blogs/containers/getting-started-with-bottlerocket-and-amazon-ecs/) on the AWS blog site.
For information about how to launch a Bottlerocket instance, see [Launching a Bottlerocket instance for Amazon ECS](bottlerocket-launch.md)
# Launching a Bottlerocket instance for Amazon ECS
You can launch a Bottlerocket instance so that you can run your container workloads.
You can use the AWS CLI to launch the Bottlerocket instance.
1. Create a file that's called `userdata.toml`. This file is used for the instance user data. Replace *cluster-name* with the name of your cluster.
```
[settings.ecs]
cluster = "cluster-name"
```
1. Use one of the commands that are included in [Retrieving Amazon ECS-optimized Bottlerocket AMI metadata](ecs-bottlerocket-retrieve-ami.md) to get the Bottlerocket AMI ID. You use this in the following step.
1. Run the following command to launch the Bottlerocket instance. Remember to replace the following parameters:
+ Replace *subnet* with the ID of the private or public subnet that your instance will launch in.
+ Replace *bottlerocket\$1ami* with the AMI ID from the previous step.
+ Replace *t3.large* with the instance type that you want to use.
+ Replace *region* with the Region code.
```
aws ec2 run-instances --key-name ecs-bottlerocket-example \
--subnet-id subnet \
--image-id bottlerocket_ami \
--instance-type t3.large \
--region region \
--tag-specifications 'ResourceType=instance,Tags=[{Key=bottlerocket,Value=example}]' \
--user-data file://userdata.toml \
--iam-instance-profile Name=ecsInstanceRole
```
1. Run the following command to verify that the container instance is registered to the cluster. When you run this command, remember to replace the following parameters:
+ Replace *cluster* with your cluster name.
+ Replace *region* with your Region code.
```
aws ecs list-container-instances --cluster cluster-name --region region
```
For a detailed walkthrough of how to get started with the Bottlerocket operating system on Amazon ECS, see [Using a Bottlerocket AMI with Amazon ECS](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-ECS.md) on GitHub and Getting started with [Bottlerocket and Amazon ECS](https://aws.amazon.com/blogs/containers/getting-started-with-bottlerocket-and-amazon-ecs/) on the AWS blog site.
# Amazon ECS Linux container instance management
When you use EC2 instances for your Amazon ECS workloads, you are responsible for maintaining the instances
**Topics**
+ [Launching a container instance](launch_container_instance.md)
+ [Bootstrapping Linux container instances](bootstrap_container_instance.md)
+ [Configuring container instances to receive Spot Instance notices](spot-instance-draining-linux-container.md)
+ [Running a script when you launch a container instance](start_task_at_launch.md)
+ [
# Increasing Amazon ECS Linux container instance network interfaces
](container-instance-eni.md)
+ [Reserving container instance memory](memory-management.md)
+ [Manage container instances remotely](ec2-run-command.md)
+ [Using an HTTP proxy for Linux container instances](http_proxy_config.md)
+ [Configuring pre-initialized instances for your Auto Scaling group](using-warm-pool.md)
+ [
# Updating the Amazon ECS container agent
](ecs-agent-update.md)
Each Amazon ECS container agent version supports a different feature set and provides bug fixes from previous versions. When possible, we always recommend using the latest version of the Amazon ECS container agent. To update your container agent to the latest version, see [Updating the Amazon ECS container agent](ecs-agent-update.md).
To see which features and enhancements are included with each agent release, see [https://github.com/aws/amazon-ecs-agent/releases](https://github.com/aws/amazon-ecs-agent/releases).
**Important**
The minimum Docker version for reliable metrics is Docker version `v20.10.13` and newer, which is included in Amazon ECS-optimized AMI `20220607` and newer.
Amazon ECS agent versions `1.20.0` and newer have deprecated support for Docker versions older than `18.01.0`.
# Launching an Amazon ECS Linux container instance
You can create Amazon ECS container instances using the Amazon EC2 console.
You can launch an instance by various methods including the Amazon EC2 console, AWS CLI, and SDK. For information about the other methods for launching an instance, see [Launch your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html) in the *Amazon EC2 User Guide*.
For more information about the launch wizard, see [Launch an instance using the new launch instance wizard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-instance-wizard.html) in the *Amazon EC2 User Guide*.
Before you begin, complete the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md).
You can use the new Amazon EC2 wizard to launch an instance. The launch instance wizard specifies the launch parameters that are required for launching an instance.
**Topics**
+ [
## Procedure
](#linux-liw-initiate-instance-launch)
+ [
## Name and tags
](#linux-liw-name-and-tags)
+ [
## Application and OS Images (Amazon Machine Image)
](#linux-liw-ami)
+ [
## Instance type
](#linux-liw-instance-type)
+ [
## Key pair (login)
](#linux-liw-key-pair)
+ [
## Network settings
](#linux-liw-network-settings)
+ [
## Configure storage
](#linux-liw-storage)
+ [
## Advanced details
](#linux-liw-advanced-details)
## Procedure
Before you begin, complete the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md).
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation bar at the top of the screen, the current AWS Region is displayed (for example, US East (Ohio)). Select a Region in which to launch the instance.
1. From the Amazon EC2 console dashboard, choose **Launch instance**.
## Name and tags
The instance name is a tag, where the key is **Name**, and the value is the name that you specify. You can tag the instance, the volumes, and elastic graphics. For Spot Instances, you can tag the Spot Instance request only.
Specifying an instance name and additional tags is optional.
+ For **Name**, enter a descriptive name for the instance. If you don't specify a name, the instance can be identified by its ID, which is automatically generated when you launch the instance.
+ To add additional tags, choose **Add additional tags**. Choose **Add tag**, and then enter a key and value, and select the resource type to tag. Choose **Add tag** again for each additional tag to add.
## Application and OS Images (Amazon Machine Image)
An Amazon Machine Image (AMI) contains the information required to create an instance. For example, an AMI might contain the software that's required to act as a web server, such as Apache, and your website.
Use the **Search** bar to find a suitable Amazon ECS-optimized AMI published by AWS.
1. Enter one of the following terms in the **Search** bar.
+ **ami-ecs**
+ The **Value** of an Amazon ECS-optimized AMI.
For the latest Amazon ECS-optimized AMIs and their values, see [Linux Amazon ECS-optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#ecs-optimized-ami-linux).
1. Press **Enter**.
1. On the **Choose an Amazon Machine Image (AMI)** page, select the **AWS Marketplace AMIs** tab.
1. From the left **Refine results** pane, select **Amazon Web Services** as the **Publisher**.
1. Choose **Select** on the row of the AMI that you want to use.
Alternatively, choose **Cancel** (at top right) to return to the launch instance wizard without choosing an AMI. A default AMI will be selected. Ensure that the AMI meets the requirements outlined in [Amazon ECS-optimized Linux AMIs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html).
## Instance type
The instance type defines the hardware configuration and size of the instance. Larger instance types have more CPU and memory. For more information, see [Instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html) in the *Amazon EC2 User Guide*. If you want to run an IPv6-only workload, certain instance types don't support IPv6 addresses. For more information, see [IPv6 addresses](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-instance-addressing.html#ipv6-addressing) in the *Amazon EC2 User Guide*.
+ For **Instance type**, select the instance type for the instance.
The instance type that you select determines the resources available for your tasks to run on.
## Key pair (login)
For **Key pair name**, choose an existing key pair, or choose **Create new key pair** to create a new one.
**Important**
If you choose the **Proceed without key pair (Not recommended)** option, you won't be able to connect to the instance unless you choose an AMI that is configured to allow users another way to log in.
## Network settings
Configure the network settings as necessary after choosing the **Edit** button for the **Network settings** section of the form.
+ For **VPC**, choose the VPC that you want to launch the instance into. To run an IPv6-only workload, choose a dual stack VPC that includes both an IPv4 and an IPv6 CIDR block.
+ For **Subnet**, choose the subnet to launch the instance in. You can launch an instance in a subnet associated with an Availability Zone, Local Zone, Wavelength Zone, or Outpost.
To launch the instance in an Availability Zone, select the subnet in which to launch your instance. To create a new subnet, choose **Create new subnet** to go to the Amazon VPC console. When you are done, return to the launch instance wizard and choose the Refresh icon to load your subnet in the list.
To launch the instance in a Local Zone, select a subnet that you created in the Local Zone.
To launch an instance in an Outpost, select a subnet in a VPC that you associated with the Outpost.
To run an IPv6-only workload, choose a subnet that includes only an IPv6 CIDR block.
+ **Auto-assign Public IP**: If your instance should be accessible from the internet, verify that the **Auto-assign Public IP** field is set to **Enable**. If not, set this field to **Disable**.
**Note**
Container instances need access to communicate with the Amazon ECS service endpoint. This can be through an interface VPC endpoint or through your container instances having public IP addresses.
For more information about interface VPC endpoints, see [Amazon ECS interface VPC endpoints (AWS PrivateLink)](vpc-endpoints.md)
If you do not have an interface VPC endpoint configured and your container instances do not have public IP addresses, then they must use network address translation (NAT) to provide this access. For more information, see [NAT gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) in the *Amazon VPC User Guide* and [Using an HTTP proxy for Amazon ECS Linux container instances](http_proxy_config.md) in this guide.
+ If you choose a dual stack VPC and an IPv6-only subnet, for **Auto-assign IPv6 IP**, choose **Enable**.
+ **Firewall (security groups)**: Use a security group to define firewall rules for your container instance. These rules specify which incoming network traffic is delivered to your container instance. All other traffic is ignored.
+ To select an existing security group, choose **Select existing security group**, and select the security group that you created in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md).
+ If you are launching the instance for an IPv6-only workload, choose **Advanced network configuration**, and then for **Assign Primary IPv6 IP**, choose **Yes**.
**Note**
Without a primary IPv6 address, tasks running on the container instance in the host or bridge network modes will fail to register with load balancers or with AWS Cloud Map.
## Configure storage
The AMI you selected includes one or more volumes of storage, including the root volume. You can specify additional volumes to attach to the instance.
You can use the **Simple** view.
+ **Storage type**: Configure the storage for your container instance.
If you are using the Amazon ECS-optimized Amazon Linux 2 AMI, your instance has a single 30 GiB volume configured, which is shared between the operating system and Docker.
If you are using the Amazon ECS-optimized AMI, your instance has two volumes configured. The **Root** volume is for the operating system's use, and the second Amazon EBS volume (attached to `/dev/xvdcz`) is for Docker's use.
You can optionally increase or decrease the volume sizes for your instance to meet your application needs.
## Advanced details
For **Advanced details**, expand the section to view the fields and specify any additional parameters for the instance.
+ **Purchasing option**: Choose **Request Spot Instances** to request Spot Instances. You also need to set the other fields related to Spot Instances. For more information, see [Spot Instance Requests](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-requests.html).
**Note**
If you are using Spot Instances and see a `Not available` message, you may need to choose a different instance type.
+ **IAM instance profile**: Select your container instance IAM role. This is usually named `ecsInstanceRole`.
**Important**
If you do not launch your container instance with the proper IAM permissions, your Amazon ECS agent cannot connect to your cluster. For more information, see [Amazon ECS container instance IAM role](instance_IAM_role.md).
+ **User data**: Configure your Amazon ECS container instance with user data, such as the agent environment variables from [Amazon ECS container agent configuration](ecs-agent-config.md). Amazon EC2 user data scripts are executed only one time, when the instance is first launched. The following are common examples of what user data is used for:
+ By default, your container instance launches into your default cluster. To launch into a non-default cluster, choose the **Advanced Details** list. Then, paste the following script into the **User data** field, replacing *your\$1cluster\$1name* with the name of your cluster.
```
#!/bin/bash
echo ECS_CLUSTER=your_cluster_name >> /etc/ecs/ecs.config
```
+ If you have an `ecs.config` file in Amazon S3 and have enabled Amazon S3 read-only access to your container instance role, choose the **Advanced Details** list. Then, paste the following script into the **User data** field, replacing *your\$1bucket\$1name* with the name of your bucket to install the AWS CLI and write your configuration file at launch time.
**Note**
For more information about this configuration, see [Storing Amazon ECS container instance configuration in Amazon S3](ecs-config-s3.md).
```
#!/bin/bash
yum install -y aws-cli
aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config
```
+ Specify tags for your container instance using the `ECS_CONTAINER_INSTANCE_TAGS` configuration parameter. This creates tags that are associated with Amazon ECS only, they cannot be listed using the Amazon EC2 API.
**Important**
If you launch your container instances using an Amazon EC2 Auto Scaling group, then you should use the ECS\$1CONTAINER\$1INSTANCE\$1TAGS agent configuration parameter to add tags. This is due to the way in which tags are added to Amazon EC2 instances that are launched using Auto Scaling groups.
```
#!/bin/bash
cat <<'EOF' >> /etc/ecs/ecs.config
ECS_CLUSTER=your_cluster_name
ECS_CONTAINER_INSTANCE_TAGS={"tag_key": "tag_value"}
EOF
```
+ Specify tags for your container instance and then use the `ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM` configuration parameter to propagate them from Amazon EC2 to Amazon ECS
The following is an example of a user data script that would propagate the tags associated with a container instance, as well as register the container instance with a cluster named `your_cluster_name`:
```
#!/bin/bash
cat <<'EOF' >> /etc/ecs/ecs.config
ECS_CLUSTER=your_cluster_name
ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM=ec2_instance
EOF
```
+ By default, the Amazon ECS container agent will try to detect the container instance's compatibility for an IPv6-only configuration by looking at the instance's default IPv4 and IPv6 routes. To override this behavior, you can set the ` ECS_INSTANCE_IP_COMPATIBILITY` parameter to `ipv4` or `ipv6` in the instance's `/etc/ecs/ecs.config` file.
```
#!/bin/bash
cat <<'EOF' >> /etc/ecs/ecs.config
ECS_CLUSTER=your_cluster_name
ECS_INSTANCE_IP_COMPATIBILITY=ipv6
EOF
```
For more information, see [Bootstrapping Amazon ECS Linux container instances to pass data](bootstrap_container_instance.md).
# Bootstrapping Amazon ECS Linux container instances to pass data
When you launch an Amazon EC2 instance, you can pass user data to the EC2 instance. The data can be used to perform common automated configuration tasks and even run scripts when the instance boots. For Amazon ECS, the most common use cases for user data are to pass configuration information to the Docker daemon and the Amazon ECS container agent.
You can pass multiple types of user data to Amazon EC2, including cloud boothooks, shell scripts, and `cloud-init` directives. For more information about these and other format types, see the [Cloud-Init documentation](https://cloudinit.readthedocs.io/en/latest/explanation/format.html).
To pass the user data when using the Amazon EC2 launch wizard, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
You can configure the container instance to pass data in the container agent configuration or in the Docker daemon configuration.
## Amazon ECS container agent
The Linux variants of the Amazon ECS-optimized AMI look for agent configuration data in the `/etc/ecs/ecs.config` file when the container agent starts. You can specify this configuration data at launch with Amazon EC2 user data. For more information about available Amazon ECS container agent configuration variables, see [Amazon ECS container agent configuration](ecs-agent-config.md).
To set only a single agent configuration variable, such as the cluster name, use **echo** to copy the variable to the configuration file:
```
#!/bin/bash
echo "ECS_CLUSTER=MyCluster" >> /etc/ecs/ecs.config
```
If you have multiple variables to write to `/etc/ecs/ecs.config`, use the following `heredoc` format. This format writes everything between the lines beginning with **cat** and `EOF` to the configuration file.
```
#!/bin/bash
cat <<'EOF' >> /etc/ecs/ecs.config
ECS_CLUSTER=MyCluster
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}
ECS_LOGLEVEL=debug
ECS_WARM_POOLS_CHECK=true
EOF
```
To set custom instance attributes, set the `ECS_INSTANCE_ATTRIBUTES` environment variable.
```
#!/bin/bash
cat <<'EOF' >> ecs.config
ECS_INSTANCE_ATTRIBUTES={"envtype":"prod"}
EOF
```
## Docker daemon
You can specify Docker daemon configuration information with Amazon EC2 user data. For more information about configuration options, see [the Docker daemon documentation](https://docs.docker.com/reference/cli/dockerd/).
**Note**
AWS doesn't support custom Docker configurations, because they can sometimes conflict with future Amazon ECS changes or features without warning.
In the example below, the custom options are added to the Docker daemon configuration file, `/etc/docker/daemon.json` which is then specified in the user data when the instance is launched.
```
#!/bin/bash
cat </etc/docker/daemon.json
{"debug": true}
EOF
systemctl restart docker --no-block
```
In the example below, the custom options are added to the Docker daemon configuration file, `/etc/docker/daemon.json` which is then specified in the user data when the instance is launched. This example shows how to disable the docker-proxy in the Docker daemon config file.
```
#!/bin/bash
cat </etc/docker/daemon.json
{"userland-proxy": false}
EOF
systemctl restart docker --no-block
```
# Configuring Amazon ECS Linux container instances to receive Spot Instance notices
Amazon EC2 terminates, stops, or hibernates your Spot Instance when the Spot price exceeds the maximum price for your request or capacity is no longer available. Amazon EC2 provides a Spot Instance two-minute interruption notice for terminate and stop actions. It does not provide the two-minute notice for the hibernate action. If Amazon ECS Spot Instance draining is turned onon the instance, Amazon ECS receives the Spot Instance interruption notice and places the instance in `DRAINING` status.
**Important**
Amazon ECS does not receive a notice from Amazon EC2 when instances are removed by Auto Scaling Capacity Rebalancing. For more information, see [Amazon EC2 Auto Scaling Capacity Rebalancing](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-capacity-rebalancing.html).
When a container instance is set to `DRAINING`, Amazon ECS prevents new tasks from being scheduled for placement on the container instance. Service tasks on the draining container instance that are in the `PENDING` state are stopped immediately. If there are container instances in the cluster that are available, replacement service tasks are started on them.
Spot Instance draining is turned off by default.
You can turn on Spot Instance draining when you launch an instance. Add the following script into the **User data** field. Replace *MyCluster* with the name of the cluster to register the container instance to.
```
#!/bin/bash
cat <<'EOF' >> /etc/ecs/ecs.config
ECS_CLUSTER=MyCluster
ECS_ENABLE_SPOT_INSTANCE_DRAINING=true
EOF
```
For more information, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
**To turn on Spot Instance draining for an existing container instance**
1. Connect to the Spot Instance over SSH.
1. Edit the `/etc/ecs/ecs.config` file and add the following:
```
ECS_ENABLE_SPOT_INSTANCE_DRAINING=true
```
1. Restart the `ecs` service.
+ For the Amazon ECS-optimized Amazon Linux 2 AMI:
```
sudo systemctl restart ecs
```
1. (Optional) You can verify that the agent is running and see some information about your new container instance by querying the agent introspection API operation. For more information, see [Amazon ECS container introspection](ecs-agent-introspection.md).
```
curl http://localhost:51678/v1/metadata
```
# Running a script when you launch an Amazon ECS Linux container instance
You might need to run a specific container on every container instance to deal with operations or security concerns such as monitoring, security, metrics, service discovery, or logging.
To do this, you can configure your container instances to call the **docker run** command with the user data script at launch, or in some init system such as Upstart or **systemd**. While this method works, it has some disadvantages because Amazon ECS has no knowledge of the container and cannot monitor the CPU, memory, ports, or any other resources used. To ensure that Amazon ECS can properly account for all task resources, create a task definition for the container to run on your container instances. Then, use Amazon ECS to place the task at launch time with Amazon EC2 user data.
The Amazon EC2 user data script in the following procedure uses the Amazon ECS introspection API to identify the container instance. Then, it uses the AWS CLI and the **start-task** command to run a specified task on itself during startup.
**To start a task at container instance launch time**
1. Modify your `ecsInstanceRole` IAM role to add permissions for the `StartTask` API operation. For more information, see [Update permissions for a role](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_update-role-permissions.html) in the *AWS Identity and Access Management User Guide*.
1. Launch one or more container instances using the Amazon ECS-optimized Amazon Linux 2 AMI. Launch new container instances and use the following example script in the EC2 User data. Replace *your\$1cluster\$1name* with the cluster for the container instance to register into and *my\$1task\$1def* with the task definition to run on the instance at launch.
For more information, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
**Note**
The MIME multi-part content below uses a shell script to set configuration values and install packages. It also uses a systemd job to start the task after the **ecs** service is running and the introspection API is available.
```
Content-Type: multipart/mixed; boundary="==BOUNDARY=="
MIME-Version: 1.0
--==BOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"
#!/bin/bash
# Specify the cluster that the container instance should register into
cluster=your_cluster_name
# Write the cluster configuration variable to the ecs.config file
# (add any other configuration variables here also)
echo ECS_CLUSTER=$cluster >> /etc/ecs/ecs.config
START_TASK_SCRIPT_FILE="/etc/ecs/ecs-start-task.sh"
cat <<- 'EOF' > ${START_TASK_SCRIPT_FILE}
exec 2>>/var/log/ecs/ecs-start-task.log
set -x
# Install prerequisite tools
yum install -y jq aws-cli
# Wait for the ECS service to be responsive
until curl -s http://localhost:51678/v1/metadata
do
sleep 1
done
# Grab the container instance ARN and AWS Region from instance metadata
instance_arn=$(curl -s http://localhost:51678/v1/metadata | jq -r '. | .ContainerInstanceArn' | awk -F/ '{print $NF}' )
cluster=$(curl -s http://localhost:51678/v1/metadata | jq -r '. | .Cluster' | awk -F/ '{print $NF}' )
region=$(curl -s http://localhost:51678/v1/metadata | jq -r '. | .ContainerInstanceArn' | awk -F: '{print $4}')
# Specify the task definition to run at launch
task_definition=my_task_def
# Run the AWS CLI start-task command to start your task on this container instance
aws ecs start-task --cluster $cluster --task-definition $task_definition --container-instances $instance_arn --started-by $instance_arn --region $region
EOF
# Write systemd unit file
UNIT="ecs-start-task.service"
cat <<- EOF > /etc/systemd/system/${UNIT}
[Unit]
Description=ECS Start Task
Requires=ecs.service
After=ecs.service
[Service]
Restart=on-failure
RestartSec=30
ExecStart=/usr/bin/bash ${START_TASK_SCRIPT_FILE}
[Install]
WantedBy=default.target
EOF
# Enable our ecs.service dependent service with `--no-block` to prevent systemd deadlock
# See https://github.com/aws/amazon-ecs-agent/issues/1707
systemctl enable --now --no-block "${UNIT}"
--==BOUNDARY==--
```
1. Verify that your container instances launch into the correct cluster and that your tasks have started.
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, choose the Region that your cluster is in.
1. In the navigation pane, choose **Clusters** and select the cluster that hosts your container instances.
1. On the **Cluster** page, choose **Tasks**, and then choose yor tasks.
Each container instance you launched should have your task running on it.
If you do not see your tasks, you can log in to your container instances with SSH and check the `/var/log/ecs/ecs-start-task.log` file for debugging information.
# Increasing Amazon ECS Linux container instance network interfaces
**Note**
This feature is not available on Fargate.
Each task that uses the `awsvpc` network mode receives its own elastic network interface (ENI), which is attached to the container instance that hosts it. There is a default limit to the number of network interfaces that can be attached to an Amazon EC2 instance, and the primary network interface counts as one. For example, by default a `c5.large` instance may have up to three ENIs attached to it. The primary network interface for the instance counts as one, so you can attach an additional two ENIs to the instance. Because each task using the `awsvpc` network mode requires an ENI, you can typically only run two such tasks on this instance type.
Amazon ECS supports launching container instances with increased ENI density using supported Amazon EC2 instance types. When you use these instance types and turn on the `awsvpcTrunking` account setting, additional ENIs are available on newly launched container instances. This configuration allows you to place more tasks on each container instance. To use the console to turn on the feature, see [Modifying Amazon ECS account settings](ecs-modifying-longer-id-settings.md). To use the AWS CLI to turn on the feature, see [Managing Amazon ECS account settings using the AWS CLI](account-setting-management-cli.md).
For example, a `c5.large` instance with `awsvpcTrunking` has an increased ENI limit of twelve. The container instance will have the primary network interface and Amazon ECS creates and attaches a "trunk" network interface to the container instance. So this configuration allows you to launch ten tasks on the container instance instead of the current two tasks.
The trunk network interface is fully managed by Amazon ECS and is deleted when you either terminate or deregister your container instance from the cluster. For more information, see [Amazon ECS task networking options for EC2](task-networking.md).
## Considerations
Consider the following when using the ENI trunking feature.
+ Only Linux variants of the Amazon ECS-optimized AMI, or other Amazon Linux variants with version `1.28.1` or later of the container agent and version `1.28.1-2` or later of the ecs-init package, support the increased ENI limits. If you use the latest Linux variant of the Amazon ECS-optimized AMI, these requirements will be met. Windows containers are not supported at this time.
+ Only new Amazon EC2 instances launched after enabling `awsvpcTrunking` receive the increased ENI limits and the trunk network interface. Previously launched instances do not receive these features regardless of the actions taken.
+ Amazon EC2 instances must have resource-based IPv4 DNS requests turned off. To disable this option, clear the **Enable resource-based IPV4 (A record) DNS requests** option when you create a new instance in the Amazon EC2 console. To disable this option using the AWS CLI, use the following command.
```
aws ec2 modify-private-dns-name-options --instance-id i-xxxxxxx --no-enable-resource-name-dns-a-record --no-dry-run
```
+ Amazon EC2 instances in shared subnets are not supported. They will fail to register to a cluster if they are used.
+ Your tasks must use the `awsvpc` network mode and the EC2. Tasks using Fargate always received a dedicated ENI regardless of how many are launched, so this feature is not needed.
+ Your tasks must be launched in the same Amazon VPC as your container instance. Your tasks will fail to start with an attribute error if they are not within the same VPC.
+ When launching a new container instance, the instance transitions to a `REGISTERING` status while the trunk elastic network interface is provisioned for the instance. If the registration fails, the instance transitions to a `REGISTRATION_FAILED` status. You can troubleshoot a failed registration by describing the container instance to view the `statusReason` field which describes the reason for the failure. The container instance then can be manually deregistered or terminated. Once the container instance is successfully deregistered or terminated, Amazon ECS will delete the trunk ENI.
**Note**
Amazon ECS emits container instance state change events which you can monitor for instances that transition to a `REGISTRATION_FAILED` state. For more information, see [Amazon ECS container instance state change events](ecs_container_instance_events.md).
+ Once the container instance is terminated, the instance transitions to a `DEREGISTERING` status while the trunk elastic network interface is deprovisioned. The instance then transitions to an `INACTIVE` status.
+ If a container instance in a public subnet with the increased ENI limits is stopped and then restarted, the instance loses its public IP address, and the container agent loses its connection.
+ When you enable `awsvpcTrunking`, container instances receive an additional ENI that uses the VPC's default security group, and is managed by Amazon ECS.
A default VPC comes with a public subnet in each Availability Zone, an internet gateway, and settings to enable DNS resolution. The subnet is a public subnet, because the main route table sends the subnet's traffic that is destined for the internet to the internet gateway. You can make a default subnet into a private subnet by removing the route from the destination 0.0.0.0/0 to the internet gateway. However, if you do this, no container instance running in that subnet can access the internet. You can add or delete security group rules to control the traffic into and out of your subnets. For more information, see [Security group rules](https://docs.aws.amazon.com/vpc/latest/userguide/security-group-rules.html) in the* Amazon Virtual Private Cloud User Guide*.
## Prerequisites
Before you launch a container instance with the increased ENI limits, the following prerequisites must be completed.
+ The service-linked role for Amazon ECS must be created. The Amazon ECS service-linked role provides Amazon ECS with the permissions to make calls to other AWS services on your behalf. This role is created for you automatically when you create a cluster, or if you create or update a service in the AWS Management Console. For more information, see [Using service-linked roles for Amazon ECS](using-service-linked-roles.md). You can also create the service-linked role with the following AWS CLI command.
```
aws iam [create-service-linked-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-service-linked-role.html) --aws-service-name ecs.amazonaws.com
```
+ Your account or container instance IAM role must enable the `awsvpcTrunking` account setting. We recommend that you create 2 container instance roles (`ecsInstanceRole`). You can then enable the `awsvpcTrunking` account setting for one role and use that role for tasks that require ENI trunking. For information about the container instance role, see [Amazon ECS container instance IAM role](instance_IAM_role.md).
After the prerequisites are met, you can launch a new container instance using one of the supported Amazon EC2 instance types, and the instance will have the increased ENI limits. For a list of supported instance types, see [Supported instances for increased Amazon ECS container network interfaces](eni-trunking-supported-instance-types.md). The container instance must have version `1.28.1` or later of the container agent and version `1.28.1-2` or later of the ecs-init package. If you use the latest Linux variant of the Amazon ECS-optimized AMI, these requirements will be met. For more information, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
**Important**
Amazon EC2 instances must have resource-based IPv4 DNS requests turned off. To disable this option, ensure the **Enable resource-based IPV4 (A record) DNS requests** option is deselected when creating a new instance using the Amazon EC2 console. To disable this option using the AWS CLI, use the following command.
```
aws ec2 modify-private-dns-name-options --instance-id i-xxxxxxx --no-enable-resource-name-dns-a-record --no-dry-run
```
**To view your container instances with increased ENI limits with the AWS CLI**
Each container instance has a default network interface, referred to as a trunk network interface. Use the following command to list your container instances with increased ENI limits by querying for the `ecs.awsvpc-trunk-id` attribute, which indicates it has a trunk network interface.
+ [list-attributes](https://docs.aws.amazon.com/cli/latest/reference/ecs/list-attributes.html) (AWS CLI)
```
aws ecs list-attributes \
--target-type container-instance \
--attribute-name ecs.awsvpc-trunk-id \
--cluster cluster_name \
--region us-east-1
```
+ [Get-ECSAttributeList](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ECSAttributeList.html) (AWS Tools for Windows PowerShell)
```
Get-ECSAttributeList -TargetType container-instance -AttributeName ecs.awsvpc-trunk-id -Region us-east-1
```
# Supported instances for increased Amazon ECS container network interfaces
The following shows the supported Amazon EC2 instance types and how many tasks using the `awsvpc` network mode can be launched on each instance type before and after enabling the `awsvpcTrunking` account setting.
**Important**
Although other instance types are supported in the same instance family, the `a1.metal`, `c5.metal`, `c5a.8xlarge`, `c5ad.8xlarge`, `c5d.metal`, `m5.metal`, `p3dn.24xlarge`, `r5.metal`, `r5.8xlarge`, and `r5d.metal` instance types are not supported.
The `c5n`, `d3`, `d3en`, `g3`, `g3s`, `g4dn`, `i3`, `i3en`, `inf1`, `m5dn`, `m5n`, `m5zn`, `mac1`, `r5b`, `r5n`, `r5dn`, `u-12tb1`, `u-6tb1`, `u-9tb1`, and `z1d` instance families are not supported.
**Topics**
+ [
## General purpose
](#eni-branch-gp)
+ [
## Compute optimized
](#eni-branch-co)
+ [
## Memory optimized
](#eni-branch-mo)
+ [
## Storage optimized
](#eni-branch-so)
+ [
## Accelerated computing
](#eni-branch-ac)
+ [
## High performance computing
](#eni-branch-hpc)
## General purpose
| Instance type | Task limit without ENI trunking | Task limit with ENI trunking |
| --- | --- | --- |
| a1.medium | 1 | 10 |
| a1.large | 2 | 10 |
| a1.xlarge | 3 | 20 |
| a1.2xlarge | 3 | 40 |
| a1.4xlarge | 7 | 60 |
| m5.large | 2 | 10 |
| m5.xlarge | 3 | 20 |
| m5.2xlarge | 3 | 40 |
| m5.4xlarge | 7 | 60 |
| m5.8xlarge | 7 | 60 |
| m5.12xlarge | 7 | 60 |
| m5.16xlarge | 14 | 120 |
| m5.24xlarge | 14 | 120 |
| m5a.large | 2 | 10 |
| m5a.xlarge | 3 | 20 |
| m5a.2xlarge | 3 | 40 |
| m5a.4xlarge | 7 | 60 |
| m5a.8xlarge | 7 | 60 |
| m5a.12xlarge | 7 | 60 |
| m5a.16xlarge | 14 | 120 |
| m5a.24xlarge | 14 | 120 |
| m5ad.large | 2 | 10 |
| m5ad.xlarge | 3 | 20 |
| m5ad.2xlarge | 3 | 40 |
| m5ad.4xlarge | 7 | 60 |
| m5ad.8xlarge | 7 | 60 |
| m5ad.12xlarge | 7 | 60 |
| m5ad.16xlarge | 14 | 120 |
| m5ad.24xlarge | 14 | 120 |
| m5d.large | 2 | 10 |
| m5d.xlarge | 3 | 20 |
| m5d.2xlarge | 3 | 40 |
| m5d.4xlarge | 7 | 60 |
| m5d.8xlarge | 7 | 60 |
| m5d.12xlarge | 7 | 60 |
| m5d.16xlarge | 14 | 120 |
| m5d.24xlarge | 14 | 120 |
| m5d.metal | 14 | 120 |
| m6a.large | 2 | 10 |
| m6a.xlarge | 3 | 20 |
| m6a.2xlarge | 3 | 40 |
| m6a.4xlarge | 7 | 60 |
| m6a.8xlarge | 7 | 90 |
| m6a.12xlarge | 7 | 120 |
| m6a.16xlarge | 14 | 120 |
| m6a.24xlarge | 14 | 120 |
| m6a.32xlarge | 14 | 120 |
| m6a.48xlarge | 14 | 120 |
| m6a.metal | 14 | 120 |
| m6g.medium | 1 | 4 |
| m6g.large | 2 | 10 |
| m6g.xlarge | 3 | 20 |
| m6g.2xlarge | 3 | 40 |
| m6g.4xlarge | 7 | 60 |
| m6g.8xlarge | 7 | 60 |
| m6g.12xlarge | 7 | 60 |
| m6g.16xlarge | 14 | 120 |
| m6g.metal | 14 | 120 |
| m6gd.medium | 1 | 4 |
| m6gd.large | 2 | 10 |
| m6gd.xlarge | 3 | 20 |
| m6gd.2xlarge | 3 | 40 |
| m6gd.4xlarge | 7 | 60 |
| m6gd.8xlarge | 7 | 60 |
| m6gd.12xlarge | 7 | 60 |
| m6gd.16xlarge | 14 | 120 |
| m6gd.metal | 14 | 120 |
| m6i.large | 2 | 10 |
| m6i.xlarge | 3 | 20 |
| m6i.2xlarge | 3 | 40 |
| m6i.4xlarge | 7 | 60 |
| m6i.8xlarge | 7 | 90 |
| m6i.12xlarge | 7 | 120 |
| m6i.16xlarge | 14 | 120 |
| m6i.24xlarge | 14 | 120 |
| m6i.32xlarge | 14 | 120 |
| m6i.metal | 14 | 120 |
| m6id.large | 2 | 10 |
| m6id.xlarge | 3 | 20 |
| m6id.2xlarge | 3 | 40 |
| m6id.4xlarge | 7 | 60 |
| m6id.8xlarge | 7 | 90 |
| m6id.12xlarge | 7 | 120 |
| m6id.16xlarge | 14 | 120 |
| m6id.24xlarge | 14 | 120 |
| m6id.32xlarge | 14 | 120 |
| m6id.metal | 14 | 120 |
| m6idn.large | 2 | 10 |
| m6idn.xlarge | 3 | 20 |
| m6idn.2xlarge | 3 | 40 |
| m6idn.4xlarge | 7 | 60 |
| m6idn.8xlarge | 7 | 90 |
| m6idn.12xlarge | 7 | 120 |
| m6idn.16xlarge | 14 | 120 |
| m6idn.24xlarge | 14 | 120 |
| m6idn.32xlarge | 15 | 120 |
| m6idn.metal | 15 | 120 |
| m6in.large | 2 | 10 |
| m6in.xlarge | 3 | 20 |
| m6in.2xlarge | 3 | 40 |
| m6in.4xlarge | 7 | 60 |
| m6in.8xlarge | 7 | 90 |
| m6in.12xlarge | 7 | 120 |
| m6in.16xlarge | 14 | 120 |
| m6in.24xlarge | 14 | 120 |
| m6in.32xlarge | 15 | 120 |
| m6in.metal | 15 | 120 |
| m7a.medium | 1 | 4 |
| m7a.large | 2 | 10 |
| m7a.xlarge | 3 | 20 |
| m7a.2xlarge | 3 | 40 |
| m7a.4xlarge | 7 | 60 |
| m7a.8xlarge | 7 | 90 |
| m7a.12xlarge | 7 | 120 |
| m7a.16xlarge | 14 | 120 |
| m7a.24xlarge | 14 | 120 |
| m7a.32xlarge | 14 | 120 |
| m7a.48xlarge | 14 | 120 |
| m7a.metal-48xl | 14 | 120 |
| m7g.medium | 1 | 4 |
| m7g.large | 2 | 10 |
| m7g.xlarge | 3 | 20 |
| m7g.2xlarge | 3 | 40 |
| m7g.4xlarge | 7 | 60 |
| m7g.8xlarge | 7 | 60 |
| m7g.12xlarge | 7 | 60 |
| m7g.16xlarge | 14 | 120 |
| m7g.metal | 14 | 120 |
| m7gd.medium | 1 | 4 |
| m7gd.large | 2 | 10 |
| m7gd.xlarge | 3 | 20 |
| m7gd.2xlarge | 3 | 40 |
| m7gd.4xlarge | 7 | 60 |
| m7gd.8xlarge | 7 | 60 |
| m7gd.12xlarge | 7 | 60 |
| m7gd.16xlarge | 14 | 120 |
| m7gd.metal | 14 | 120 |
| m7i.large | 2 | 10 |
| m7i.xlarge | 3 | 20 |
| m7i.2xlarge | 3 | 40 |
| m7i.4xlarge | 7 | 60 |
| m7i.8xlarge | 7 | 90 |
| m7i.12xlarge | 7 | 120 |
| m7i.16xlarge | 14 | 120 |
| m7i.24xlarge | 14 | 120 |
| m7i.48xlarge | 14 | 120 |
| m7i.metal-24xl | 14 | 120 |
| m7i.metal-48xl | 14 | 120 |
| m7i-flex.large | 2 | 4 |
| m7i-flex.xlarge | 3 | 10 |
| m7i-flex.2xlarge | 3 | 20 |
| m7i-flex.4xlarge | 7 | 40 |
| m7i-flex.8xlarge | 7 | 60 |
| m7i-flex.12xlarge | 7 | 120 |
| m7i-flex.16xlarge | 14 | 120 |
| m8a.medium | 1 | 4 |
| m8a.large | 2 | 10 |
| m8a.xlarge | 3 | 20 |
| m8a.2xlarge | 3 | 40 |
| m8a.4xlarge | 7 | 60 |
| m8a.8xlarge | 9 | 90 |
| m8a.12xlarge | 11 | 120 |
| m8a.16xlarge | 15 | 120 |
| m8a.24xlarge | 15 | 120 |
| m8a.48xlarge | 23 | 120 |
| m8a.metal-24xl | 15 | 120 |
| m8a.metal-48xl | 23 | 120 |
| m8azn.medium | 2 | 4 |
| m8azn.large | 3 | 10 |
| m8azn.xlarge | 3 | 20 |
| m8azn.3xlarge | 7 | 40 |
| m8azn.6xlarge | 7 | 60 |
| m8azn.12xlarge | 15 | 120 |
| m8azn.24xlarge | 15 | 120 |
| m8azn.metal-12xl | 15 | 120 |
| m8azn.metal-24xl | 15 | 120 |
| m8g.medium | 1 | 4 |
| m8g.large | 2 | 10 |
| m8g.xlarge | 3 | 20 |
| m8g.2xlarge | 3 | 40 |
| m8g.4xlarge | 7 | 60 |
| m8g.8xlarge | 7 | 60 |
| m8g.12xlarge | 7 | 60 |
| m8g.16xlarge | 14 | 120 |
| m8g.24xlarge | 14 | 120 |
| m8g.48xlarge | 14 | 120 |
| m8g.metal-24xl | 14 | 120 |
| m8g.metal-48xl | 14 | 120 |
| m8gb.medium | 1 | 4 |
| m8gb.large | 2 | 10 |
| m8gb.xlarge | 3 | 20 |
| m8gb.2xlarge | 3 | 40 |
| m8gb.4xlarge | 7 | 60 |
| m8gb.8xlarge | 9 | 60 |
| m8gb.12xlarge | 11 | 60 |
| m8gb.16xlarge | 15 | 120 |
| m8gb.24xlarge | 23 | 120 |
| m8gb.48xlarge | 23 | 120 |
| m8gb.metal-24xl | 23 | 120 |
| m8gb.metal-48xl | 23 | 120 |
| m8gd.medium | 1 | 4 |
| m8gd.large | 2 | 10 |
| m8gd.xlarge | 3 | 20 |
| m8gd.2xlarge | 3 | 40 |
| m8gd.4xlarge | 7 | 60 |
| m8gd.8xlarge | 7 | 60 |
| m8gd.12xlarge | 7 | 60 |
| m8gd.16xlarge | 14 | 120 |
| m8gd.24xlarge | 14 | 120 |
| m8gd.48xlarge | 14 | 120 |
| m8gd.metal-24xl | 14 | 120 |
| m8gd.metal-48xl | 14 | 120 |
| m8gn.medium | 1 | 4 |
| m8gn.large | 2 | 10 |
| m8gn.xlarge | 3 | 20 |
| m8gn.2xlarge | 3 | 40 |
| m8gn.4xlarge | 7 | 60 |
| m8gn.8xlarge | 9 | 60 |
| m8gn.12xlarge | 11 | 60 |
| m8gn.16xlarge | 15 | 120 |
| m8gn.24xlarge | 23 | 120 |
| m8gn.48xlarge | 23 | 120 |
| m8gn.metal-24xl | 23 | 120 |
| m8gn.metal-48xl | 23 | 120 |
| m8i.large | 2 | 10 |
| m8i.xlarge | 3 | 20 |
| m8i.2xlarge | 3 | 40 |
| m8i.4xlarge | 7 | 60 |
| m8i.8xlarge | 9 | 90 |
| m8i.12xlarge | 11 | 120 |
| m8i.16xlarge | 15 | 120 |
| m8i.24xlarge | 15 | 120 |
| m8i.32xlarge | 23 | 120 |
| m8i.48xlarge | 23 | 120 |
| m8i.96xlarge | 23 | 120 |
| m8i.metal-48xl | 23 | 120 |
| m8i.metal-96xl | 23 | 120 |
| m8id.large | 2 | 10 |
| m8id.xlarge | 3 | 20 |
| m8id.2xlarge | 3 | 40 |
| m8id.4xlarge | 7 | 60 |
| m8id.8xlarge | 9 | 90 |
| m8id.12xlarge | 11 | 120 |
| m8id.16xlarge | 15 | 120 |
| m8id.24xlarge | 15 | 120 |
| m8id.32xlarge | 23 | 120 |
| m8id.48xlarge | 23 | 120 |
| m8id.96xlarge | 23 | 120 |
| m8id.metal-48xl | 23 | 120 |
| m8id.metal-96xl | 23 | 120 |
| m8i-flex.large | 2 | 4 |
| m8i-flex.xlarge | 3 | 10 |
| m8i-flex.2xlarge | 3 | 20 |
| m8i-flex.4xlarge | 7 | 40 |
| m8i-flex.8xlarge | 9 | 60 |
| m8i-flex.12xlarge | 11 | 120 |
| m8i-flex.16xlarge | 15 | 120 |
| mac2.metal | 7 | 12 |
| mac2-m1ultra.metal | 7 | 12 |
| mac2-m2.metal | 7 | 12 |
| mac2-m2pro.metal | 7 | 12 |
| mac-m4.metal | 7 | 12 |
| mac-m4pro.metal | 7 | 12 |
| mac-m4max.metal | 7 | 12 |
## Compute optimized
| Instance type | Task limit without ENI trunking | Task limit with ENI trunking |
| --- | --- | --- |
| c5.large | 2 | 10 |
| c5.xlarge | 3 | 20 |
| c5.2xlarge | 3 | 40 |
| c5.4xlarge | 7 | 60 |
| c5.9xlarge | 7 | 60 |
| c5.12xlarge | 7 | 60 |
| c5.18xlarge | 14 | 120 |
| c5.24xlarge | 14 | 120 |
| c5a.large | 2 | 10 |
| c5a.xlarge | 3 | 20 |
| c5a.2xlarge | 3 | 40 |
| c5a.4xlarge | 7 | 60 |
| c5a.12xlarge | 7 | 60 |
| c5a.16xlarge | 14 | 120 |
| c5a.24xlarge | 14 | 120 |
| c5ad.large | 2 | 10 |
| c5ad.xlarge | 3 | 20 |
| c5ad.2xlarge | 3 | 40 |
| c5ad.4xlarge | 7 | 60 |
| c5ad.12xlarge | 7 | 60 |
| c5ad.16xlarge | 14 | 120 |
| c5ad.24xlarge | 14 | 120 |
| c5d.large | 2 | 10 |
| c5d.xlarge | 3 | 20 |
| c5d.2xlarge | 3 | 40 |
| c5d.4xlarge | 7 | 60 |
| c5d.9xlarge | 7 | 60 |
| c5d.12xlarge | 7 | 60 |
| c5d.18xlarge | 14 | 120 |
| c5d.24xlarge | 14 | 120 |
| c6a.large | 2 | 10 |
| c6a.xlarge | 3 | 20 |
| c6a.2xlarge | 3 | 40 |
| c6a.4xlarge | 7 | 60 |
| c6a.8xlarge | 7 | 90 |
| c6a.12xlarge | 7 | 120 |
| c6a.16xlarge | 14 | 120 |
| c6a.24xlarge | 14 | 120 |
| c6a.32xlarge | 14 | 120 |
| c6a.48xlarge | 14 | 120 |
| c6a.metal | 14 | 120 |
| c6g.medium | 1 | 4 |
| c6g.large | 2 | 10 |
| c6g.xlarge | 3 | 20 |
| c6g.2xlarge | 3 | 40 |
| c6g.4xlarge | 7 | 60 |
| c6g.8xlarge | 7 | 60 |
| c6g.12xlarge | 7 | 60 |
| c6g.16xlarge | 14 | 120 |
| c6g.metal | 14 | 120 |
| c6gd.medium | 1 | 4 |
| c6gd.large | 2 | 10 |
| c6gd.xlarge | 3 | 20 |
| c6gd.2xlarge | 3 | 40 |
| c6gd.4xlarge | 7 | 60 |
| c6gd.8xlarge | 7 | 60 |
| c6gd.12xlarge | 7 | 60 |
| c6gd.16xlarge | 14 | 120 |
| c6gd.metal | 14 | 120 |
| c6gn.medium | 1 | 4 |
| c6gn.large | 2 | 10 |
| c6gn.xlarge | 3 | 20 |
| c6gn.2xlarge | 3 | 40 |
| c6gn.4xlarge | 7 | 60 |
| c6gn.8xlarge | 7 | 60 |
| c6gn.12xlarge | 7 | 60 |
| c6gn.16xlarge | 14 | 120 |
| c6i.large | 2 | 10 |
| c6i.xlarge | 3 | 20 |
| c6i.2xlarge | 3 | 40 |
| c6i.4xlarge | 7 | 60 |
| c6i.8xlarge | 7 | 90 |
| c6i.12xlarge | 7 | 120 |
| c6i.16xlarge | 14 | 120 |
| c6i.24xlarge | 14 | 120 |
| c6i.32xlarge | 14 | 120 |
| c6i.metal | 14 | 120 |
| c6id.large | 2 | 10 |
| c6id.xlarge | 3 | 20 |
| c6id.2xlarge | 3 | 40 |
| c6id.4xlarge | 7 | 60 |
| c6id.8xlarge | 7 | 90 |
| c6id.12xlarge | 7 | 120 |
| c6id.16xlarge | 14 | 120 |
| c6id.24xlarge | 14 | 120 |
| c6id.32xlarge | 14 | 120 |
| c6id.metal | 14 | 120 |
| c6in.large | 2 | 10 |
| c6in.xlarge | 3 | 20 |
| c6in.2xlarge | 3 | 40 |
| c6in.4xlarge | 7 | 60 |
| c6in.8xlarge | 7 | 90 |
| c6in.12xlarge | 7 | 120 |
| c6in.16xlarge | 14 | 120 |
| c6in.24xlarge | 14 | 120 |
| c6in.32xlarge | 15 | 120 |
| c6in.metal | 15 | 120 |
| c7a.medium | 1 | 4 |
| c7a.large | 2 | 10 |
| c7a.xlarge | 3 | 20 |
| c7a.2xlarge | 3 | 40 |
| c7a.4xlarge | 7 | 60 |
| c7a.8xlarge | 7 | 90 |
| c7a.12xlarge | 7 | 120 |
| c7a.16xlarge | 14 | 120 |
| c7a.24xlarge | 14 | 120 |
| c7a.32xlarge | 14 | 120 |
| c7a.48xlarge | 14 | 120 |
| c7a.metal-48xl | 14 | 120 |
| c7g.medium | 1 | 4 |
| c7g.large | 2 | 10 |
| c7g.xlarge | 3 | 20 |
| c7g.2xlarge | 3 | 40 |
| c7g.4xlarge | 7 | 60 |
| c7g.8xlarge | 7 | 60 |
| c7g.12xlarge | 7 | 60 |
| c7g.16xlarge | 14 | 120 |
| c7g.metal | 14 | 120 |
| c7gd.medium | 1 | 4 |
| c7gd.large | 2 | 10 |
| c7gd.xlarge | 3 | 20 |
| c7gd.2xlarge | 3 | 40 |
| c7gd.4xlarge | 7 | 60 |
| c7gd.8xlarge | 7 | 60 |
| c7gd.12xlarge | 7 | 60 |
| c7gd.16xlarge | 14 | 120 |
| c7gd.metal | 14 | 120 |
| c7gn.medium | 1 | 4 |
| c7gn.large | 2 | 10 |
| c7gn.xlarge | 3 | 20 |
| c7gn.2xlarge | 3 | 40 |
| c7gn.4xlarge | 7 | 60 |
| c7gn.8xlarge | 7 | 60 |
| c7gn.12xlarge | 7 | 60 |
| c7gn.16xlarge | 14 | 120 |
| c7gn.metal | 14 | 120 |
| c7i.large | 2 | 10 |
| c7i.xlarge | 3 | 20 |
| c7i.2xlarge | 3 | 40 |
| c7i.4xlarge | 7 | 60 |
| c7i.8xlarge | 7 | 90 |
| c7i.12xlarge | 7 | 120 |
| c7i.16xlarge | 14 | 120 |
| c7i.24xlarge | 14 | 120 |
| c7i.48xlarge | 14 | 120 |
| c7i.metal-24xl | 14 | 120 |
| c7i.metal-48xl | 14 | 120 |
| c7i-flex.large | 2 | 4 |
| c7i-flex.xlarge | 3 | 10 |
| c7i-flex.2xlarge | 3 | 20 |
| c7i-flex.4xlarge | 7 | 40 |
| c7i-flex.8xlarge | 7 | 60 |
| c7i-flex.12xlarge | 7 | 120 |
| c7i-flex.16xlarge | 14 | 120 |
| c8a.medium | 1 | 4 |
| c8a.large | 2 | 10 |
| c8a.xlarge | 3 | 20 |
| c8a.2xlarge | 3 | 40 |
| c8a.4xlarge | 7 | 60 |
| c8a.8xlarge | 9 | 90 |
| c8a.12xlarge | 11 | 120 |
| c8a.16xlarge | 15 | 120 |
| c8a.24xlarge | 15 | 120 |
| c8a.48xlarge | 23 | 120 |
| c8a.metal-24xl | 15 | 120 |
| c8a.metal-48xl | 23 | 120 |
| c8g.medium | 1 | 4 |
| c8g.large | 2 | 10 |
| c8g.xlarge | 3 | 20 |
| c8g.2xlarge | 3 | 40 |
| c8g.4xlarge | 7 | 60 |
| c8g.8xlarge | 7 | 60 |
| c8g.12xlarge | 7 | 60 |
| c8g.16xlarge | 14 | 120 |
| c8g.24xlarge | 14 | 120 |
| c8g.48xlarge | 14 | 120 |
| c8g.metal-24xl | 14 | 120 |
| c8g.metal-48xl | 14 | 120 |
| c8gb.medium | 1 | 4 |
| c8gb.large | 2 | 10 |
| c8gb.xlarge | 3 | 20 |
| c8gb.2xlarge | 3 | 40 |
| c8gb.4xlarge | 7 | 60 |
| c8gb.8xlarge | 9 | 60 |
| c8gb.12xlarge | 11 | 60 |
| c8gb.16xlarge | 15 | 120 |
| c8gb.24xlarge | 23 | 120 |
| c8gb.48xlarge | 23 | 120 |
| c8gb.metal-24xl | 23 | 120 |
| c8gb.metal-48xl | 23 | 120 |
| c8gd.medium | 1 | 4 |
| c8gd.large | 2 | 10 |
| c8gd.xlarge | 3 | 20 |
| c8gd.2xlarge | 3 | 40 |
| c8gd.4xlarge | 7 | 60 |
| c8gd.8xlarge | 7 | 60 |
| c8gd.12xlarge | 7 | 60 |
| c8gd.16xlarge | 14 | 120 |
| c8gd.24xlarge | 14 | 120 |
| c8gd.48xlarge | 14 | 120 |
| c8gd.metal-24xl | 14 | 120 |
| c8gd.metal-48xl | 14 | 120 |
| c8gn.medium | 1 | 4 |
| c8gn.large | 2 | 10 |
| c8gn.xlarge | 3 | 20 |
| c8gn.2xlarge | 3 | 40 |
| c8gn.4xlarge | 7 | 60 |
| c8gn.8xlarge | 9 | 60 |
| c8gn.12xlarge | 11 | 60 |
| c8gn.16xlarge | 15 | 120 |
| c8gn.24xlarge | 23 | 120 |
| c8gn.48xlarge | 23 | 120 |
| c8gn.metal-24xl | 23 | 120 |
| c8gn.metal-48xl | 23 | 120 |
| c8i.large | 2 | 10 |
| c8i.xlarge | 3 | 20 |
| c8i.2xlarge | 3 | 40 |
| c8i.4xlarge | 7 | 60 |
| c8i.8xlarge | 9 | 90 |
| c8i.12xlarge | 11 | 120 |
| c8i.16xlarge | 15 | 120 |
| c8i.24xlarge | 15 | 120 |
| c8i.32xlarge | 23 | 120 |
| c8i.48xlarge | 23 | 120 |
| c8i.96xlarge | 23 | 120 |
| c8i.metal-48xl | 23 | 120 |
| c8i.metal-96xl | 23 | 120 |
| c8ib.large | 3 | 10 |
| c8ib.xlarge | 3 | 20 |
| c8ib.2xlarge | 3 | 40 |
| c8ib.4xlarge | 7 | 60 |
| c8ib.8xlarge | 7 | 90 |
| c8ib.12xlarge | 11 | 120 |
| c8ib.16xlarge | 15 | 120 |
| c8ib.24xlarge | 15 | 120 |
| c8ib.32xlarge | 15 | 120 |
| c8ib.48xlarge | 23 | 120 |
| c8ib.96xlarge | 23 | 120 |
| c8ib.metal-48xl | 23 | 120 |
| c8ib.metal-96xl | 23 | 120 |
| c8id.large | 2 | 10 |
| c8id.xlarge | 3 | 20 |
| c8id.2xlarge | 3 | 40 |
| c8id.4xlarge | 7 | 60 |
| c8id.8xlarge | 9 | 90 |
| c8id.12xlarge | 11 | 120 |
| c8id.16xlarge | 15 | 120 |
| c8id.24xlarge | 15 | 120 |
| c8id.32xlarge | 23 | 120 |
| c8id.48xlarge | 23 | 120 |
| c8id.96xlarge | 23 | 120 |
| c8id.metal-48xl | 23 | 120 |
| c8id.metal-96xl | 23 | 120 |
| c8in.large | 3 | 10 |
| c8in.xlarge | 3 | 20 |
| c8in.2xlarge | 3 | 40 |
| c8in.4xlarge | 7 | 60 |
| c8in.8xlarge | 7 | 90 |
| c8in.12xlarge | 11 | 120 |
| c8in.16xlarge | 15 | 120 |
| c8in.24xlarge | 15 | 120 |
| c8in.32xlarge | 15 | 120 |
| c8in.48xlarge | 23 | 120 |
| c8in.96xlarge | 23 | 120 |
| c8in.metal-48xl | 23 | 120 |
| c8in.metal-96xl | 23 | 120 |
| c8i-flex.large | 2 | 4 |
| c8i-flex.xlarge | 3 | 10 |
| c8i-flex.2xlarge | 3 | 20 |
| c8i-flex.4xlarge | 7 | 40 |
| c8i-flex.8xlarge | 9 | 60 |
| c8i-flex.12xlarge | 11 | 120 |
| c8i-flex.16xlarge | 15 | 120 |
## Memory optimized
| Instance type | Task limit without ENI trunking | Task limit with ENI trunking |
| --- | --- | --- |
| r5.large | 2 | 10 |
| r5.xlarge | 3 | 20 |
| r5.2xlarge | 3 | 40 |
| r5.4xlarge | 7 | 60 |
| r5.12xlarge | 7 | 60 |
| r5.16xlarge | 14 | 120 |
| r5.24xlarge | 14 | 120 |
| r5a.large | 2 | 10 |
| r5a.xlarge | 3 | 20 |
| r5a.2xlarge | 3 | 40 |
| r5a.4xlarge | 7 | 60 |
| r5a.8xlarge | 7 | 60 |
| r5a.12xlarge | 7 | 60 |
| r5a.16xlarge | 14 | 120 |
| r5a.24xlarge | 14 | 120 |
| r5ad.large | 2 | 10 |
| r5ad.xlarge | 3 | 20 |
| r5ad.2xlarge | 3 | 40 |
| r5ad.4xlarge | 7 | 60 |
| r5ad.8xlarge | 7 | 60 |
| r5ad.12xlarge | 7 | 60 |
| r5ad.16xlarge | 14 | 120 |
| r5ad.24xlarge | 14 | 120 |
| r5b.16xlarge | 14 | 120 |
| r5d.large | 2 | 10 |
| r5d.xlarge | 3 | 20 |
| r5d.2xlarge | 3 | 40 |
| r5d.4xlarge | 7 | 60 |
| r5d.8xlarge | 7 | 60 |
| r5d.12xlarge | 7 | 60 |
| r5d.16xlarge | 14 | 120 |
| r5d.24xlarge | 14 | 120 |
| r5dn.16xlarge | 14 | 120 |
| r6a.large | 2 | 10 |
| r6a.xlarge | 3 | 20 |
| r6a.2xlarge | 3 | 40 |
| r6a.4xlarge | 7 | 60 |
| r6a.8xlarge | 7 | 90 |
| r6a.12xlarge | 7 | 120 |
| r6a.16xlarge | 14 | 120 |
| r6a.24xlarge | 14 | 120 |
| r6a.32xlarge | 14 | 120 |
| r6a.48xlarge | 14 | 120 |
| r6a.metal | 14 | 120 |
| r6g.medium | 1 | 4 |
| r6g.large | 2 | 10 |
| r6g.xlarge | 3 | 20 |
| r6g.2xlarge | 3 | 40 |
| r6g.4xlarge | 7 | 60 |
| r6g.8xlarge | 7 | 60 |
| r6g.12xlarge | 7 | 60 |
| r6g.16xlarge | 14 | 120 |
| r6g.metal | 14 | 120 |
| r6gd.medium | 1 | 4 |
| r6gd.large | 2 | 10 |
| r6gd.xlarge | 3 | 20 |
| r6gd.2xlarge | 3 | 40 |
| r6gd.4xlarge | 7 | 60 |
| r6gd.8xlarge | 7 | 60 |
| r6gd.12xlarge | 7 | 60 |
| r6gd.16xlarge | 14 | 120 |
| r6gd.metal | 14 | 120 |
| r6i.large | 2 | 10 |
| r6i.xlarge | 3 | 20 |
| r6i.2xlarge | 3 | 40 |
| r6i.4xlarge | 7 | 60 |
| r6i.8xlarge | 7 | 90 |
| r6i.12xlarge | 7 | 120 |
| r6i.16xlarge | 14 | 120 |
| r6i.24xlarge | 14 | 120 |
| r6i.32xlarge | 14 | 120 |
| r6i.metal | 14 | 120 |
| r6id.large | 2 | 10 |
| r6id.xlarge | 3 | 20 |
| r6id.2xlarge | 3 | 40 |
| r6id.4xlarge | 7 | 60 |
| r6id.8xlarge | 7 | 90 |
| r6id.12xlarge | 7 | 120 |
| r6id.16xlarge | 14 | 120 |
| r6id.24xlarge | 14 | 120 |
| r6id.32xlarge | 14 | 120 |
| r6id.metal | 14 | 120 |
| r6idn.large | 2 | 10 |
| r6idn.xlarge | 3 | 20 |
| r6idn.2xlarge | 3 | 40 |
| r6idn.4xlarge | 7 | 60 |
| r6idn.8xlarge | 7 | 90 |
| r6idn.12xlarge | 7 | 120 |
| r6idn.16xlarge | 14 | 120 |
| r6idn.24xlarge | 14 | 120 |
| r6idn.32xlarge | 15 | 120 |
| r6idn.metal | 15 | 120 |
| r6in.large | 2 | 10 |
| r6in.xlarge | 3 | 20 |
| r6in.2xlarge | 3 | 40 |
| r6in.4xlarge | 7 | 60 |
| r6in.8xlarge | 7 | 90 |
| r6in.12xlarge | 7 | 120 |
| r6in.16xlarge | 14 | 120 |
| r6in.24xlarge | 14 | 120 |
| r6in.32xlarge | 15 | 120 |
| r6in.metal | 15 | 120 |
| r7a.medium | 1 | 4 |
| r7a.large | 2 | 10 |
| r7a.xlarge | 3 | 20 |
| r7a.2xlarge | 3 | 40 |
| r7a.4xlarge | 7 | 60 |
| r7a.8xlarge | 7 | 90 |
| r7a.12xlarge | 7 | 120 |
| r7a.16xlarge | 14 | 120 |
| r7a.24xlarge | 14 | 120 |
| r7a.32xlarge | 14 | 120 |
| r7a.48xlarge | 14 | 120 |
| r7a.metal-48xl | 14 | 120 |
| r7g.medium | 1 | 4 |
| r7g.large | 2 | 10 |
| r7g.xlarge | 3 | 20 |
| r7g.2xlarge | 3 | 40 |
| r7g.4xlarge | 7 | 60 |
| r7g.8xlarge | 7 | 60 |
| r7g.12xlarge | 7 | 60 |
| r7g.16xlarge | 14 | 120 |
| r7g.metal | 14 | 120 |
| r7gd.medium | 1 | 4 |
| r7gd.large | 2 | 10 |
| r7gd.xlarge | 3 | 20 |
| r7gd.2xlarge | 3 | 40 |
| r7gd.4xlarge | 7 | 60 |
| r7gd.8xlarge | 7 | 60 |
| r7gd.12xlarge | 7 | 60 |
| r7gd.16xlarge | 14 | 120 |
| r7gd.metal | 14 | 120 |
| r7i.large | 2 | 10 |
| r7i.xlarge | 3 | 20 |
| r7i.2xlarge | 3 | 40 |
| r7i.4xlarge | 7 | 60 |
| r7i.8xlarge | 7 | 90 |
| r7i.12xlarge | 7 | 120 |
| r7i.16xlarge | 14 | 120 |
| r7i.24xlarge | 14 | 120 |
| r7i.48xlarge | 14 | 120 |
| r7i.metal-24xl | 14 | 120 |
| r7i.metal-48xl | 14 | 120 |
| r7iz.large | 2 | 10 |
| r7iz.xlarge | 3 | 20 |
| r7iz.2xlarge | 3 | 40 |
| r7iz.4xlarge | 7 | 60 |
| r7iz.8xlarge | 7 | 90 |
| r7iz.12xlarge | 7 | 120 |
| r7iz.16xlarge | 14 | 120 |
| r7iz.32xlarge | 14 | 120 |
| r7iz.metal-16xl | 14 | 120 |
| r7iz.metal-32xl | 14 | 120 |
| r8a.medium | 1 | 4 |
| r8a.large | 2 | 10 |
| r8a.xlarge | 3 | 20 |
| r8a.2xlarge | 3 | 40 |
| r8a.4xlarge | 7 | 60 |
| r8a.8xlarge | 9 | 90 |
| r8a.12xlarge | 11 | 120 |
| r8a.16xlarge | 15 | 120 |
| r8a.24xlarge | 15 | 120 |
| r8a.48xlarge | 23 | 120 |
| r8a.metal-24xl | 15 | 120 |
| r8a.metal-48xl | 23 | 120 |
| r8g.medium | 1 | 4 |
| r8g.large | 2 | 10 |
| r8g.xlarge | 3 | 20 |
| r8g.2xlarge | 3 | 40 |
| r8g.4xlarge | 7 | 60 |
| r8g.8xlarge | 7 | 60 |
| r8g.12xlarge | 7 | 60 |
| r8g.16xlarge | 14 | 120 |
| r8g.24xlarge | 14 | 120 |
| r8g.48xlarge | 14 | 120 |
| r8g.metal-24xl | 14 | 120 |
| r8g.metal-48xl | 14 | 120 |
| r8gb.medium | 1 | 4 |
| r8gb.large | 2 | 10 |
| r8gb.xlarge | 3 | 20 |
| r8gb.2xlarge | 3 | 40 |
| r8gb.4xlarge | 7 | 60 |
| r8gb.8xlarge | 9 | 60 |
| r8gb.12xlarge | 11 | 60 |
| r8gb.16xlarge | 15 | 120 |
| r8gb.24xlarge | 23 | 120 |
| r8gb.48xlarge | 23 | 120 |
| r8gb.metal-24xl | 23 | 120 |
| r8gb.metal-48xl | 23 | 120 |
| r8gd.medium | 1 | 4 |
| r8gd.large | 2 | 10 |
| r8gd.xlarge | 3 | 20 |
| r8gd.2xlarge | 3 | 40 |
| r8gd.4xlarge | 7 | 60 |
| r8gd.8xlarge | 7 | 60 |
| r8gd.12xlarge | 7 | 60 |
| r8gd.16xlarge | 14 | 120 |
| r8gd.24xlarge | 14 | 120 |
| r8gd.48xlarge | 14 | 120 |
| r8gd.metal-24xl | 14 | 120 |
| r8gd.metal-48xl | 14 | 120 |
| r8gn.medium | 1 | 4 |
| r8gn.large | 2 | 10 |
| r8gn.xlarge | 3 | 20 |
| r8gn.2xlarge | 3 | 40 |
| r8gn.4xlarge | 7 | 60 |
| r8gn.8xlarge | 9 | 60 |
| r8gn.12xlarge | 11 | 60 |
| r8gn.16xlarge | 15 | 120 |
| r8gn.24xlarge | 23 | 120 |
| r8gn.48xlarge | 23 | 120 |
| r8gn.metal-24xl | 23 | 120 |
| r8gn.metal-48xl | 23 | 120 |
| r8i.large | 2 | 10 |
| r8i.xlarge | 3 | 20 |
| r8i.2xlarge | 3 | 40 |
| r8i.4xlarge | 7 | 60 |
| r8i.8xlarge | 9 | 90 |
| r8i.12xlarge | 11 | 120 |
| r8i.16xlarge | 15 | 120 |
| r8i.24xlarge | 15 | 120 |
| r8i.32xlarge | 23 | 120 |
| r8i.48xlarge | 23 | 120 |
| r8i.96xlarge | 23 | 120 |
| r8i.metal-48xl | 23 | 120 |
| r8i.metal-96xl | 23 | 120 |
| r8id.large | 2 | 10 |
| r8id.xlarge | 3 | 20 |
| r8id.2xlarge | 3 | 40 |
| r8id.4xlarge | 7 | 60 |
| r8id.8xlarge | 9 | 90 |
| r8id.12xlarge | 11 | 120 |
| r8id.16xlarge | 15 | 120 |
| r8id.24xlarge | 15 | 120 |
| r8id.32xlarge | 23 | 120 |
| r8id.48xlarge | 23 | 120 |
| r8id.96xlarge | 23 | 120 |
| r8id.metal-48xl | 23 | 120 |
| r8id.metal-96xl | 23 | 120 |
| r8i-flex.large | 2 | 4 |
| r8i-flex.xlarge | 3 | 10 |
| r8i-flex.2xlarge | 3 | 20 |
| r8i-flex.4xlarge | 7 | 40 |
| r8i-flex.8xlarge | 9 | 60 |
| r8i-flex.12xlarge | 11 | 120 |
| r8i-flex.16xlarge | 15 | 120 |
| u-3tb1.56xlarge | 7 | 12 |
| u-6tb1.56xlarge | 14 | 12 |
| u-18tb1.112xlarge | 14 | 12 |
| u-18tb1.metal | 14 | 12 |
| u-24tb1.112xlarge | 14 | 12 |
| u-24tb1.metal | 14 | 12 |
| u7i-6tb.112xlarge | 14 | 120 |
| u7i-8tb.112xlarge | 14 | 120 |
| u7i-12tb.224xlarge | 14 | 120 |
| u7in-16tb.224xlarge | 15 | 120 |
| u7in-24tb.224xlarge | 15 | 120 |
| u7in-32tb.224xlarge | 15 | 120 |
| u7inh-32tb.480xlarge | 15 | 120 |
| x2gd.medium | 1 | 10 |
| x2gd.large | 2 | 10 |
| x2gd.xlarge | 3 | 20 |
| x2gd.2xlarge | 3 | 40 |
| x2gd.4xlarge | 7 | 60 |
| x2gd.8xlarge | 7 | 60 |
| x2gd.12xlarge | 7 | 60 |
| x2gd.16xlarge | 14 | 120 |
| x2gd.metal | 14 | 120 |
| x2idn.16xlarge | 14 | 120 |
| x2idn.24xlarge | 14 | 120 |
| x2idn.32xlarge | 14 | 120 |
| x2idn.metal | 14 | 120 |
| x2iedn.xlarge | 3 | 13 |
| x2iedn.2xlarge | 3 | 29 |
| x2iedn.4xlarge | 7 | 60 |
| x2iedn.8xlarge | 7 | 120 |
| x2iedn.16xlarge | 14 | 120 |
| x2iedn.24xlarge | 14 | 120 |
| x2iedn.32xlarge | 14 | 120 |
| x2iedn.metal | 14 | 120 |
| x2iezn.2xlarge | 3 | 64 |
| x2iezn.4xlarge | 7 | 120 |
| x2iezn.6xlarge | 7 | 120 |
| x2iezn.8xlarge | 7 | 120 |
| x2iezn.12xlarge | 14 | 120 |
| x2iezn.metal | 14 | 120 |
| x8g.medium | 1 | 4 |
| x8g.large | 2 | 10 |
| x8g.xlarge | 3 | 20 |
| x8g.2xlarge | 3 | 40 |
| x8g.4xlarge | 7 | 60 |
| x8g.8xlarge | 7 | 60 |
| x8g.12xlarge | 7 | 60 |
| x8g.16xlarge | 14 | 120 |
| x8g.24xlarge | 14 | 120 |
| x8g.48xlarge | 14 | 120 |
| x8g.metal-24xl | 14 | 120 |
| x8g.metal-48xl | 14 | 120 |
| x8aedz.large | 3 | 10 |
| x8aedz.xlarge | 3 | 20 |
| x8aedz.3xlarge | 7 | 40 |
| x8aedz.6xlarge | 7 | 60 |
| x8aedz.12xlarge | 15 | 120 |
| x8aedz.24xlarge | 15 | 120 |
| x8aedz.metal-12xl | 15 | 120 |
| x8aedz.metal-24xl | 15 | 120 |
| x8i.large | 2 | 10 |
| x8i.xlarge | 3 | 20 |
| x8i.2xlarge | 3 | 40 |
| x8i.4xlarge | 7 | 60 |
| x8i.8xlarge | 9 | 90 |
| x8i.12xlarge | 11 | 120 |
| x8i.16xlarge | 15 | 120 |
| x8i.24xlarge | 15 | 120 |
| x8i.32xlarge | 23 | 120 |
| x8i.48xlarge | 23 | 120 |
| x8i.64xlarge | 23 | 120 |
| x8i.96xlarge | 23 | 120 |
| x8i.metal-48xl | 23 | 120 |
| x8i.metal-96xl | 23 | 120 |
## Storage optimized
| Instance type | Task limit without ENI trunking | Task limit with ENI trunking |
| --- | --- | --- |
| i4g.large | 2 | 10 |
| i4g.xlarge | 3 | 20 |
| i4g.2xlarge | 3 | 40 |
| i4g.4xlarge | 7 | 60 |
| i4g.8xlarge | 7 | 60 |
| i4g.16xlarge | 14 | 120 |
| i4i.xlarge | 3 | 8 |
| i4i.2xlarge | 3 | 28 |
| i4i.4xlarge | 7 | 58 |
| i4i.8xlarge | 7 | 118 |
| i4i.12xlarge | 7 | 118 |
| i4i.16xlarge | 14 | 248 |
| i4i.24xlarge | 14 | 118 |
| i4i.32xlarge | 14 | 498 |
| i4i.metal | 14 | 498 |
| i7i.large | 2 | 10 |
| i7i.xlarge | 3 | 20 |
| i7i.2xlarge | 3 | 40 |
| i7i.4xlarge | 7 | 60 |
| i7i.8xlarge | 7 | 90 |
| i7i.12xlarge | 7 | 90 |
| i7i.16xlarge | 14 | 120 |
| i7i.24xlarge | 14 | 120 |
| i7i.48xlarge | 14 | 120 |
| i7i.metal-24xl | 14 | 120 |
| i7i.metal-48xl | 14 | 120 |
| i7ie.large | 2 | 20 |
| i7ie.xlarge | 3 | 29 |
| i7ie.2xlarge | 3 | 29 |
| i7ie.3xlarge | 3 | 29 |
| i7ie.6xlarge | 7 | 60 |
| i7ie.12xlarge | 7 | 60 |
| i7ie.18xlarge | 14 | 120 |
| i7ie.24xlarge | 14 | 120 |
| i7ie.48xlarge | 14 | 120 |
| i7ie.metal-24xl | 14 | 120 |
| i7ie.metal-48xl | 14 | 120 |
| i8g.large | 2 | 10 |
| i8g.xlarge | 3 | 20 |
| i8g.2xlarge | 3 | 40 |
| i8g.4xlarge | 7 | 60 |
| i8g.8xlarge | 7 | 60 |
| i8g.12xlarge | 7 | 60 |
| i8g.16xlarge | 14 | 120 |
| i8g.24xlarge | 14 | 120 |
| i8g.48xlarge | 14 | 120 |
| i8g.metal-24xl | 14 | 120 |
| i8g.metal-48xl | 14 | 120 |
| i8ge.large | 2 | 20 |
| i8ge.xlarge | 3 | 29 |
| i8ge.2xlarge | 3 | 29 |
| i8ge.3xlarge | 5 | 29 |
| i8ge.6xlarge | 9 | 60 |
| i8ge.12xlarge | 11 | 60 |
| i8ge.18xlarge | 15 | 120 |
| i8ge.24xlarge | 15 | 120 |
| i8ge.48xlarge | 23 | 120 |
| i8ge.metal-24xl | 15 | 120 |
| i8ge.metal-48xl | 23 | 120 |
| im4gn.large | 2 | 10 |
| im4gn.xlarge | 3 | 20 |
| im4gn.2xlarge | 3 | 40 |
| im4gn.4xlarge | 7 | 60 |
| im4gn.8xlarge | 7 | 60 |
| im4gn.16xlarge | 14 | 120 |
| is4gen.medium | 1 | 4 |
| is4gen.large | 2 | 10 |
| is4gen.xlarge | 3 | 20 |
| is4gen.2xlarge | 3 | 40 |
| is4gen.4xlarge | 7 | 60 |
| is4gen.8xlarge | 7 | 60 |
## Accelerated computing
| Instance type | Task limit without ENI trunking | Task limit with ENI trunking |
| --- | --- | --- |
| dl1.24xlarge | 59 | 120 |
| dl2q.24xlarge | 14 | 120 |
| f2.6xlarge | 7 | 90 |
| f2.12xlarge | 7 | 120 |
| f2.48xlarge | 14 | 120 |
| g4ad.xlarge | 1 | 12 |
| g4ad.2xlarge | 1 | 12 |
| g4ad.4xlarge | 2 | 12 |
| g4ad.8xlarge | 3 | 12 |
| g4ad.16xlarge | 7 | 12 |
| g5.xlarge | 3 | 6 |
| g5.2xlarge | 3 | 19 |
| g5.4xlarge | 7 | 40 |
| g5.8xlarge | 7 | 90 |
| g5.12xlarge | 14 | 120 |
| g5.16xlarge | 7 | 120 |
| g5.24xlarge | 14 | 120 |
| g5.48xlarge | 6 | 120 |
| g5g.xlarge | 3 | 20 |
| g5g.2xlarge | 3 | 40 |
| g5g.4xlarge | 7 | 60 |
| g5g.8xlarge | 7 | 60 |
| g5g.16xlarge | 14 | 120 |
| g5g.metal | 14 | 120 |
| g6.xlarge | 3 | 20 |
| g6.2xlarge | 3 | 40 |
| g6.4xlarge | 7 | 60 |
| g6.8xlarge | 7 | 90 |
| g6.12xlarge | 7 | 120 |
| g6.16xlarge | 14 | 120 |
| g6.24xlarge | 14 | 120 |
| g6.48xlarge | 14 | 120 |
| g6e.xlarge | 3 | 20 |
| g6e.2xlarge | 3 | 40 |
| g6e.4xlarge | 7 | 60 |
| g6e.8xlarge | 7 | 90 |
| g6e.12xlarge | 9 | 120 |
| g6e.16xlarge | 14 | 120 |
| g6e.24xlarge | 19 | 120 |
| g6e.48xlarge | 39 | 120 |
| g6f.large | 1 | 10 |
| g6f.xlarge | 3 | 20 |
| g6f.2xlarge | 3 | 40 |
| g6f.4xlarge | 7 | 60 |
| gr6.4xlarge | 7 | 60 |
| gr6.8xlarge | 7 | 90 |
| gr6f.4xlarge | 7 | 60 |
| g7e.2xlarge | 3 | 242 |
| g7e.4xlarge | 7 | 242 |
| g7e.8xlarge | 7 | 242 |
| g7e.12xlarge | 9 | 242 |
| g7e.24xlarge | 19 | 242 |
| g7e.48xlarge | 39 | 242 |
| inf2.xlarge | 3 | 20 |
| inf2.8xlarge | 7 | 90 |
| inf2.24xlarge | 14 | 120 |
| inf2.48xlarge | 14 | 120 |
| p4d.24xlarge | 59 | 120 |
| p4de.24xlarge | 59 | 120 |
| p5.4xlarge | 3 | 60 |
| p5.48xlarge | 63 | 242 |
| p5e.48xlarge | 63 | 242 |
| p5en.48xlarge | 63 | 242 |
| p6-b200.48xlarge | 31 | 242 |
| p6-b300.48xlarge | 67 | 242 |
| p6e-gb200.36xlarge | 38 | 120 |
| trn1.2xlarge | 3 | 19 |
| trn1.32xlarge | 39 | 120 |
| trn1n.32xlarge | 79 | 242 |
| trn2.3xlarge | 1 | 14 |
| trn2.48xlarge | 31 | 242 |
| trn2u.48xlarge | 31 | 242 |
| vt1.3xlarge | 3 | 40 |
| vt1.6xlarge | 7 | 60 |
| vt1.24xlarge | 14 | 120 |
## High performance computing
| Instance type | Task limit without ENI trunking | Task limit with ENI trunking |
| --- | --- | --- |
| hpc6a.48xlarge | 1 | 120 |
| hpc6id.32xlarge | 1 | 120 |
| hpc7g.4xlarge | 3 | 120 |
| hpc7g.8xlarge | 3 | 120 |
| hpc7g.16xlarge | 3 | 120 |
| hpc8a.96xlarge | 3 | -2 |
# Reserving Amazon ECS Linux container instance memory
When the Amazon ECS container agent registers a container instance to a cluster, the agent must determine how much memory the container instance has available to reserve for your tasks. Because of platform memory overhead and memory occupied by the system kernel, this number is different than the installed memory amount that is advertised for Amazon EC2 instances. For example, an `m4.large` instance has 8 GiB of installed memory. However, this does not always translate to exactly 8192 MiB of memory available for tasks when the container instance registers.
## ECS Managed Instances memory resource determination
Amazon ECS Managed Instances uses a hierarchical approach to determine memory resource requirements for tasks. Unlike ECS on EC2 which relies on Docker's memory introspection, ECS Managed Instances calculates memory requirements directly from the task payload during scheduling decisions.
When the ECS Managed Instances agent receives a task, it calculates the memory requirement using the following priority order:
1. **Task-level memory (highest priority)** - If task-level memory is specified in the task definition, the agent uses this value directly. This takes precedence over all container-level memory settings.
1. **Container-level memory sum (fallback)** - If task-level memory is not specified (or is 0), the agent sums the memory requirements from all containers in the task. For each container, it uses:
1. *Memory reservation (soft limit)* - If a container specifies `memoryReservation` in its configuration, the agent uses this value.
1. *Container memory (hard limit)* - If `memoryReservation` is not specified, the agent uses the container's `memory` field.
**Example Task-level memory specified**
When task-level memory is specified, it takes precedence over container-level settings:
```
{
"family": "my-task",
"memory": "2048",
"containerDefinitions": [
{
"name": "container1",
"memory": 1024,
"memoryReservation": 512
}
]
}
```
The agent reserves 2048 MiB (task-level memory takes precedence).
**Example Container-level memory with reservations**
When task-level memory is not specified, the agent sums container memory requirements:
```
{
"family": "my-task",
"containerDefinitions": [
{
"name": "container1",
"memory": 1024,
"memoryReservation": 512
},
{
"name": "container2",
"memory": 512
}
]
}
```
The agent reserves 512 MiB (container1 reservation) \$1 512 MiB (container2 memory) = 1024 MiB total.
The ECS Managed Instances agent performs memory calculation in three phases:
1. **Task reception** - When a task payload arrives from the ECS control plane, the agent immediately calculates the required memory.
1. **Resource storage** - The calculated memory requirement is stored in the task model for later use in resource accounting operations.
1. **Scheduling decision** - Before accepting a task, the agent checks if sufficient memory is available. If insufficient memory is available, the task is rejected and remains in the ECS service queue until resources become available.
**Note**
Unlike ECS on EC2, ECS Managed Instances does not use the `ECS_RESERVED_MEMORY` configuration variable. Memory reservation for system processes is handled through the underlying platform's resource management, and the agent performs accurate resource accounting based on task definitions.
For ECS on EC2, the Amazon ECS container agent provides a configuration variable called `ECS_RESERVED_MEMORY`, which you can use to remove a specified number of MiB of memory from the pool that is allocated to your tasks. This effectively reserves that memory for critical system processes.
If you occupy all of the memory on a container instance with your tasks, then it is possible that your tasks will contend with critical system processes for memory and possibly start a system failure.
For example, if you specify `ECS_RESERVED_MEMORY=256` in your container agent configuration file, then the agent registers the total memory minus 256 MiB for that instance, and 256 MiB of memory could not be allocated by ECS tasks. For more information about agent configuration variables and how to set them, see [Amazon ECS container agent configuration](ecs-agent-config.md) and [Bootstrapping Amazon ECS Linux container instances to pass data](bootstrap_container_instance.md).
If you specify 8192 MiB for the task, and none of your container instances have 8192 MiB or greater of memory available to satisfy this requirement, then the task cannot be placed in your cluster. If you are using a managed compute environment, then AWS Batch must launch a larger instance type to accommodate the request.
The Amazon ECS container agent uses the Docker `ReadMemInfo()` function to query the total memory available to the operating system. Both Linux and Windows provide command line utilities to determine the total memory.
**Example - Determine Linux total memory**
The **free** command returns the total memory that is recognized by the operating system.
```
$ free -b
```
Example output for an `m4.large` instance running the Amazon ECS-optimized Amazon Linux AMI.
```
total used free shared buffers cached
Mem: 8373026816 348180480 8024846336 90112 25534464 205418496
-/+ buffers/cache: 117227520 8255799296
```
This instance has 8373026816 bytes of total memory, which translates to 7985 MiB available for tasks.
**Example - Determine Windows total memory**
The **wmic** command returns the total memory that is recognized by the operating system.
```
C:\> wmic ComputerSystem get TotalPhysicalMemory
```
Example output for an `m4.large` instance running the Amazon ECS-optimized Windows Server AMI.
```
TotalPhysicalMemory
8589524992
```
This instance has 8589524992 bytes of total memory, which translates to 8191 MiB available for tasks.
## Viewing container instance memory
You can view how much memory a container instance registers with in the Amazon ECS console (or with the [DescribeContainerInstances](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeContainerInstances.html) API operation). If you are trying to maximize your resource utilization by providing your tasks as much memory as possible for a particular instance type, you can observe the memory available for that container instance and then assign your tasks that much memory.
**To view container instance memory**
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 the cluster that hosts your container instance.
1. Choose **Infrastructure**, and then under Container instances, choose a container instance.
1. The **Resources** section shows the registered and available memory for the container instance.
The **Registered** memory value is what the container instance; registered with Amazon ECS when it was first launched, and the **Available** memory value is what has not already been allocated to tasks.
# Managing Amazon ECS container instances remotely using AWS Systems Manager
You can use the Run Command capability in AWS Systems Manager (Systems Manager) to securely and remotely manage the configuration of your Amazon ECS container instances. Run Command provides a simple way to perform common administrative tasks without logging on locally to the instance. You can manage configuration changes across your clusters by simultaneously executing commands on multiple container instances. Run Command reports the status and results of each command.
Here are some examples of the types of tasks you can perform with Run Command:
+ Install or uninstall packages.
+ Perform security updates.
+ Clean up Docker images.
+ Stop or start services.
+ View system resources.
+ View log files.
+ Perform file operations.
For more information about Run Command, see [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
The following are prequisites to using Systems Manager with Amazon ECS.
1. You must grant the container instance role (**ecsInstanceRole**) permissions to access the Systems Manager APIs. You can do this by assigning the **AmazonSSMManagedInstanceCore** to the `ecsInstanceRole` role. For information about how to attach a policy to a role, see [Update permissions for a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-permissions.html) in the *AWS Identity and Access Management User Guide*
1. Verify that SSM Agent is installed on your container instances. For more information, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-linux.html).
After you attach Systems Manager managed policies to your `ecsInstanceRole` and verify that AWS Systems Manager Agent (SSM Agent) is installed on your container instances, you can start using Run Command to send commands to your container instances. For information about running commands and shell scripts on your instances and viewing the resulting output, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) and [Run Command Walkthroughs](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command-walkthroughs.html) in the *AWS Systems Manager User Guide*.
A common use case is to update container instance software with Run Command. You can follow the procedues in the AWS Systems Manager User Guide with the following parameters.
| Parameter | Value |
| --- | --- |
| **Command document** | AWS-RunShellScript |
| Command | $ yum update -y
|
| Target instances | Your container instances |
# Using an HTTP proxy for Amazon ECS Linux container instances
You can configure your Amazon ECS container instances to use an HTTP proxy for both the Amazon ECS container agent and the Docker daemon. This is useful if your container instances do not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
To configure your Amazon ECS Linux container instance to use an HTTP proxy, set the following variables in the relevant files at launch time (with Amazon EC2 user data). You can also manually edit the configuration file, and then restart the agent.
`/etc/ecs/ecs.config` (Amazon Linux 2 and AmazonLinux AMI)
`HTTP_PROXY=10.0.0.131:3128`
Set this value to the hostname (or IP address) and port number of an HTTP proxy to use for the Amazon ECS agent to connect to the internet. For example, your container instances may not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
`NO_PROXY=169.254.169.254,169.254.170.2,/var/run/docker.sock`
Set this value to `169.254.169.254,169.254.170.2,/var/run/docker.sock` to filter EC2 instance metadata, IAM roles for tasks, and Docker daemon traffic from the proxy.
`/etc/systemd/system/ecs.service.d/http-proxy.conf` (Amazon Linux 2 only)
`Environment="HTTP_PROXY=10.0.0.131:3128/"`
Set this value to the hostname (or IP address) and port number of an HTTP proxy to use for `ecs-init` to connect to the internet. For example, your container instances may not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
`Environment="NO_PROXY=169.254.169.254,169.254.170.2,/var/run/docker.sock"`
Set this value to `169.254.169.254,169.254.170.2,/var/run/docker.sock` to filter EC2 instance metadata, IAM roles for tasks, and Docker daemon traffic from the proxy.
`/etc/init/ecs.override` (Amazon Linux AMI only)
`env HTTP_PROXY=10.0.0.131:3128`
Set this value to the hostname (or IP address) and port number of an HTTP proxy to use for `ecs-init` to connect to the internet. For example, your container instances may not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
`env NO_PROXY=169.254.169.254,169.254.170.2,/var/run/docker.sock`
Set this value to `169.254.169.254,169.254.170.2,/var/run/docker.sock` to filter EC2 instance metadata, IAM roles for tasks, and Docker daemon traffic from the proxy.
`/etc/systemd/system/docker.service.d/http-proxy.conf` (Amazon Linux 2 only)
`Environment="HTTP_PROXY=http://10.0.0.131:3128"`
Set this value to the hostname (or IP address) and port number of an HTTP proxy to use for the Docker daemon to connect to the internet. For example, your container instances may not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
`Environment="NO_PROXY=169.254.169.254,169.254.170.2"`
Set this value to `169.254.169.254,169.254.170.2` to filter EC2 instance metadata from the proxy.
`/etc/sysconfig/docker` (Amazon Linux AMI and Amazon Linux 2 only)
`export HTTP_PROXY=http://10.0.0.131:3128`
Set this value to the hostname (or IP address) and port number of an HTTP proxy to use for the Docker daemon to connect to the internet. For example, your container instances may not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
`export NO_PROXY=169.254.169.254,169.254.170.2`
Set this value to `169.254.169.254,169.254.170.2` to filter EC2 instance metadata from the proxy.
Setting these environment variables in the above files only affects the Amazon ECS container agent, `ecs-init`, and the Docker daemon. They do not configure any other services (such as **yum**) to use the proxy.
For information about how to confiure thhe proxy, see [How do I set up an HTTP proxy for Docker and the Amazon ECS container agent in Amazon Linux 2 or AL2023](https://repost.aws/knowledge-center/ecs-http-proxy-docker-linux2).
# Configuring pre-initialized instances for your Amazon ECS Auto Scaling group
Amazon ECS supports Amazon EC2 Auto Scaling warm pools. A warm pool is a group of pre-initialized Amazon EC2 instances ready to be placed into service. Whenever your application needs to scale out, Amazon EC2 Auto Scaling uses the pre-initialized instances from the warm pool rather than launching cold instances, allows for any final initialization process to run, and then places the instance into service.
To learn more about warm pools and how to add a warm pool to your Auto Scaling group, see [Warm pools for Amazon EC2 Auto Scaling](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-warm-pools.html) *in the Amazon EC2 Auto Scaling User Guide*.
When you create or update a warm pool for an Auto Scaling group for Amazon ECS , you cannot set the option that returns instances to the warm pool on scale in (`ReuseOnScaleIn`). For more information, see [put-warm-pool](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/put-warm-pool.html) in the *AWS Command Line Interface Reference*.
To use warm pools with your Amazon ECS cluster, set the `ECS_WARM_POOLS_CHECK` agent configuration variable to `true` in the **User data** field of your Amazon EC2 Auto Scaling group launch template.
The following shows an example of how the agent configuration variable can be specified in the **User data** field of an Amazon EC2 launch template. Replace *MyCluster* with the name our your cluster.
```
#!/bin/bash
cat <<'EOF' >> /etc/ecs/ecs.config
ECS_CLUSTER=MyCluster
ECS_WARM_POOLS_CHECK=true
EOF
```
The `ECS_WARM_POOLS_CHECK` variable is only supported on agent versions `1.59.0` and later. For more information about the variable, see [Amazon ECS container agent configuration](ecs-agent-config.md).
# Updating the Amazon ECS container agent
Occasionally, you might need to update the Amazon ECS container agent to pick up bug fixes and new features. Updating the Amazon ECS container agent does not interrupt running tasks or services on the container instance. The process for updating the agent differs depending on whether your container instance was launched with an Amazon ECS-optimized AMI or another operating system.
**Note**
Agent updates do not apply to Windows container instances. We recommend that you launch new container instances to update the agent version in your Windows clusters.
## Checking the Amazon ECS container agent version
You can check the version of the container agent that is running on your container instances to see if you need to update it. The container instance view in the Amazon ECS console provides the agent version. Use the following procedure to check your agent version.
------
#### [ Amazon ECS console ]
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, choose the Region where your external instance is registered.
1. In the navigation pane, choose **Clusters** and select the cluster that hosts the external instance.
1. On the **Cluster : *name*** page, choose the **Infrastructure** tab.
1. Under **Container instances**, note the **Agent version** column for your container instances. If the container instance does not contain the latest version of the container agent, the console alerts you with a message and flags the outdated agent version.
If your agent version is outdated, you can update your container agent with the following procedures:
+ If your container instance is running an Amazon ECS-optimized AMI, see [Updating the Amazon ECS container agent on an Amazon ECS-optimized AMI](agent-update-ecs-ami.md).
+ If your container instance is not running an Amazon ECS-optimized AMI, see [Manually updating the Amazon ECS container agent (for non-Amazon ECS-Optimized AMIs)](manually_update_agent.md).
**Important**
To update the Amazon ECS agent version from versions before v1.0.0 on your Amazon ECS-optimized AMI, we recommend that you terminate your current container instance and launch a new instance with the most recent AMI version. Any container instances that use a preview version should be retired and replaced with the most recent AMI. For more information, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
------
#### [ Amazon ECS container agent introspection API ]
You can also use the to check the agent Amazon ECS container agent introspection API version from the container instance itself. For more information, see [Amazon ECS container introspection](ecs-agent-introspection.md).
**To check if your Amazon ECS container agent is running the latest version with the introspection API**
1. Log in to your container instance via SSH.
1. Query the introspection API.
```
[ec2-user ~]$ curl -s 127.0.0.1:51678/v1/metadata | python3 -mjson.tool
```
**Note**
The introspection API added `Version` information in the version v1.0.0 of the Amazon ECS container agent. If `Version` is not present when querying the introspection API, or the introspection API is not present in your agent at all, then the version you are running is v0.0.3 or earlier. You should update your version.
------
# Updating the Amazon ECS container agent on an Amazon ECS-optimized AMI
If you are using an Amazon ECS-optimized AMI, you have several options to get the latest version of the Amazon ECS container agent (shown in order of recommendation):
+ Terminate the container instance and launch the latest version of the Amazon ECS-optimized Amazon Linux 2 AMI (either manually or by updating your Auto Scaling launch configuration with the latest AMI). This provides a fresh container instance with the most current tested and validated versions of Amazon Linux, Docker, `ecs-init`, and the Amazon ECS container agent. For more information, see [Amazon ECS-optimized Linux AMIs](ecs-optimized_AMI.md).
+ Connect to the instance with SSH and update the `ecs-init` package (and its dependencies) to the latest version. This operation provides the most current tested and validated versions of Docker and `ecs-init` that are available in the Amazon Linux repositories and the latest version of the Amazon ECS container agent. For more information, see [To update the `ecs-init` package on an Amazon ECS-optimized AMI](#procedure_update_ecs-init).
+ Update the container agent with the `UpdateContainerAgent` API operation, either through the console or with the AWS CLI or AWS SDKs. For more information, see [Updating the Amazon ECS container agent with the `UpdateContainerAgent` API operation](#agent-update-api).
**Note**
Agent updates do not apply to Windows container instances. We recommend that you launch new container instances to update the agent version in your Windows clusters.
**To update the `ecs-init` package on an Amazon ECS-optimized AMI**
1. Log in to your container instance via SSH.
1. Update the `ecs-init` package with the following command.
```
sudo yum update -y ecs-init
```
**Note**
The `ecs-init` package and the Amazon ECS container agent are updated immediately. However, newer versions of Docker are not loaded until the Docker daemon is restarted. Restart either by rebooting the instance, or by running the following commands on your instance:
Amazon ECS-optimized Amazon Linux 2 AMI:
```
sudo systemctl restart docker
```
Amazon ECS-optimized Amazon Linux AMI:
```
sudo service docker restart && sudo start ecs
```
## Updating the Amazon ECS container agent with the `UpdateContainerAgent` API operation
**Important**
The `UpdateContainerAgent` API is only supported on Linux variants of the Amazon ECS-optimized AMI, with the exception of the Amazon ECS-optimized Amazon Linux 2 (arm64) AMI. For container instances using the Amazon ECS-optimized Amazon Linux 2 (arm64) AMI, update the `ecs-init` package to update the agent. For container instances that are running other operating systems, see [Manually updating the Amazon ECS container agent (for non-Amazon ECS-Optimized AMIs)](manually_update_agent.md). If you are using Windows container instances, we recommend that you launch new container instances to update the agent version in your Windows clusters.
The `UpdateContainerAgent` API process begins when you request an agent update, either through the console or with the AWS CLI or AWS SDKs. Amazon ECS checks your current agent version against the latest available agent version, and if an update is possible. If an update is not available, for example, if the agent is already running the most recent version, then a `NoUpdateAvailableException` is returned.
The stages in the update process shown above are as follows:
`PENDING`
An agent update is available, and the update process has started.
`STAGING`
The agent has begun downloading the agent update. If the agent cannot download the update, or if the contents of the update are incorrect or corrupted, then the agent sends a notification of the failure and the update transitions to the `FAILED` state.
`STAGED`
The agent download has completed and the agent contents have been verified.
`UPDATING`
The `ecs-init` service is restarted and it picks up the new agent version. If the agent is for some reason unable to restart, the update transitions to the `FAILED` state; otherwise, the agent signals Amazon ECS that the update is complete.
**Note**
Agent updates do not apply to Windows container instances. We recommend that you launch new container instances to update the agent version in your Windows clusters.
**To update the Amazon ECS container agent on an Amazon ECS-optimized AMI in the console**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, choose the Region where your external instance is registered.
1. In the navigation pane, choose **Clusters** and select the cluster.
1. On the **Cluster : *name*** page, choose the **Infrastructure** tab.
1. Under **Container instances**, select the instances to update, and then choose **Actions**, **Update agent**.
# Manually updating the Amazon ECS container agent (for non-Amazon ECS-Optimized AMIs)
Occasionally, you might need to update the Amazon ECS container agent to pick up bug fixes and new features. Updating the Amazon ECS container agent does not interrupt running tasks or services on the container instance.
**Note**
Agent updates do not apply to Windows container instances. We recommend that you launch new container instances to update the agent version in your Windows clusters.
1. Log in to your container instance via SSH.
1. Check to see if your agent uses the `ECS_DATADIR` environment variable to save its state.
```
ubuntu:~$ docker inspect ecs-agent | grep ECS_DATADIR
```
Output:
```
"ECS_DATADIR=/data",
```
**Important**
If the previous command does not return the `ECS_DATADIR` environment variable, you must stop any tasks running on this container instance before updating your agent. Newer agents with the `ECS_DATADIR` environment variable save their state and you can update them while tasks are running without issues.
1. Stop the Amazon ECS container agent.
```
ubuntu:~$ docker stop ecs-agent
```
1. Delete the agent container.
```
ubuntu:~$ docker rm ecs-agent
```
1. Ensure that the `/etc/ecs` directory and the Amazon ECS container agent configuration file exist at `/etc/ecs/ecs.config`.
```
ubuntu:~$ sudo mkdir -p /etc/ecs && sudo touch /etc/ecs/ecs.config
```
1. Edit the `/etc/ecs/ecs.config` file and ensure that it contains at least the following variable declarations. If you do not want your container instance to register with the default cluster, specify your cluster name as the value for `ECS_CLUSTER`.
```
ECS_DATADIR=/data
ECS_ENABLE_TASK_IAM_ROLE=true
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true
ECS_LOGFILE=/log/ecs-agent.log
ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"]
ECS_LOGLEVEL=info
ECS_CLUSTER=default
```
For more information about these and other agent runtime options, see [Amazon ECS container agent configuration](ecs-agent-config.md).
**Note**
You can optionally store your agent environment variables in Amazon S3 (which can be downloaded to your container instances at launch time using Amazon EC2 user data). This is recommended for sensitive information such as authentication credentials for private repositories. For more information, see [Storing Amazon ECS container instance configuration in Amazon S3](ecs-config-s3.md) and [Using non-AWS container images in Amazon ECS](private-auth.md).
1. Pull the latest Amazon ECS container agent image from Amazon Elastic Container Registry Public.
```
ubuntu:~$ docker pull public.ecr.aws/ecs/amazon-ecs-agent:latest
```
Output:
```
Pulling repository amazon/amazon-ecs-agent
a5a56a5e13dc: Download complete
511136ea3c5a: Download complete
9950b5d678a1: Download complete
c48ddcf21b63: Download complete
Status: Image is up to date for amazon/amazon-ecs-agent:latest
```
1. Run the latest Amazon ECS container agent on your container instance.
**Note**
Use Docker restart policies or a process manager (such as **upstart** or **systemd**) to treat the container agent as a service or a daemon and ensure that it is restarted after exiting. The Amazon ECS-optimized AMI uses the `ecs-init` RPM for this purpose, and you can view the [source code for this RPM](https://github.com/aws/amazon-ecs-init) on GitHub.
The following example of the agent run command is broken into separate lines to show each option. For more information about these and other agent runtime options, see [Amazon ECS container agent configuration](ecs-agent-config.md).
**Important**
Operating systems with SELinux enabled require the `--privileged` option in your **docker run** command. In addition, for SELinux-enabled container instances, we recommend that you add the `:Z` option to the `/log` and `/data` volume mounts. However, the host mounts for these volumes must exist before you run the command or you receive a `no such file or directory` error. Take the following action if you experience difficulty running the Amazon ECS agent on an SELinux-enabled container instance:
Create the host volume mount points on your container instance.
```
ubuntu:~$ sudo mkdir -p /var/log/ecs /var/lib/ecs/data
```
Add the `--privileged` option to the **docker run** command below.
Append the `:Z` option to the `/log` and `/data` container volume mounts (for example, `--volume=/var/log/ecs/:/log:Z`) to the **docker run** command below.
```
ubuntu:~$ sudo docker run --name ecs-agent \
--detach=true \
--restart=on-failure:10 \
--volume=/var/run:/var/run \
--volume=/var/log/ecs/:/log \
--volume=/var/lib/ecs/data:/data \
--volume=/etc/ecs:/etc/ecs \
--volume=/etc/ecs:/etc/ecs/pki \
--net=host \
--env-file=/etc/ecs/ecs.config \
amazon/amazon-ecs-agent:latest
```
**Note**
If you receive an `Error response from daemon: Cannot start container` message, you can delete the failed container with the **sudo docker rm ecs-agent** command and try running the agent again.
# Amazon ECS-optimized Windows AMIs
The Amazon ECS-optimized AMIs are preconfigured with the necessary components that you need to run Amazon ECS workloads. Although you can create your own container instance AMI that meets the basic specifications needed to run your containerized workloads on Amazon ECS, the Amazon ECS-optimized AMIs are preconfigured and tested on Amazon ECS by AWS engineers. It is the simplest way for you to get started and to get your containers running on AWS quickly.
The Amazon ECS-optimized AMI metadata, including the AMI name, Amazon ECS container agent version, and Amazon ECS runtime version which includes the Docker version, for each variant can be retrieved programmatically. For more information, see [Retrieving Amazon ECS-optimized Windows AMI metadata](retrieve-ecs-optimized_windows_AMI.md).
**Important**
All ECS-optimized AMI variants produced after August 2022 will be migrating from Docker EE (Mirantis) to Docker CE (Moby project).
To ensure that customers have the latest security updates by default, Amazon ECS maintains at least the last three Windows Amazon ECS-optimized AMIs. After releasing new Windows Amazon ECS-optimized AMIs, Amazon ECS makes the Windows Amazon ECS-optimized AMIs that are older private. If there is a private AMI that you need access to, let us know by filing a ticket with Cloud Support.
## Amazon ECS-optimized AMI variants
The following Windows Server variants of the Amazon ECS-optimized AMI are available for your Amazon EC2 instances.
**Important**
All ECS-optimized AMI variants produced after August will be migrating from Docker EE (Mirantis) to Docker CE (Moby project).
+ **Amazon ECS-optimized Windows Server 2025 Full AMI**
+ **Amazon ECS-optimized Windows Server 2025 Core AMI**
+ **Amazon ECS-optimized Windows Server 2022 Full AMI**
+ **Amazon ECS-optimized Windows Server 2022 Core AMI**
+ **Amazon ECS-optimized Windows Server 2019 Full AMI**
+ **Amazon ECS-optimized Windows Server 2019 Core AMI**
+ **Amazon ECS-optimized Windows Server 2016 Full AMI**
**Important**
Windows Server 2016 does not support the latest Docker version, for example 25.x.x. Therefore the Windows Server 2016 Full AMIs will not receive security or bug patches to the Docker runtime. We recommend that you move to one of the following Windows platforms:
Windows Server 2022 Full
Windows Server 2022 Core
Windows Server 2019 Full
Windows Server 2019 Core
On August 9, 2022, the Amazon ECS-optimized Windows Server 20H2 Core AMI reached its end of support date. No new versions of this AMI will be released. For more information, see [Windows Server release information](https://learn.microsoft.com/en-us/windows-server/get-started/windows-server-release-info).
Windows Server 2025, Windows Server 2022, Windows Server 2019, and Windows Server 2016 are Long-Term Servicing Channel (LTSC) releases. Windows Server 20H2 is a Semi-Annual Channel (SAC) release. For more information, see [Windows Server release information](https://learn.microsoft.com/en-us/windows-server/get-started/windows-server-release-info).
### Considerations
Here are some things you should know about Amazon EC2 Windows containers and Amazon ECS.
+ Windows containers can't run on Linux container instances, and the opposite is also the case. For better task placement for Windows and Linux tasks, keep Windows and Linux container instances in separate clusters and only place Windows tasks on Windows clusters. You can ensure that Windows task definitions are only placed on Windows instances by setting the following placement constraint: `memberOf(ecs.os-type=='windows')`.
+ Windows containers are supported for tasks that use the EC2 and Fargate.
+ Windows containers and container instances can't support all the task definition parameters that are available for Linux containers and container instances. For some parameters, they aren't supported at all, and others behave differently on Windows than they do on Linux. For more information, see [Amazon ECS task definition differences for EC2 instances running Windows](windows_task_definitions.md).
+ For the IAM roles for tasks feature, you need to configure your Windows container instances to allow the feature at launch. Your containers must run some provided PowerShell code when they use the feature. For more information, see [Amazon EC2 Windows instance additional configuration](task-iam-roles.md#windows_task_IAM_roles).
+ The IAM roles for tasks feature uses a credential proxy to provide credentials to the containers. This credential proxy occupies port 80 on the container instance, so if you use IAM roles for tasks, port 80 is not available for tasks. For web service containers, you can use an Application Load Balancer and dynamic port mapping to provide standard HTTP port 80 connections to your containers. For more information, see [Use load balancing to distribute Amazon ECS service traffic](service-load-balancing.md).
+ The Windows Server Docker images are large (9 GiB). So, your Windows container instances require more storage space than Linux container instances.
+ To run a Windows container on a Windows Server, the container’s base image OS version must match that of the host. For more information, see [Windows container version compatibility](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-2022%2Cwindows-11) on the Microsoft documentation website. If your cluster runs multiple Windows versions, you can ensure that a task is placed on an EC2 instance running on the same version by using the placement constraint: `memberOf(attribute:ecs.os-family == WINDOWS_SERVER__)`. For more information, see [Retrieving Amazon ECS-optimized Windows AMI metadata](retrieve-ecs-optimized_windows_AMI.md).
# Retrieving Amazon ECS-optimized Windows AMI metadata
The AMI ID, image name, operating system, container agent version, and runtime version for each variant of the Amazon ECS-optimized AMIs can be programmatically retrieved by querying the Systems Manager Parameter Store API. For more information about the Systems Manager Parameter Store API, see [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html) and [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html).
**Note**
Your administrative user must have the following IAM permissions to retrieve the Amazon ECS-optimized AMI metadata. These permissions have been added to the `AmazonECS_FullAccess` IAM policy.
ssm:GetParameters
ssm:GetParameter
ssm:GetParametersByPath
## Systems Manager Parameter Store parameter format
**Note**
The following Systems Manager Parameter Store API parameters are deprecated and should not be used to retrieve the latest Windows AMIs:
`/aws/service/ecs/optimized-ami/windows_server/2016/english/full/recommended/image_id `
`/aws/service/ecs/optimized-ami/windows_server/2019/english/full/recommended/image_id`
The following is the format of the parameter name for each Amazon ECS-optimized AMI variant.
+ Windows Server 2025 Full AMI metadata:
```
/aws/service/ami-windows-latest/Windows_Server-2025-English-Full-ECS_Optimized
```
+ Windows Server 2025 Core AMI metadata:
```
/aws/service/ami-windows-latest/Windows_Server-2025-English-Core-ECS_Optimized
```
+ Windows Server 2022 Full AMI metadata:
```
/aws/service/ami-windows-latest/Windows_Server-2022-English-Full-ECS_Optimized
```
+ Windows Server 2022 Core AMI metadata:
```
/aws/service/ami-windows-latest/Windows_Server-2022-English-Core-ECS_Optimized
```
+ Windows Server 2019 Full AMI metadata:
```
/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized
```
+ Windows Server 2019 Core AMI metadata:
```
/aws/service/ami-windows-latest/Windows_Server-2019-English-Core-ECS_Optimized
```
+ Windows Server 2016 Full AMI metadata:
```
/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-ECS_Optimized
```
The following parameter name format retrieves the metadata of the latest stable Windows Server 2019 Full AMI
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized
```
The following is an example of the JSON object that is returned for the parameter value.
```
{
"Parameters": [
{
"Name": "/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized",
"Type": "String",
"Value": "{\"image_name\":\"Windows_Server-2019-English-Full-ECS_Optimized-2023.06.13\",\"image_id\":\"ami-0debc1fb48e4aee16\",\"ecs_runtime_version\":\"Docker (CE) version 20.10.21\",\"ecs_agent_version\":\"1.72.0\"}",
"Version": 58,
"LastModifiedDate": "2023-06-22T19:37:37.841000-04:00",
"ARN": "arn:aws:ssm:us-east-1::parameter/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized",
"DataType": "text"
}
],
"InvalidParameters": []
}
```
Each of the fields in the output above are available to be queried as sub-parameters. Construct the parameter path for a sub-parameter by appending the sub-parameter name to the path for the selected AMI. The following sub-parameters are available:
+ `schema_version`
+ `image_id`
+ `image_name`
+ `os`
+ `ecs_agent_version`
+ `ecs_runtime_version`
## Examples
The following examples show ways in which you can retrieve the metadata for each Amazon ECS-optimized AMI variant.
### Retrieving the metadata of the latest stable Amazon ECS-optimized AMI
You can retrieve the latest stable Amazon ECS-optimized AMI using the AWS CLI with the following AWS CLI commands.
+ **For the Amazon ECS-optimized Windows Server 2025 Full AMI:**
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2025-English-Full-ECS_Optimized --region us-east-1
```
+ **For the Amazon ECS-optimized Windows Server 2025 Core AMI:**
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2025-English-Core-ECS_Optimized --region us-east-1
```
+ **For the Amazon ECS-optimized Windows Server 2022 Full AMI:**
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2022-English-Full-ECS_Optimized --region us-east-1
```
+ **For the Amazon ECS-optimized Windows Server 2022 Core AMI:**
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2022-English-Core-ECS_Optimized --region us-east-1
```
+ **For the Amazon ECS-optimized Windows Server 2019 Full AMI:**
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized --region us-east-1
```
+ **For the Amazon ECS-optimized Windows Server 2019 Core AMI:**
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Core-ECS_Optimized --region us-east-1
```
+ **For the Amazon ECS-optimized Windows Server 2016 Full AMI:**
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2016-English-Full-ECS_Optimized --region us-east-1
```
### Using the latest recommended Amazon ECS-optimized AMI in an CloudFormation template
You can reference the latest recommended Amazon ECS-optimized AMI in an CloudFormation template by referencing the Systems Manager parameter store name.
```
Parameters:
LatestECSOptimizedAMI:
Description: AMI ID
Type: AWS::SSM::Parameter::Value
Default: /aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized/image_id
```
# Amazon ECS-optimized Windows AMI versions
View the current and previous versions of the Amazon ECS-optimized AMIs and their corresponding versions of the Amazon ECS container agent, Docker, and the `ecs-init` package.
The Amazon ECS-optimized AMI metadata, including the AMI ID, for each variant can be retrieved programmatically. For more information, see [Retrieving Amazon ECS-optimized Windows AMI metadata](retrieve-ecs-optimized_windows_AMI.md).
The following tabs display a list of Windows Amazon ECS-optimized AMIs versions. For details on referencing the Systems Manager Parameter Store parameter in an CloudFormation template, see [Using the latest recommended Amazon ECS-optimized AMI in an CloudFormation template](retrieve-ecs-optimized_AMI.md#ecs-optimized-ami-parameter-examples-5).
**Important**
To ensure that customers have the latest security updates by default, Amazon ECS maintains at least the last three Windows Amazon ECS-optimized AMIs. After releasing new Windows Amazon ECS-optimized AMIs, Amazon ECS makes the Windows Amazon ECS-optimized AMIs that are older private. If there is a private AMI that you need access to, let us know by filing a ticket with Cloud Support.
Windows Server 2016 does not support the latest Docker version, for example 25.x.x. Therefore the Windows Server 2016 Full AMIs will not receive security or bug patches to the Docker runtime. We recommend that you move to one of the following Windows platforms:
Windows Server 2022 Full
Windows Server 2022 Core
Windows Server 2019 Full
Windows Server 2019 Core
**Note**
gMSA plugin logging has been migrated from file-based logging `(C:\ProgramData\Amazon\gmsa)` to Windows Event logging with the August 2025 AMI release. The public log collector script will collect all gMSA logs. For more information, see [Collecting container logs with Amazon ECS logs collector](ecs-logs-collector.md).
------
#### [ Windows Server 2025 Full AMI versions ]
The table below lists the current and previous versions of the Amazon ECS-optimized Windows Server 2025 Full AMI and their corresponding versions of the Amazon ECS container agent and Docker.
| Amazon ECS-optimized Windows Server 2025 Full AMI | Amazon ECS container agent version | Docker version | Visibility |
| --- | --- | --- | --- |
| **Windows\$1Server-2025-English-Full-ECS\$1Optimized-2026.03.13** | `1.102.0` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2025-English-Full-ECS\$1Optimized-2026.02.13** | `1.101.3` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2025-English-Full-ECS\$1Optimized-2026.01.16** | `1.101.2` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2025-English-Full-ECS\$1Optimized-2025.12.13** | `1.101.0` | `25.0.6 (Docker CE)` | Public |
Use the following AWS CLI command to retrieve the current Amazon ECS-optimized Windows Server 2025 Full AMI.
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2025-English-Full-ECS_Optimized
```
------
#### [ Windows Server 2025 Core AMI versions ]
The table below lists the current and previous versions of the Amazon ECS-optimized Windows Server 2025 Core AMI and their corresponding versions of the Amazon ECS container agent and Docker.
| Amazon ECS-optimized Windows Server 2025 Core AMI | Amazon ECS container agent version | Docker version | Visibility |
| --- | --- | --- | --- |
| **Windows\$1Server-2025-English-Core-ECS\$1Optimized-2026.03.13** | `1.102.0` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2025-English-Core-ECS\$1Optimized-2026.02.13** | `1.101.3` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2025-English-Core-ECS\$1Optimized-2026.01.16** | `1.101.2` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2025-English-Core-ECS\$1Optimized-2025.12.13** | `1.101.0` | `25.0.6 (Docker CE)` | Public |
Use the following AWS CLI command to retrieve the current Amazon ECS-optimized Windows Server 2025 Core AMI.
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2025-English-Core-ECS_Optimized
```
------
#### [ Windows Server 2022 Full AMI versions ]
The table below lists the current and previous versions of the Amazon ECS-optimized Windows Server 2022 Full AMI and their corresponding versions of the Amazon ECS container agent and Docker.
| Amazon ECS-optimized Windows Server 2022 Full AMI | Amazon ECS container agent version | Docker version | Visibility |
| --- | --- | --- | --- |
| **Windows\$1Server-2022-English-Full-ECS\$1Optimized-2026.03.13** | `1.102.0` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2022-English-Full-ECS\$1Optimized-2026.02.13** | `1.101.3` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2022-English-Full-ECS\$1Optimized-2026.01.16** | `1.101.2` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2022-English-Full-ECS\$1Optimized-2025.12.13** | `1.101.0` | `25.0.6 (Docker CE)` | Public |
Use the following AWS CLI command to retrieve the current Amazon ECS-optimized Windows Server 2022 Full AMI.
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2022-English-Full-ECS_Optimized
```
------
#### [ Windows Server 2022 Core AMI versions ]
The table below lists the current and previous versions of the Amazon ECS-optimized Windows Server 2022 Core AMI and their corresponding versions of the Amazon ECS container agent and Docker.
| Amazon ECS-optimized Windows Server 2022 Core AMI | Amazon ECS container agent version | Docker version | Visibility |
| --- | --- | --- | --- |
| **Windows\$1Server-2022-English-Core-ECS\$1Optimized-2026.03.13** | `1.102.0` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2022-English-Core-ECS\$1Optimized-2026.02.13** | `1.101.3` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2022-English-Core-ECS\$1Optimized-2026.01.16** | `1.101.2` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2022-English-Core-ECS\$1Optimized-2025.12.13** | `1.101.0` | `25.0.6 (Docker CE)` | Public |
Use the following AWS CLI command to retrieve the current Amazon ECS-optimized Windows Server 2022 Full AMI.
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2022-English-Core-ECS_Optimized
```
------
#### [ Windows Server 2019 Full AMI versions ]
The table below lists the current and previous versions of the Amazon ECS-optimized Windows Server 2019 Full AMI and their corresponding versions of the Amazon ECS container agent and Docker.
| Amazon ECS-optimized Windows Server 2019 Full AMI | Amazon ECS container agent version | Docker version | Visibility |
| --- | --- | --- | --- |
| **Windows\$1Server-2019-English-Full-ECS\$1Optimized-2026.03.13** | `1.102.0` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2019-English-Full-ECS\$1Optimized-2026.02.13** | `1.101.3` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2019-English-Full-ECS\$1Optimized-2026.01.16** | `1.101.2` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2019-English-Full-ECS\$1Optimized-2025.12.13** | `1.101.0` | `25.0.6 (Docker CE)` | Public |
Use the following AWS CLI command to retrieve the current Amazon ECS-optimized Windows Server 2019 Full AMI.
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized
```
------
#### [ Windows Server 2019 Core AMI versions ]
The table below lists the current and previous versions of the Amazon ECS-optimized Windows Server 2019 Core AMI and their corresponding versions of the Amazon ECS container agent and Docker.
| Amazon ECS-optimized Windows Server 2019 Core AMI | Amazon ECS container agent version | Docker version | Visibility |
| --- | --- | --- | --- |
| **Windows\$1Server-2019-English-Core-ECS\$1Optimized-2026.03.13** | `1.102.0` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2019-English-Core-ECS\$1Optimized-2026.02.13** | `1.101.3` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2019-English-Core-ECS\$1Optimized-2026.01.16** | `1.101.2` | `25.0.6 (Docker CE)` | Public |
| **Windows\$1Server-2019-English-Core-ECS\$1Optimized-2025.12.13** | `1.101.0` | `25.0.6 (Docker CE)` | Public |
Use the following AWS CLI command to retrieve the current Amazon ECS-optimized Windows Server 2019 Full AMI.
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Core-ECS_Optimized
```
------
#### [ Windows Server 2016 Full AMI versions ]
**Important**
Windows Server 2016 does not support the latest Docker version, for example 25.x.x. Therefore the Windows Server 2016 Full AMIs will not receive security or bug patches to the Docker runtime. We recommend that you move to one of the following Windows platforms:
Windows Server 2022 Full
Windows Server 2022 Core
Windows Server 2019 Full
Windows Server 2019 Core
The table below lists the current and previous versions of the Amazon ECS-optimized Windows Server 2016 Full AMI and their corresponding versions of the Amazon ECS container agent and Docker.
| Amazon ECS-optimized Windows Server 2016 Full AMI | Amazon ECS container agent version | Docker version | Visibility |
| --- | --- | --- | --- |
| **Windows\$1Server-2016-English-Full-ECS\$1Optimized-2026.03.13** | `1.102.0` | `20.10.23 (Docker CE)` | Public |
| **Windows\$1Server-2016-English-Full-ECS\$1Optimized-2026.02.13** | `1.101.3` | `20.10.23 (Docker CE)` | Public |
| **Windows\$1Server-2016-English-Full-ECS\$1Optimized-2026.01.16** | `1.101.2` | `20.10.23 (Docker CE)` | Public |
| **Windows\$1Server-2016-English-Full-ECS\$1Optimized-2025.12.13** | `1.101.0` | `20.10.23 (Docker CE)` | Public |
Use the following AWS CLI Amazon ECS-optimized Windows Server 2016 Full AMI.
```
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2016-English-Full-ECS_Optimized
```
------
# Building your own Amazon ECS-optimized Windows AMI
Use EC2 Image Builder to build your own custom Amazon ECS-optimized Windows AMI. This makes it easy to use a Windows AMI with your own license on Amazon ECS. Amazon ECS provides a managed Image Builder component which provides the system configuration needed to run Windows instances to host your containers. Each Amazon ECS managed component includes a specific container agent and Docker version. You can customize your image to use either the latest Amazon ECS managed component, or if an older container agent or Docker version is needed you can specify a different component.
For a full walkthrough of using EC2 Image Builder, see [Getting started with EC2 Image Builder](https://docs.aws.amazon.com/imagebuilder/latest/userguide/set-up-ib-env.html#image-builder-accessing-prereq) in the *EC2 Image Builder User Guide*.
When building your own Amazon ECS-optimized Windows AMI using EC2 Image Builder, you create an image recipe. Your image recipe must meet the following requirements:
+ The **Source image** should be based on Windows Server 2019 Core, Windows Server 2019 Full, Windows Server 2022 Core, or Windows Server 2022 Full. Any other Windows operating system is not supported and may not be compatible with the component.
+ When specifying the **Build components**, the `ecs-optimized-ami-windows` component is required. The `update-windows` component is recommended, which ensures the image contains the latest security updates.
To specify a different component version, expand the **Versioning options** menu and specify the component version you want to use. For more information, see [Listing the `ecs-optimized-ami-windows` component versions](#windows-component-list).
## Listing the `ecs-optimized-ami-windows` component versions
When creating an EC2 Image Builder recipe and specifying the `ecs-optimized-ami-windows` component, you can either use the default option or you can specify a specific component version. To determine what component versions are available, along with the Amazon ECS container agent and Docker versions contained within the component, you can use the AWS Management Console.
**To list the available `ecs-optimized-ami-windows` component versions**
1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/).
1. On the navigation bar, select the Region that are building your image in.
1. In the navigation pane, under the **Saved configurations** menu, choose **Components**.
1. On the **Components** page, in the search bar type `ecs-optimized-ami-windows` and pull down the qualification menu and select **Quick start (Amazon-managed)**.
1. Use the **Description** column to determine the component version with the Amazon ECS container agent and Docker version your image requires.
# Amazon ECS Windows container instance management
When you use EC2 instances for your Amazon ECS workloads, you are responsible for maintaining the instances.
Agent updates do not apply to Windows container instances. We recommend that you launch new container instances to update the agent version in your Windows clusters.
**Topics**
+ [Launching a container instance](launch_window-container_instance.md)
+ [Bootstrapping container instances](bootstrap_windows_container_instance.md)
+ [Using an HTTP proxy for Windows container instances](http_proxy_config-windows.md)
+ [Configuring container instances to receive Spot Instance notices](windows-spot-instance-draining-container.md)
# Launching an Amazon ECS Windows container instance
Your Amazon ECS container instances are created using the Amazon EC2 console. Before you begin, be sure that you've completed the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md).
For more information about the launch wizard, see [Launch an instance using the new launch instance wizard](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2-launch-instance-wizard.html) in the *Amazon EC2 User Guide*.
You can use the new Amazon EC2 wizard to launch an instance. You can use the following list for the parameters and leave the parameters not listed as the default. The following instructions take you through each parameter group.
## Procedure
Before you begin, complete the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md).
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation bar at the top of the screen, the current AWS Region is displayed (for example, US East (Ohio)). Select a Region in which to launch the instance. This choice is important because some Amazon EC2 resources can be shared between Regions, while others can't.
1. From the Amazon EC2 console dashboard, choose **Launch instance**.
## Name and tags
The instance name is a tag, where the key is **Name**, and the value is the name that you specify. You can tag the instance, the volumes, and elastic graphics. For Spot Instances, you can tag the Spot Instance request only.
Specifying an instance name and additional tags is optional.
+ For **Name**, enter a descriptive name for the instance. If you don't specify a name, the instance can be identified by its ID, which is automatically generated when you launch the instance.
+ To add additional tags, choose **Add additional tags**. Choose **Add tag**, and then enter a key and value, and select the resource type to tag. Choose **Add tag** again for each additional tag to add.
## Application and OS Images (Amazon Machine Image)
An Amazon Machine Image (AMI) contains the information required to create an instance. For example, an AMI might contain the software that's required to act as a web server, such as Apache, and your website.
For the latest Amazon ECS-optimized AMIs and their values, see [Windows Amazon ECS-optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_windows_AMI.html).
Use the **Search** bar to find a suitable Amazon ECS-optimized AMI published by AWS.
1. Based on your requirements, enter one of the following AMIs in the **Search** bar and press **Enter**.
+ Windows\$1Server-2022-English-Full-ECS\$1Optimized
+ Windows\$1Server-2022-English-Core-ECS\$1Optimized
+ Windows\$1Server-2019-English-Full-ECS\$1Optimized
+ Windows\$1Server-2019-English-Core-ECS\$1Optimized
+ Windows\$1Server-2016-English-Full-ECS\$1Optimized
1. On the **Choose an Amazon Machine Image (AMI)** page, select the **Community AMIs** tab.
1. From the list that appears, choose a Microsoft-verified AMI with the most recent publish date and click **Select**.
## Instance type
The instance type defines the hardware configuration and size of the instance. Larger instance types have more CPU and memory. For more information, see [Instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html).
+ For **Instance type**, select the instance type for the instance.
The instance type that you select determines the resources available for your tasks to run on.
## Key pair (login)
For **Key pair name**, choose an existing key pair, or choose **Create new key pair** to create a new one.
**Important**
If you choose the **Proceed without key pair (Not recommended)** option, you won't be able to connect to the instance unless you choose an AMI that is configured to allow users another way to log in.
## Network settings
Configure the network settings, as necessary.
+ **Networking platform**: Choose **Virtual Private Cloud (VPC)**, and then specify the subnet in the **Network interfaces** section.
+ **VPC**: Select an existing VPC in which to create the security group.
+ **Subnet**: You can launch an instance in a subnet associated with an Availability Zone, Local Zone, Wavelength Zone, or Outpost.
To launch the instance in an Availability Zone, select the subnet in which to launch your instance. To create a new subnet, choose **Create new subnet** to go to the Amazon VPC console. When you are done, return to the launch instance wizard and choose the Refresh icon to load your subnet in the list.
To launch the instance in a Local Zone, select a subnet that you created in the Local Zone.
To launch an instance in an Outpost, select a subnet in a VPC that you associated with the Outpost.
+ **Auto-assign Public IP**: If your instance should be accessible from the internet, verify that the **Auto-assign Public IP** field is set to **Enable**. If not, set this field to **Disable**.
**Note**
Container instances need access to communicate with the Amazon ECS service endpoint. This can be through an interface VPC endpoint or through your container instances having public IP addresses.
For more information about interface VPC endpoints, see [Amazon ECS interface VPC endpoints (AWS PrivateLink)](vpc-endpoints.md)
If you do not have an interface VPC endpoint configured and your container instances do not have public IP addresses, then they must use network address translation (NAT) to provide this access. For more information, see [NAT gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) in the *Amazon VPC User Guide* and [Using an HTTP proxy for Amazon ECS Linux container instances](http_proxy_config.md) in this guide.
+ **Firewall (security groups)**: Use a security group to define firewall rules for your container instance. These rules specify which incoming network traffic is delivered to your container instance. All other traffic is ignored.
+ To select an existing security group, choose **Select existing security group**, and select the security group that you created in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md)
## Configure storage
The AMI you selected includes one or more volumes of storage, including the root volume. You can specify additional volumes to attach to the instance.
You can use the **Simple** view.
+ **Storage type**: Configure the storage for your container instance.
If you are using the Amazon ECS-optimized Amazon Linux AMI, your instance has two volumes configured. The **Root** volume is for the operating system's use, and the second Amazon EBS volume (attached to `/dev/xvdcz`) is for Docker's use.
You can optionally increase or decrease the volume sizes for your instance to meet your application needs.
## Advanced details
For **Advanced details**, expand the section to view the fields and specify any additional parameters for the instance.
+ **Purchasing option**: Choose **Request Spot Instances** to request Spot Instances. You also need to set the other fields related to Spot Instances. For more information, see [Spot Instance Requests](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-requests.html).
**Note**
If you are using Spot Instances and see a `Not available` message, you may need to choose a different instance type.
.
+ **IAM instance profile**: Select your container instance IAM role. This is usually named `ecsInstanceRole`.
**Important**
If you do not launch your container instance with the proper IAM permissions, your Amazon ECS agent cannot connect to your cluster. For more information, see [Amazon ECS container instance IAM role](instance_IAM_role.md).
+ (Optional) **User data**: Configure your Amazon ECS container instance with user data, such as the agent environment variables from [Amazon ECS container agent configuration](ecs-agent-config.md). Amazon EC2 user data scripts are executed only one time, when the instance is first launched. The following are common examples of what user data is used for:
+ By default, your container instance launches into your default cluster. To launch into a non-default cluster, choose the **Advanced Details** list. Then, paste the following script into the **User data** field, replacing *your\$1cluster\$1name* with the name of your cluster.
The `EnableTaskIAMRole` turns on the Task IAM roles feature for the tasks.
In addition, the following options are available when you use the `awsvpc` network mode.
+ `EnableTaskENI`: This flag turns on task networking and is required when you use the `awsvpc` network mode.
+ `AwsvpcBlockIMDS`: This optional flag blocks IMDS access for the task containers running in the `awsvpc` network mode.
+ `AwsvpcAdditionalLocalRoutes`: This optional flag allows you to have additional routes in the task namespace.
Replace `ip-address` with the IP Address for the additional routes, for example 172.31.42.23/32.
```
Import-Module ECSTools
Initialize-ECSAgent -Cluster your_cluster_name -EnableTaskIAMRole -EnableTaskENI -AwsvpcBlockIMDS -AwsvpcAdditionalLocalRoutes
'["ip-address"]'
```
# Bootstrapping Amazon ECS Windows container instances to pass data
When you launch an Amazon EC2 instance, you can pass user data to the EC2 instance. The data can be used to perform common automated configuration tasks and even run scripts when the instance boots. For Amazon ECS, the most common use cases for user data are to pass configuration information to the Docker daemon and the Amazon ECS container agent.
You can pass multiple types of user data to Amazon EC2, including cloud boothooks, shell scripts, and `cloud-init` directives. For more information about these and other format types, see the [Cloud-Init documentation](https://cloudinit.readthedocs.io/en/latest/explanation/format.html).
You can pass this user data when using the Amazon EC2 launch wizard. For more information, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
## Default Windows user data
This example user data script shows the default user data that your Windows container instances receive if you use the console. The script below does the following:
+ Sets the cluster name to the name you entered.
+ Sets the IAM roles for tasks.
+ Sets `json-file` and `awslogs` as the available logging drivers.
In addition, the following options are available when you use the `awsvpc` network mode.
+ `EnableTaskENI`: This flag turns on task networking and is required when you use the `awsvpc` network mode.
+ `AwsvpcBlockIMDS`: This optional flag blocks IMDS access for the task containers running in `awsvpc` network mode.
+ `AwsvpcAdditionalLocalRoutes`: This optional flag allows you to have additional routes.
Replace `ip-address` with the IP Address for the additional routes, for example 172.31.42.23/32.
You can use this script for your own container instances (provided that they are launched from the Amazon ECS-optimized Windows Server AMI).
Replace the `-Cluster cluster-name` line to specify your own cluster name.
```
Initialize-ECSAgent -Cluster cluster-name -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]' -EnableTaskENI -AwsvpcBlockIMDS -AwsvpcAdditionalLocalRoutes
'["ip-address"]'
```
For Windows tasks that are configured to use the `awslogs` logging driver, you must also set the `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` environment variable on your container instance. Use the following syntax.
Replace the `-Cluster cluster-name` line to specify your own cluster name.
```
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster cluster-name -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
```
## Windows agent installation user data
This example user data script installs the Amazon ECS container agent on an instance launched with a **Windows\$1Server-2016-English-Full-Containers** AMI. It has been adapted from the agent installation instructions on the [Amazon ECS Container Agent GitHub repository](https://github.com/aws/amazon-ecs-agent) README page.
**Note**
This script is shared for example purposes. It is much easier to get started with Windows containers by using the Amazon ECS-optimized Windows Server AMI. For more information, see [Creating an Amazon ECS cluster for Fargate workloads](create-cluster-console-v2.md).
For information about how to install the Amazon ECS agent on Windows Server 2022 Full, see[ Issue 3753](https://github.com/aws/amazon-ecs-agent/issues/3753) on GitHub.
You can use this script for your own container instances (provided that they are launched with a version of the **Windows\$1Server-2016-English-Full-Containers** AMI). Be sure to replace the `windows` line to specify your own cluster name (if you are not using a cluster called `windows`).
```
# Set up directories the agent uses
New-Item -Type directory -Path ${env:ProgramFiles}\Amazon\ECS -Force
New-Item -Type directory -Path ${env:ProgramData}\Amazon\ECS -Force
New-Item -Type directory -Path ${env:ProgramData}\Amazon\ECS\data -Force
# Set up configuration
$ecsExeDir = "${env:ProgramFiles}\Amazon\ECS"
[Environment]::SetEnvironmentVariable("ECS_CLUSTER", "windows", "Machine")
[Environment]::SetEnvironmentVariable("ECS_LOGFILE", "${env:ProgramData}\Amazon\ECS\log\ecs-agent.log", "Machine")
[Environment]::SetEnvironmentVariable("ECS_DATADIR", "${env:ProgramData}\Amazon\ECS\data", "Machine")
# Download the agent
$agentVersion = "latest"
$agentZipUri = "https://s3.amazonaws.com/amazon-ecs-agent/ecs-agent-windows-$agentVersion.zip"
$zipFile = "${env:TEMP}\ecs-agent.zip"
Invoke-RestMethod -OutFile $zipFile -Uri $agentZipUri
# Put the executables in the executable directory.
Expand-Archive -Path $zipFile -DestinationPath $ecsExeDir -Force
Set-Location ${ecsExeDir}
# Set $EnableTaskIAMRoles to $true to enable task IAM roles
# Note that enabling IAM roles will make port 80 unavailable for tasks.
[bool]$EnableTaskIAMRoles = $false
if (${EnableTaskIAMRoles}) {
$HostSetupScript = Invoke-WebRequest https://raw.githubusercontent.com/aws/amazon-ecs-agent/master/misc/windows-deploy/hostsetup.ps1
Invoke-Expression $($HostSetupScript.Content)
}
# Install the agent service
New-Service -Name "AmazonECS" `
-BinaryPathName "$ecsExeDir\amazon-ecs-agent.exe -windows-service" `
-DisplayName "Amazon ECS" `
-Description "Amazon ECS service runs the Amazon ECS agent" `
-DependsOn Docker `
-StartupType Manual
sc.exe failure AmazonECS reset=300 actions=restart/5000/restart/30000/restart/60000
sc.exe failureflag AmazonECS 1
Start-Service AmazonECS
```
# Using an HTTP proxy for Amazon ECS Windows container instances
You can configure your Amazon ECS container instances to use an HTTP proxy for both the Amazon ECS container agent and the Docker daemon. This is useful if your container instances do not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
To configure your Amazon ECS Windows container instance to use an HTTP proxy, set the following variables at launch time (with Amazon EC2 user data).
`[Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://proxy.mydomain:port", "Machine")`
Set `HTTP_PROXY` to the hostname (or IP address) and port number of an HTTP proxy to use for the Amazon ECS agent to connect to the internet. For example, your container instances may not have external network access through an Amazon VPC internet gateway, NAT gateway, or instance.
`[Environment]::SetEnvironmentVariable("NO_PROXY", "169.254.169.254,169.254.170.2,\\.\pipe\docker_engine", "Machine")`
Set `NO_PROXY` to `169.254.169.254,169.254.170.2,\\.\pipe\docker_engine` to filter EC2 instance metadata, IAM roles for tasks, and Docker daemon traffic from the proxy.
**Example Windows HTTP proxy user data script**
The example user data PowerShell script below configures the Amazon ECS container agent and the Docker daemon to use an HTTP proxy that you specify. You can also specify a cluster into which the container instance registers itself.
To use this script when you launch a container instance, follow the steps in [Launching an Amazon ECS Windows container instance](launch_window-container_instance.md). Just copy and paste the PowerShell script below into the **User data** field (be sure to substitute the red example values with your own proxy and cluster information).
The `-EnableTaskIAMRole` option is required to enable IAM roles for tasks. For more information, see [Amazon EC2 Windows instance additional configuration](task-iam-roles.md#windows_task_IAM_roles).
```
Import-Module ECSTools
$proxy = "http://proxy.mydomain:port"
[Environment]::SetEnvironmentVariable("HTTP_PROXY", $proxy, "Machine")
[Environment]::SetEnvironmentVariable("NO_PROXY", "169.254.169.254,169.254.170.2,\\.\pipe\docker_engine", "Machine")
Restart-Service Docker
Initialize-ECSAgent -Cluster MyCluster -EnableTaskIAMRole
```
# Configuring Amazon ECS Windows container instances to receive Spot Instance notices
Amazon EC2 terminates, stops, or hibernates your Spot Instance when the Spot price exceeds the maximum price for your request or capacity is no longer available. Amazon EC2 provides a Spot Instance interruption notice, which gives the instance a two-minute warning before it is interrupted. If Amazon ECS Spot Instance draining is enabled on the instance, ECS receives the Spot Instance interruption notice and places the instance in `DRAINING` status.
**Important**
Amazon ECS monitors for the Spot Instance interruption notices that have the `terminate` and `stop` instance-actions. If you specified either the `hibernate` instance interruption behavior when requesting your Spot Instances or Spot Fleet, then Amazon ECS Spot Instance draining is not supported for those instances.
When a container instance is set to `DRAINING`, Amazon ECS prevents new tasks from being scheduled for placement on the container instance. Service tasks on the draining container instance that are in the `PENDING` state are stopped immediately. If there are container instances in the cluster that are available, replacement service tasks are started on them.
You can turn on Spot Instance draining when you launch an instance. You must set the `ECS_ENABLE_SPOT_INSTANCE_DRAINING` parameter before you start the container agent. Replace *my-cluster* with the name of your cluster.
```
[Environment]::SetEnvironmentVariable("ECS_ENABLE_SPOT_INSTANCE_DRAINING", "true", "Machine")
# Initialize the agent
Initialize-ECSAgent -Cluster my-cluster
```
For more information, see [Launching an Amazon ECS Windows container instance](launch_window-container_instance.md).
# Amazon ECS clusters for external instances
Amazon ECS Anywhere provides support for registering an *external instance* such as an on-premises server or virtual machine (VM), to your Amazon ECS cluster. External instances are optimized for running applications that generate outbound traffic or process data. If your application requires inbound traffic, the lack of Elastic Load Balancing support makes running these workloads less efficient. Amazon ECS added a new `EXTERNAL` launch type that you can use to create services or run tasks on your external instances.
## Supported operating systems and system architectures
The following is the list of supported operating systems. The `x86_64` and `ARM64` CPU architectures are supported.
+ Amazon Linux 2023
+ Ubuntu 20, Ubuntu 22, Ubuntu 24
+ RHEL 9 — You must ensure that Docker is installed before you run the [ECS Anywhere install script](https://github.com/aws/amazon-ecs-agent/blob/master/scripts/ecs-anywhere-install.sh). For more information, see [Install Docker Engine on RHEL](https://docs.docker.com/engine/install/rhel/) in the Docker documentation.
Beginning August 7 2026, the following operating systems are no longer supported by Amazon ECS Anywhere:
+ Amazon Linux 2
+ CentOS Stream 9
+ RHEL 7, RHEL 8
+ Fedora 32, Fedora 33, Fedora 40
+ openSUSE Tumbleweed
+ Ubuntu 18
+ Debian 9, Debian 10, Debian 11, Debian 12
+ SUSE Enterprise Server 15
+ Windows Server 2022, Windows Server 2019, Windows Server 2016, Windows Server 20H2
## Considerations
Before you start using external instances, be aware of the following considerations.
+ You can register an external instance to one cluster at a time. For instructions on how to register an external instance with a different cluster, see [Deregistering an Amazon ECS external instance](ecs-anywhere-deregistration.md).
+ Your external instances require an IAM role that allows them to communicate with AWS APIs. For more information, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md).
+ Your external instances should not have a preconfigured instance credential chain defined locally as this will interfere with the registration script.
+ To send container logs to CloudWatch Logs, make sure that you create and specify a task execution IAM role in your task definition.
+ When an external instance is registered to a cluster, the `ecs.capability.external` attribute is associated with the instance. This attribute identifies the instance as an external instance. You can add custom attributes to your external instances to use as a task placement constraint. For more information, see [Custom attributes](task-placement-constraints.md#ecs-custom-attributes).
+ You can add resource tags to your external instance. For more information, see [Adding tags to External container instances for Amazon ECS](instance-details-tags-external.md).
+ ECS Exec is supported on external instances. For more information, see [Monitor Amazon ECS containers with ECS Exec](ecs-exec.md).
+ The following are additional considerations that are specific to networking with your external instances. For more information, see [Networking](#ecs-anywhere-networking).
+ Service load balancing isn't supported.
+ Service discovery isn't supported.
+ Tasks that run on external instances must use the `bridge`, `host`, or `none` network modes. The `awsvpc` network mode isn't supported.
+ There are Amazon ECS service domains in each AWS Region. These service domains must be allowed to send traffic to your external instances.
+ The SSM Agent installed on your external instance maintains IAM credentials that are rotated every 30 minutes using a hardware fingerprint. If your external instance loses connection to AWS, the SSM Agent automatically refreshes the credentials after the connection is re-established. For more information, see [Validating on-premises servers and virtual machines using a hardware fingerprint](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html#fingerprint-validation) in the *AWS Systems Manager User Guide*.
+ You can run Linux tasks on external instances in an IPv6-only configuration as long as the instances are in IPv6-only subnets. For more information, see [Using a VPC in IPv6-only mode](task-networking.md#networking-ipv6-only).
+ The `UpdateContainerAgent` API isn't supported. For instructions on how to update the SSM Agent or the Amazon ECS agent on your external instances, see [Updating the AWS Systems Manager agent and Amazon ECS container agent on an external instance](ecs-anywhere-updates.md).
+ Amazon ECS capacity providers aren't supported. To create a service or run a standalone task on your external instances, use the `EXTERNAL` launch type.
+ SELinux isn't supported.
+ Using Amazon EFS volumes or specifying an `EFSVolumeConfiguration` isn't supported.
+ Integration with App Mesh isn't supported.
+ If you use the console to create an external instance task definition, you must create the task definition with the console JSON editor.
+ When you use a non Amazon ECS-optimized AMI, run the following commands on the external container instance to configure rules to use IAM roles for tasks. For more information, see [External instance additional configuration](task-iam-roles.md#enable_task_iam_roles).
```
$ sysctl -w net.ipv4.conf.all.route_localnet=1
$ iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination 127.0.0.1:51679
$ iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 51679
```
### Networking
Amazon ECS external instances are optimized for running applications that generate outbound traffic or process data. If your application requires inbound traffic, such as a web service, the lack of Elastic Load Balancing support makes running these workloads less efficient because there isn't support for placing these workloads behind a load balancer.
The following are additional considerations that are specific to networking with your external instances.
+ Service load balancing isn't supported.
+ Service discovery isn't supported.
+ Linux tasks that run on external instances must use the `bridge`, `host`, or `none` network modes. The `awsvpc` network mode isn't supported.
For more information about each network mode, see [Amazon ECS task networking options for EC2 instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html).
+ You can run Linux tasks on external instances in an IPv6-only configuration as long as the instances are in IPv6-only subnets. For more information, see [Using a VPC in IPv6-only mode](task-networking.md#networking-ipv6-only).
+ There are Amazon ECS service domains in each Region and must be allowed to send traffic to your external instances.
+ The SSM Agent installed on your external instance maintains IAM credentials that are rotated every 30 minutes using a hardware fingerprint. If your external instance loses connection to AWS, the SSM Agent automatically refreshes the credentials after the connection is re-established. For more information, see [Validating on-premises servers and virtual machines using a hardware fingerprint](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html#fingerprint-validation) in the *AWS Systems Manager User Guide*.
The following domains are used for communication between the Amazon ECS service and the Amazon ECS agent that's installed on your external instance. Make sure that traffic is allowed and that DNS resolution works. For each endpoint, *region* represents the Region identifier for an AWS Region that's supported by Amazon ECS, such as `us-east-2` for the US East (Ohio) Region. The endpoints for all Regions that you use should be allowed. For the `ecs-a` and `ecs-t` endpoints, you should include an asterisk (for example, `ecs-a-*`).
+ `ecs-a-*.region.amazonaws.com` — This endpoint is used when managing tasks.
+ `ecs-t-*.region.amazonaws.com` — This endpoint is used to manage task and container metrics.
+ `ecs.region.amazonaws.com` — This is the service endpoint for Amazon ECS.
+ `ssm.region.amazonaws.com ` — This is the service endpoint for AWS Systems Manager.
+ `ec2messages.region.amazonaws.com` — This is the service endpoint that AWS Systems Manager uses to communicate between the Systems Manager agent and the Systems Manager service in the cloud.
+ `ssmmessages.region.amazonaws.com` — This is the service endpoint that is required to create and delete session channels with the Session Manager service in the cloud.
+ If your tasks require communication with any other AWS services, make sure that those service endpoints are allowed. Example applications include using Amazon ECR to pull container images or using CloudWatch for CloudWatch Logs. For more information, see [Service endpoints](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) in the *AWS General Reference*.
### Amazon FSx for Windows File Server with ECS Anywhere
**Important**
Windows support for Amazon ECS Anywhere has been deprecated. This section is no longer applicable.
In order to use the Amazon FSx for Windows File Server with Amazon ECS external instances you must establish a connection between your on-premises data center and the AWS Cloud. For information about the options for connecting your network to your VPC, see [Amazon Virtual Private Cloud Connectivity Options](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/introduction.html).
### gMSA with ECS Anywhere
**Important**
Windows support for Amazon ECS Anywhere has been deprecated. This section is no longer applicable.
The following use cases were supported for ECS Anywhere when Windows was a supported operating system.
+ The Active Directory is in the AWS Cloud - For this configuration, you create a connection between your on-premises network and the AWS Cloud using an AWS Direct Connect connection. For information about how to create the connection, see [Amazon Virtual Private Cloud Connectivity Options](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/introduction.html).You create an Active Directory in the AWS Cloud. For information about how to get started with AWS Directory Service, see [Setting up AWS Directory Service](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/setting_up.html) in the *AWS Directory Service Administration Guide*. You can then join your external instances to the domain using the AWS Direct Connect connection. For information about working with gMSA with Amazon ECS, see [Learn how to use gMSAs for EC2 Windows containers for Amazon ECS](windows-gmsa.md).
+ The Active Directory is in the on-premises data center. - For this configuration, you join your external instances to the on-premises Active Directory. You then use the locally available credentials when you run the Amazon ECS tasks.
# Creating an Amazon ECS cluster for External instance workloads
You create a cluster to define the infrastructure your tasks and services run on.
Before you begin, be sure that you've completed the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) and assign the appropriate IAM permission. For more information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies). The Amazon ECS console provides a simple way to create the resources that are needed by an Amazon ECS cluster by creating a CloudFormation stack.
To make the cluster creation process as easy as possible, the console has default selections for many choices which we describe below. There are also help panels available for most of the sections in the console which provide further context.
You can modify the following options:
+ Add a namespace to the cluster.
A namespace allows services that you create in the cluster can connect to the other services in the namespace without additional configuration. For more information, see [Interconnect Amazon ECS services](interconnecting-services.md).
+ Configure the cluster for external instances
+ Assign a AWS KMS key for your managed storage. For information about how to create a key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*.
+ Add tags to help you identify your cluster.
**To create a new cluster (Amazon ECS console)**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, choose **Create cluster**.
1. Under **Cluster configuration**, configure the following:
+ For **Cluster name**, enter a unique name.
The name can contain up to 255 letters (uppercase and lowercase), numbers, and hyphens.
+ (Optional) To have the namespace used for Service Connect be different from the cluster name, for **Namespace**, enter a unique name.
1. (Optional) Use Container Insights, expand **Monitoring**, and then choose one of the following options:
+ To use the recommended Container Insights with enhanced observability, choose **Container Insights with enhanced observability**.
+ To use Container Insights, choose **Container Insights**.
1. (Optional) To use ECS Exec to debug tasks in the cluster, expand **Troubleshooting configuration**, and then configure the following:
+ Select **Turn on ECS Exec**.
+ (Optional) For **AWS KMS key for ECS Exec**, enter the ARN of the AWS KMS key you want to use to encrypt the ECS Exec session data.
+ (Optional) For **ECS Exec logging**, choose the log destination:
+ To send logs to CloudWatch Logs, choose **Amazon CloudWatch**.
+ To send logs to Amazon S3, choose **Amazon S3**.
+ To disable logging, choose **None**.
1. (Optional) Encrypt the data on managed storage. Under **Encryption**, for **Managed storage**, enter the ARN of the AWS KMS key you want to use to encrypt the managed storage data.
1. (Optional) To help identify your cluster, expand **Tags**, and then configure your tags.
[Add a tag] Choose **Add tag** and do the following:
+ For **Key**, enter the key name.
+ For **Value**, enter the key value.
1. Choose **Create**.
## Next steps
You must register the instances with the cluster. For more information, see [Registering an external instance to an Amazon ECS cluster](ecs-anywhere-registration.md).
Create a task definition for the external launch type. For more information, see [Creating an Amazon ECS task definition using the console](create-task-definition.md)
Run your applications as standalone tasks, or as part of a service. For more information, see the following:
+ [Running an application as an Amazon ECS task](standalone-task-create.md)
+ [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md)
# Registering an external instance to an Amazon ECS cluster
For each external instance you register with an Amazon ECS cluster, it must have the SSM Agent, the Amazon ECS container agent, and Docker installed. To register the external instance to an Amazon ECS cluster, it must first be registered as an AWS Systems Manager managed instance. You can create the installation script in a few clicks on the Amazon ECS console. The installation script includes an Systems Manager activation key and commands to install each of the required agents and Docker. The installation script must be run on your on-premises server or VM to complete the installation and registration steps.
**Note**
Before registering your Linux external instance with the cluster, create the `/etc/ecs/ecs.config` file on your external instance and add any container agent configuration parameters that you want. You can't do this after registering the external instance to a cluster. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md).
------
#### [ AWS Management Console ]
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, choose a cluster to register your external instance to.
1. On the **Cluster : *name*** page, choose the **Infrastructure** tab.
1. On the **Register external instances** page, complete the following steps.
1. For **Activation key duration (in days)**, enter the number of days that the activation key remains active for. After the number of days you entered pass, the key no longer works when registering an external instance.
1. For **Number of instances**, enter the number of external instances that you want to register to your cluster with the activation key.
1. For **Instance role**, choose the IAM role to associate with your external instances. If a role wasn't already created, choose **Create new role** to have Amazon ECS create a role on your behalf. For more information about what IAM permissions are required for your external instances, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md).
1. Copy the registration command. This command should be run on each external instance you want to register to the cluster.
**Important**
The bash portion of the script must be run as root. If the command isn't run as root, an error is returned.
1. Choose **Close**.
------
#### [ AWS CLI for Linux operating systems ]
1. Create an Systems Manager activation pair. This is used for Systems Manager managed instance activation. The output includes an `ActivationId` and `ActivationCode`. You use these in a later step. Make sure that you specify the ECS Anywhere IAM role that you created. For more information, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md).
```
aws ssm create-activation --iam-role ecsAnywhereRole | tee ssm-activation.json
```
1. On your on-premises server or virtual machine (VM), download the installation script.
```
curl --proto "https" -o "/tmp/ecs-anywhere-install.sh" "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh"
```
1. (Optional) On your on-premises server or virtual machine (VM), use the following steps to verify the installation script using the script signature file.
1. Download and install GnuPG. For more information about GNUpg, see the [GnuPG website](https://www.gnupg.org). For Linux systems, install `gpg` using the package manager on your flavor of Linux.
1. Retrieve the Amazon ECS PGP public key.
```
gpg --keyserver hkp://keys.gnupg.net:80 --recv BCE9D9A42D51784F
```
1. Download the installation script signature. The signature is an ascii detached PGP signature stored in a file with the `.asc` extension.
```
curl --proto "https" -o "/tmp/ecs-anywhere-install.sh.asc" "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh.asc"
```
1. Verify the installation script file using the key.
```
gpg --verify /tmp/ecs-anywhere-install.sh.asc /tmp/ecs-anywhere-install.sh
```
The following is the expected output.
```
gpg: Signature made Tue 25 May 2021 07:16:29 PM UTC
gpg: using RSA key 50DECCC4710E61AF
gpg: Good signature from "Amazon ECS " [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: F34C 3DDA E729 26B0 79BE AEC6 BCE9 D9A4 2D51 784F
Subkey fingerprint: D64B B6F9 0CF3 77E9 B5FB 346F 50DE CCC4 710E 61AF
```
1. On your on-premises server or virtual machine (VM), run the installation script. Specify the cluster name, Region, and the Systems Manager activation ID and activation code from the first step.
```
sudo bash /tmp/ecs-anywhere-install.sh \
--region $REGION \
--cluster $CLUSTER_NAME \
--activation-id $ACTIVATION_ID \
--activation-code $ACTIVATION_CODE
```
For an on-premises server or virtual machine (VM) that has the NVIDIA driver installed for GPU workloads, you must add the `--enable-gpu` flag to the installation script. When this flag is specified, the install script verifies that the NVIDIA driver is running and then adds the required configuration variables to run your Amazon ECS tasks. For more information about running GPU workloads and specifying GPU requirements in a task definition, see [Specifying GPUs in an Amazon ECS task definition](ecs-gpu-specifying.md).
```
sudo bash /tmp/ecs-anywhere-install.sh \
--region $REGION \
--cluster $CLUSTER_NAME \
--activation-id $ACTIVATION_ID \
--activation-code $ACTIVATION_CODE \
--enable-gpu
```
Use the following steps to register an existing external instance with a different cluster.
**To register an existing external instance with a different cluster**
1. Stop the Amazon ECS container agent.
```
sudo systemctl stop ecs.service
```
1. Edit the `/etc/ecs/ecs.config` file and on the `ECS_CLUSTER` line, ensure the cluster name matches the name of the cluster to register the external instance with.
1. Remove the existing Amazon ECS agent data.
```
sudo rm /var/lib/ecs/data/agent.db
```
1. Start the Amazon ECS container agent.
```
sudo systemctl start ecs.service
```
------
#### [ AWS CLI for Windows operating systems ]
1. Create an Systems Manager activation pair. This is used for Systems Manager managed instance activation. The output includes an `ActivationId` and `ActivationCode`. You use these in a later step. Make sure that you specify the ECS Anywhere IAM role that you created. For more information, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md).
```
aws ssm create-activation --iam-role ecsAnywhereRole | tee ssm-activation.json
```
1. On your on-premises server or virtual machine (VM), download the installation script.
```
Invoke-RestMethod -URI "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install.ps1" -OutFile “ecs-anywhere-install.ps1”
```
1. (Optional) The Powershell script is signed by Amazon and therefore, Windows automatically performs the certificate validation on the same. You do not need to perform any manual validation.
To manually verify the certificate, right-click on the file, navigate to properties and use the Digital Signatures tab to obtain more details.
This option is only available when the host has the certificate in the certificate store.
The verification should return information similar to the following:
```
# Verification (PowerShell)
Get-AuthenticodeSignature -FilePath .\ecs-anywhere-install.ps1
SignerCertificate Status Path
----------------- ------ ----
EXAMPLECERTIFICATE Valid ecs-anywhere-install.ps1
...
Subject : CN="Amazon Web Services, Inc.",...
----
```
1. On your on-premises server or virtual machine (VM), run the installation script. Specify the cluster name, Region, and the Systems Manager activation ID and activation code from the first step.
```
.\ecs-anywhere-install.ps1 -Region $Region -Cluster $Cluster -ActivationID $ActivationID -ActivationCode $ActivationCode
```
1. Verify the Amazon ECS container agent is running.
```
Get-Service AmazonECS
Status Name DisplayName
------ ---- -----------
Running AmazonECS Amazon ECS
```
Use the following steps to register an existing external instance with a different cluster.
**To register an existing external instance with a different cluster**
1. Stop the Amazon ECS container agent.
```
Stop-Service AmazonECS
```
1. Modify the `ECS_CLUSTER` parameter so that the cluster name matches the name of the cluster to register the external instance with.
```
[Environment]::SetEnvironmentVariable("ECS_CLUSTER", $ECSCluster, [System.EnvironmentVariableTarget]::Machine)
```
1. Remove the existing Amazon ECS agent data.
```
Remove-Item -Recurse -Force $env:ProgramData\Amazon\ECS\data\*
```
1. Start the Amazon ECS container agent.
```
Start-Service AmazonECS
```
------
The AWS CLI can be used to create a Systems Manager activation before running the installation script to complete the external instance registration process.
# Deregistering an Amazon ECS external instance
We recommend that you deregister the instance from both Amazon ECS and AWS Systems Manager after you are done with the instance. Following deregistration, the external instance is no longer able to accept new tasks.
If you have tasks that are running on the container instance when you deregister it, the tasks remain running until they stop through some other means. However, these tasks are no longer monitored or accounted for by Amazon ECS. If these tasks on your external instance are part of an Amazon ECS service, then the service scheduler starts another copy of that task, on a different instance, if possible.
After you deregister the instance, clean up the remaining AWS resources on the instance. You can then register it to a new cluster.
## Procedure
------
#### [ AWS Management Console ]
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, choose the Region where your external instance is registered.
1. In the navigation pane, choose **Clusters** and select the cluster that hosts the external instance.
1. On the **Cluster : *name*** page, choose the **Infrastructure** tab.
1. Under **Container instances**, select the external instance ID to deregister. You're redirected to the container instance detail page.
1. On the **Container Instance : *id*** page, choose **Deregister**.
1. Review the deregistration message. Select **Deregister from AWS Systems Manager** to also deregister the external instance as an Systems Manager managed instance. Choose **Deregister**.
**Note**
You can deregister the external instance as an Systems Manager managed instance in the Systems Manager console. For instructions, see [Deregistering managed nodes in a hybrid and multicloud environment](https://docs.aws.amazon.com/systems-manager/latest/userguide/fleet-manager-deregister-hybrid-nodes.html) in the *AWS Systems Manager User Guide*.
1. After you deregister the instance, clean up AWS resources on your on-premises server or VM.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere-deregistration.html)
------
#### [ AWS CLI ]
1. You need the instance ID and the container instance ARN to deregister the container instance. If you do not have theses values, run the following comands
Run the following commandto get the instance ID.
You use the instance ID (`instanceID`) to get the container instance ARN (`containerInstanceARN`).
```
instanceId=$(aws ssm describe-instance-information --region "{{ region }}" | jq ".InstanceInformationList[] |select(.IPAddress==\"{{ IPv4 Address }}\") | .InstanceId" | tr -d'"'
```
Run the following commands.
You use the `containerInstanceArn` as a parameter in the command to deregister the instance (`deregister-container-instance`).
```
instances=$(aws ecs list-container-instances --cluster "{{ cluster }}" --region "{{ region }}" | jq -c '.containerInstanceArns')
containerInstanceArn=$(aws ecs describe-container-instances --cluster "{{ cluster }}" --region "{{ region }}" --container-instances $instances | jq ".containerInstances[] | select(.ec2InstanceId==\"{{ instanceId }}\") | .containerInstanceArn" | tr -d '"')
```
1. Run the following command to drain the instance.
```
aws ecs update-container-instances-state --cluster "{{ cluster }}" --region "{{ region }}" --container-instances "{{ containerInstanceArn }}" --status DRAINING
```
1. After the container instance finishes draining, run the following command to deregister the instance.
```
aws ecs deregister-container-instance --cluster "{{ cluster }}" --region "{{ region }}" --container-instance "{{ containerInstanceArn }}"
```
1. Run the following command to remove the container instance from SSM.
```
aws ssm deregister-managed-instance --region "{{ region }}" --instance-id "{{ instanceId }}"
```
1. After you deregister the instance, clean up AWS resources on your on-premises server or VM.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere-deregistration.html)
------
# Updating the AWS Systems Manager agent and Amazon ECS container agent on an external instance
Your on-premises server or VM must run both the AWS Systems Manager Agent (SSM Agent) and the Amazon ECS container agent when running Amazon ECS workloads. AWS releases new versions of these agents when any capabilities are added or updated. If your external instances are using an earlier version of either agent, you can update them using the following procedures.
## Updating the SSM Agent on an external instance
AWS Systems Manager recommends that you automate the process of updating the SSM Agent on your instances. They provide several methods to automate updates. For more information, see [Automating updates to SSM Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-automatic-updates.html) in the *AWS Systems Manager User Guide*.
## Updating the Amazon ECS agent on an external instance
On your external instances, the Amazon ECS container agent is updated by upgrading the `ecs-init` package. Updating the Amazon ECS agent doesn't interrupt the running tasks or services. Amazon ECS provides the `ecs-init` package and signature file in an Amazon S3 bucket in each Region. Beginning with `ecs-init` version `1.52.1-1`, Amazon ECS provides separate `ecs-init` packages for use depending on the operating system and system architecture your external instance uses.
Use the following table to determine the `ecs-init` package that you should download based on the operating system and system architecture your external instance uses.
**Note**
You can determine which operating system and system architecture that your external instance uses by using the following commands.
```
cat /etc/os-release
uname -m
```
| Operating systems (architecture) | ecs-init package |
| --- | --- |
| CentOS 7 (x86\$164) CentOS 8 (x86\$164) CentOS Stream 9 (x86\$164) SUSE Enterprise Server 15 (x86\$164) RHEL 7 (x86\$164) RHEL 8 (x86\$164) | `amazon-ecs-init-latest.x86_64.rpm` |
| CentOS 7 (aarch64) CentOS 8 (aarch64) CentOS Stream 9 (aarch64) RHEL 7 (aarch64) | `amazon-ecs-init-latest.aarch64.rpm` |
| Debian 9 (x86\$164) Debian 10 (x86\$164) Debian 11 (x86\$164) Debian 12 (x86\$164) Ubuntu 18 (x86\$164) Ubuntu 20 (x86\$164) Ubuntu 22 (x86\$164) Ubuntu 24 (x86\$164) | `amazon-ecs-init-latest.amd64.deb` |
| Debian 9 (aarch64) Debian 10 (aarch64) Debian 11 (aarch64) Debian 12 (aarch64) Ubuntu 18 (aarch64) Ubuntu 20 (aarch64) Ubuntu 22 (aarch64) Ubuntu 24 (aarch64) | `amazon-ecs-init-latest.arm64.deb` |
Follow these steps to update the Amazon ECS agent.
**To update the Amazon ECS agent**
1. Confirm the Amazon ECS agent version that you're running.
```
curl -s 127.0.0.1:51678/v1/metadata | python3 -mjson.tool
```
1. Download the `ecs-init` package for your operating system and system architecture. Amazon ECS provides the `ecs-init` package file in an Amazon S3 bucket in each Region. Make sure that you replace the ** identifier in the command with the Region name (for example, `us-west-2`) that you're geographically closest to.
**amazon-ecs-init-latest.x86\$164.rpm**
```
curl -o amazon-ecs-init.rpm https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.x86_64.rpm
```
**amazon-ecs-init-latest.aarch64.rpm**
```
curl -o amazon-ecs-init.rpm https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.aarch64.rpm
```
**amazon-ecs-init-latest.amd64.deb**
```
curl -o amazon-ecs-init.deb https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.amd64.deb
```
**amazon-ecs-init-latest.arm64.deb**
```
curl -o amazon-ecs-init.deb https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.arm64.deb
```
1. (Optional) Verify the validity of the `ecs-init` package file using the PGP signature.
1. Download and install GnuPG. For more information about GNUpg, see the [GnuPG website](https://www.gnupg.org). For Linux systems, install `gpg` using the package manager on your flavor of Linux.
1. Retrieve the Amazon ECS PGP public key.
```
gpg --keyserver hkp://keys.gnupg.net:80 --recv BCE9D9A42D51784F
```
1. Download the `ecs-init` package signature. The signature is an ASCII detached PGP signature that's stored in a file with the `.asc` extension. Amazon ECS provides the signature file in an Amazon S3 bucket in each Region. Make sure that you replace the ** identifier in the command with the Region name (for example, `us-west-2`) that you're geographically closest to.
**amazon-ecs-init-latest.x86\$164.rpm**
```
curl -o amazon-ecs-init.rpm.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.x86_64.rpm.asc
```
**amazon-ecs-init-latest.aarch64.rpm**
```
curl -o amazon-ecs-init.rpm.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.aarch64.rpm.asc
```
**amazon-ecs-init-latest.amd64.deb**
```
curl -o amazon-ecs-init.deb.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.amd64.deb.asc
```
**amazon-ecs-init-latest.arm64.deb**
```
curl -o amazon-ecs-init.deb.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.arm64.deb.asc
```
1. Verify the `ecs-init` package file using the key.
**For the `rpm` packages**
```
gpg --verify amazon-ecs-init.rpm.asc ./amazon-ecs-init.rpm
```
**For the `deb` packages**
```
gpg --verify amazon-ecs-init.deb.asc ./amazon-ecs-init.deb
```
The following is the expected output.
```
gpg: Signature made Fri 14 May 2021 09:31:36 PM UTC
gpg: using RSA key 50DECCC4710E61AF
gpg: Good signature from "Amazon ECS " [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: F34C 3DDA E729 26B0 79BE AEC6 BCE9 D9A4 2D51 784F
Subkey fingerprint: D64B B6F9 0CF3 77E9 B5FB 346F 50DE CCC4 710E 61AF
```
1. Install the `ecs-init` package.
**For the `rpm` package on CentOS 7, CentOS 8, and RHEL 7**
```
sudo yum install -y ./amazon-ecs-init.rpm
```
**For the `rpm` package on SUSE Enterprise Server 15**
```
sudo zypper install -y --allow-unsigned-rpm ./amazon-ecs-init.rpm
```
**For the `deb` package**
```
sudo dpkg -i ./amazon-ecs-init.deb
```
1. Restart the `ecs` service.
```
sudo systemctl restart ecs
```
1. Verify the Amazon ECS agent version was updated.
```
curl -s 127.0.0.1:51678/v1/metadata | python3 -mjson.tool
```
# Updating an Amazon ECS cluster
You can modify the following cluster properties:
+ Set a default capacity provider
Each cluster can have one or more capacity providers and an optional capacity provider strategy. The capacity provider strategy determines how the tasks are spread across the cluster's capacity providers. When you run a standalone task or create a service, you either use the cluster's default capacity provider strategy or a capacity provider strategy that overrides the default one.
+ Turn on Container Insights.
CloudWatch Container Insights collects, aggregates, and summarizes metrics and logs from your containerized applications and microservices. Container Insights also provides diagnostic information, such as container restart failures, that you use to isolate issues and resolve them quickly. For more information, see [Monitor Amazon ECS containers using Container Insights with enhanced observability](cloudwatch-container-insights.md).
+ Add tags to help you identify your clusters.
**Procedure**
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 **Update cluster**.
1. To set the default capacity provider, under **Default capacity provider strategy**, choose **Add more**.
1. For **Capacity provider**, choose the capacity provider.
1. (Optional) For **Base**, enter the minimum number of tasks that run on the capacity provider.
You can only set a **Base** value for one capacity provider.
1. (Optional) For **Weight**, enter the relative percentage of the total number of launched tasks that use the specified capacity provider.
1. (Optional) Repeat the steps for any additional capacity providers.
1. To turn on or off Container Insights, expand **Monitoring**, and then turn on **Use Container Insights**.
1. To help identify your cluster, expand **Tags**, and then configure your tags.
[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 **Update**.
# Deleting an Amazon ECS cluster
If you are finished using a cluster, you can delete it. After you delete the cluster, it transitions to the `INACTIVE` state. Clusters 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` clusters persisting.
Before you delete a cluster, you must perform the following operations:
+ Delete all services in the cluster. For more information, see [Deleting an Amazon ECS service using the console](delete-service-v2.md).
+ Stop all currently running tasks. For more information, see [Stopping an Amazon ECS task](standalone-task-stop.md).
+ Deregister all registered container instances in the cluster. For more information, see [Deregistering an Amazon ECS container instance](deregister_container_instance.md).
+ Delete the namespace. For more information, see [Deleting namespaces](https://docs.aws.amazon.com/cloud-map/latest/dg/deleting-namespaces.html) in the *AWS Cloud Map Developer Guide*.
**Procedure**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, select the Region to use.
1. In the navigation pane, choose **Clusters**.
1. On the **Clusters** page, select the cluster to delete.
1. In the upper-right of the page, choose **Delete Cluster**.
A message is displayed when you did not delete all the resources associated with the cluster.
1. In the confirmation box, enter **delete *cluster name***.
# Deregistering an Amazon ECS container instance
**Important**
This topic is for container instances created in Amazon EC2 only. For more information about deregistering external instances, see [Deregistering an Amazon ECS external instance](ecs-anywhere-deregistration.md).
When you are finished with an Amazon EC2 backed container instance, you should deregister it from your cluster. Following deregistration, the container instance is no longer able to accept new tasks.
If you have tasks running on the container instance when you deregister it, these tasks remain running until you terminate the instance or the tasks stop through some other means. However, these tasks are orphaned which means they are no longer monitored or accounted for by Amazon ECS. If an orphaned task on your container instance is part of an Amazon ECS service, then the service scheduler starts another copy of that task, on a different container instance, if possible. Any containers in orphaned service tasks that are registered with an Application Load Balancer target group are deregistered. They begin connection draining according to the settings on the load balancer or target group. If an orphaned tasks is using the `awsvpc` network mode, their elastic network interfaces are deleted.
If you intend to use the container instance for some other purpose after deregistration, you should stop all of the tasks running on the container instance before deregistration. This stops any orphaned tasks from consuming resources.
When deregistering a container instance, be aware of the following considerations.
+ Because each container instance has unique state information, they should not be deregistered from one cluster and re-registered into another. To relocate container instance resources, we recommend that you terminate container instances from one cluster and launch new container instances in the new cluster. For more information, see [Terminate your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html) in the *Amazon EC2 User Guide* and [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
+ If the container instance is managed by an Auto Scaling group or a CloudFormation stack, terminate the instance by updating the Auto Scaling group or CloudFormation stack. Otherwise, the Auto Scaling group or CloudFormation will create a new instance after you terminate it.
+ If you terminate a running container instance with a connected Amazon ECS container agent, the agent automatically deregisters the instance from your cluster. Stopped container instances or instances with disconnected agents are not automatically deregistered when terminated.
+ Deregistering a container instance removes the instance from a cluster, but it does not terminate the Amazon EC2 instance. If you are finished using the instance, be sure to terminate it to stop billing. For more information, see [Terminate your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html) in the *Amazon EC2 User Guide*.
## Procedure
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. From the navigation bar, choose the Region where your external instance is registered.
1. In the navigation pane, choose **Clusters** and select the cluster that hosts the instance.
1. On the **Cluster : *name*** page, choose the **Infrastructure** tab.
1. Under **Container instances**, select the instance ID to deregister. You're redirected to the container instance detail page.
1. On the **Container Instance : *id*** page, choose **Deregister**.
1. On the confirmation screen, choose **Deregister**.
1. If you are finished with the container instance, terminate the underlying Amazon EC2 instance. For more information, see [Terminate Your Instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html) in the *Amazon EC2 User Guide*.
# Draining Amazon ECS container instances
There might be times when you need to remove a container instance from your cluster, for example, to perform system updates or to scale down the cluster capacity. Amazon ECS provides the ability to transition a container instance to a `DRAINING` status. This is referred to as *container instance draining*. When a container instance is set to `DRAINING`, Amazon ECS prevents new tasks from being scheduled for placement on the container instance.
## Draining behavior for services
Any tasks that are part of a service that are in a `PENDING` state are stopped immediately. If there is available container instance capacity in the cluster, the service scheduler will start replacement tasks. If there isn't enough container instance capacity, a service event message will be sent indicating the issue.
Tasks that are part of a service on the container instance that are in a `RUNNING` state are transitioned to a `STOPPED` state. The service scheduler attempts to replace the tasks according to the service's deployment type and deployment configuration parameters, `minimumHealthyPercent` and `maximumPercent`. For more information, see [Amazon ECS services](ecs_services.md) and [Amazon ECS service definition parameters](service_definition_parameters.md).
+ If `minimumHealthyPercent` is below 100%, the scheduler can ignore `desiredCount` temporarily during task replacement. For example, `desiredCount` is four tasks, a minimum of 50% allows the scheduler to stop two existing tasks before starting two new tasks. If the minimum is 100%, the service scheduler can't remove existing tasks until the replacement tasks are considered healthy. If tasks for services that do not use a load balancer are in the `RUNNING` state, they are considered healthy. Tasks for services that use a load balancer are considered healthy if they are in the `RUNNING` state and the container instance they are hosted on is reported as healthy by the load balancer.
**Important**
If you use Spot Instances and `minimumHealthyPercent` is greater than or equal to 100%, then the service will not have enough time to replace the task before the Spot Instance terminates.
+ The `maximumPercent` parameter represents an upper limit on the number of running tasks during task replacement, which allows you to define the replacement batch size. For example, if `desiredCount` of four tasks, a maximum of 200% starts four new tasks before stopping the four tasks to be drained (provided that the cluster resources required to do this are available). If the maximum is 100%, then replacement tasks can't start until the draining tasks have stopped.
**Important**
If both `minimumHealthyPercent` and `maximumPercent` are 100%, then the service can't remove existing tasks, and also cannot start replacement tasks. This prevents successful container instance draining and prevents making new deployments.
## Draining behavior for standalone tasks
Any standalone tasks in the `PENDING` or `RUNNING` state are unaffected; you must wait for them to stop on their own or stop them manually. The container instance will remain in `DRAINING` status.
## 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.
Customer-initiated termination
Provides direct control over instance removal when you need to remove container instances from service immediately. You run `deregister-container-instance` with the `force` request parameter set to true. This means 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).
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 because they might complete naturally. 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 force deregistration procedures and immediate termination of all remaining tasks regardless of the completion status.
A container instance has completed draining when all tasks running on the instance transition to a `STOPPED` state. The container instance remains in a `DRAINING` state until it is activated again or deleted. You can verify the state of the tasks on the container instance by using the [ListTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTasks.html) operation with the `containerInstance` parameter to get a list of tasks on the instance followed by a [DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html) operation with the Amazon Resource Name (ARN) or ID of each task to verify the task state.
When you are ready for the container instance to start hosting tasks again, you change the state of the container instance from `DRAINING` to `ACTIVE`. The Amazon ECS service scheduler then considers the container instance for task placement again.
## Procedure
The following steps can be used to set a container instance to draining using the new AWS Management Console.
You can also use the [UpdateContainerInstancesState](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateContainerInstancesState.html) API action or the [update-container-instances-state](https://docs.aws.amazon.com/cli/latest/reference/ecs/update-container-instances-state.html) command to change the status of a container instance to `DRAINING`.
**AWS Management 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 a cluster that hosts your instances.
1. On the **Cluster : *name*** page, choose the **Infrastructure** tab. Then, under **Container instances** select the check box for each container instance you want to drain.
1. Choose **Actions**, **Drain**.
# Changing the instance type or size outside of the Auto Scaling group
AWS recommends that you keep your infrastructure immutable. If you need to change instance sizes, you can either:
+ Scale horizontally and add additional instances. Then, place additional tasks on those instances, or you
+ Scale vertically by launching a new, larger/smaller instance and then drain the old instance.
Both of these approaches will help minimize application availability impact.
If you used another method to change the instance, you might receive the following error:
```
Container instance type changes are not supported.
```
When you get this error, perform the following steps:
1. Launch new instances with the desired instance type.
1. Drain your old instance types. For more information, see [Draining Amazon ECS container instances](container-instance-draining.md).
# Amazon ECS EC2 Container Instances
The Amazon ECS agent is a process that runs on every container instance that is registered with your cluster. It facilitates the communication between your container instances and Amazon ECS.
**Note**
On Linux container instances, the agent container mounts top-level directories such as `/lib`, `/lib64`, and `/proc`. This is necessary for ECS features and functionalities such as Amazon EBS volumes, `awsvpc` network mode, Amazon ECS Service Connect, and FireLens for Amazon ECS.
Each Amazon ECS container agent version supports a different feature set and provides bug fixes from previous versions. When possible, we always recommend using the latest version of the Amazon ECS container agent. To update your container agent to the latest version, see [Updating the Amazon ECS container agent](ecs-agent-update.md).
The Amazon ECS container agent contains the `amazon-ecs-pause` image.Amazon ECS uses this image for tasks that use `awsvpc` network mode.
To see which features and enhancements are included with each agent release, see [https://github.com/aws/amazon-ecs-agent/releases](https://github.com/aws/amazon-ecs-agent/releases).
**Important**
The minimum Docker version for reliable metrics is Docker version `v20.10.13` and newer, which is included in Amazon ECS-optimized AMI `20220607` and newer.
Amazon ECS agent versions `1.20.0` and newer have deprecated support for Docker versions older than `18.01.0`.
## Lifecycle
When the Amazon ECS container agent registers an Amazon EC2 instance to your cluster, the Amazon EC2 instance reports its status as `ACTIVE` and its agent connection status as `TRUE`. This container instance can accept run task requests.
If you stop (not terminate) a container instance, the status remains `ACTIVE`, but the agent connection status transitions to `FALSE` within a few minutes. Any tasks that were running on the container instance stop. If you start the container instance again, the container agent reconnects with the Amazon ECS service, and you are able to run tasks on the instance again.
If you change the status of a container instance to `DRAINING`, new tasks are not placed on the container instance. Any service tasks running on the container instance are removed, if possible, so that you can perform system updates. For more information, see [Draining Amazon ECS container instances](container-instance-draining.md).
If you deregister or terminate a container instance, the container instance status changes to `INACTIVE` immediately, and the container instance is no longer reported when you list your container instances. However, you can still describe the container instance for one hour following termination. After one hour, the instance description is no longer available.
You can drain the instances manually, or build an Auto Scaling group lifecycle hook to set the instance status to `DRAINING`. See [Amazon EC2 Auto Scaling lifecycle hooks](https://docs.aws.amazon.com/autoscaling/ec2/userguide/lifecycle-hooks.html) for more information about Auto Scaling lifecycle hooks.
## Docker Support
Amazon ECS supports the last two major versions of Docker published on Amazon Linux. Currently, this includes Docker 20.10.x and Docker 25.x.
The minimum required Docker version for Amazon ECS can be found in the [Amazon ECS Agent specification file](https://github.com/aws/amazon-ecs-agent/blob/dev/packaging/amazon-linux-ami-integrated/ecs-agent.spec#L53) on GitHub.
When using the Amazon ECS-optimized AMI, Docker is pre-installed and configured to work with the Amazon ECS container agent. The AMI includes a Docker version that is tested and supported by Amazon ECS.
**Note**
While Amazon ECS supports multiple Docker versions, we recommend using the Docker version that comes with the Amazon ECS-optimized AMI for the best compatibility and support.
## Amazon ECS-optimized AMI
For more information about the Amazon ECS-optimized AMI, see [Amazon ECS-optimized Linux AMIs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html).
## Additional information
The following pages provide additional information about the changes:
+ [Amazon ECS Agent changelog](https://github.com/aws/amazon-ecs-agent/blob/master/CHANGELOG.md) on GitHub
+ [Amazon Linux 2 release notes](https://docs.aws.amazon.com/AL2/latest/relnotes/relnotes-al2.html).
+ [Docker Engine release notes](https://docs.docker.com/engine/release-notes/27/) in the Docker documentation
+ [NVIDIA Driver Documentation](https://docs.nvidia.com/datacenter/tesla/index.html) in the NVIDIA documentation
# Amazon ECS container agent configuration
**Applies to**: EC2 instances
The Amazon ECS container agent supports a number of configuration options, most of which you set through environment variables.
If your container instance was launched with a Linux variant of the Amazon ECS-optimized AMI, you can set these environment variables in the `/etc/ecs/ecs.config` file and then restart the agent. You can also write these configuration variables to your container instances with Amazon EC2 user data at launch time. For more information, see [Bootstrapping Amazon ECS Linux container instances to pass data](bootstrap_container_instance.md).
If your container instance was launched with a Windows variant of the Amazon ECS-optimized AMI, you can set these environment variables with the PowerShell SetEnvironmentVariable command and then restart the agent. For more information, see [Run commands when you launch an EC2 instance with user data input](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html) in the *Amazon EC2 User Guide* and [Bootstrapping Amazon ECS Windows container instances to pass data](bootstrap_windows_container_instance.md).
If you are manually starting the Amazon ECS container agent (for non Amazon ECS-optimized AMIs), you can use these environment variables in the **docker run** command that you use to start the agent. Use these variables with the syntax `--env=VARIABLE_NAME=VARIABLE_VALUE`. For sensitive information, such as authentication credentials for private repositories, you should store your agent environment variables in a file and pass them all at one time with the `--env-file path_to_env_file` option. You can use the following commands to add the variables.
```
sudo systemctl stop ecs
sudo vi /etc/ecs/ecs.config
# And add the environment variables with VARIABLE_NAME=VARIABLE_VALUE format.
sudo systemctl start ecs
```
## Run the Amazon ECS agent with the host PID namespace
By default, the Amazon ECS agent runs with its own PID namespace. In the following configurations, you can configure the Amazon ECS agent to run with the host PID namespace:
+ SELinux enforcing mode is enabled.
+ Docker's SELinux security policy is set to true.
You can configure this behavior by setting the `ECS_AGENT_PID_NAMESPACE_HOST` environment variable to `true` in your `/etc/ecs/ecs.config` file. When this variable is enabled, `ecs-init` will start the Amazon ECS agent container with the host's PID namespace (`--pid=host`), allowing the agent to bootstrap itself properly in SELinux-enforcing environments. This feature is available in Amazon ECS agent version `1.94.0` and later.
To enable this feature, add the following line to your `/etc/ecs/ecs.config` file:
```
ECS_AGENT_PID_NAMESPACE_HOST=true
```
After making this change, restart the Amazon ECS agent for the change to take effect:
```
sudo systemctl restart ecs
```
The following features will not work SELinux enforcing mode is enabled and the Docker security policy is set to true, even when `ECS_AGENT_PID_NAMESPACE_HOST=true` is set.
+ Amazon ECS Exec
+ Amazon EBS task attach
+ Service Connect
+ FireLens for Amazon ECS
## Available parameters
For information about the available Amazon ECS container agent configuration parameters, see [Amazon ECS Container Agent](https://github.com/aws/amazon-ecs-agent/blob/master/README.md) on GitHub.
# Storing Amazon ECS container instance configuration in Amazon S3
Amazon ECS container agent configuration is controlled with the environment variable. Linux variants of the Amazon ECS-optimized AMI look for these variables in `/etc/ecs/ecs.config` when the container agent starts and configure the agent accordingly. Non-sensative environment variables, such as `ECS_CLUSTER`, can be passed to the container instance at launch through Amazon EC2 user data and written to this file without consequence. However, other sensitive information, such as your AWS credentials or the `ECS_ENGINE_AUTH_DATA` variable, should never be passed to an instance in user data or written to `/etc/ecs/ecs.config` in a way that would allow them to show up in a `.bash_history` file.
Storing configuration information in a private bucket in Amazon S3 and granting read-only access to your container instance IAM role is a secure and convenient way to allow container instance configuration at launch. You can store a copy of your `ecs.config` file in a private bucket. You can then use Amazon EC2 user data to install the AWS CLI and copy your configuration information to `/etc/ecs/ecs.config` when the instance launches.
**To store an `ecs.config` file in Amazon S3**
1. You must grant the container instance role (**ecsInstanceRole**) permissions to have read only access to Amazon S3. You can do this by assigning the **AmazonS3ReadOnlyAccess** to the `ecsInstanceRole` role. For information about how to attach a policy to a role, see [Update permissions for a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-permissions.html) in the *AWS Identity and Access Management User Guide*
1. Create an `ecs.config` file with valid Amazon ECS agent configuration variables using the following format. This example configures private registry authentication. For more information, see [Using non-AWS container images in Amazon ECS](private-auth.md).
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
```
**Note**
For a full list of available Amazon ECS agent configuration variables, see [Amazon ECS Container Agent](https://github.com/aws/amazon-ecs-agent/blob/master/README.md) on GitHub.
1. To store your configuration file, create a private bucket in Amazon S3. For more information, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) in the *Amazon Simple Storage Service User Guide*.
1. Upload the `ecs.config` file to your S3 bucket. For more information, see [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) in the *Amazon Simple Storage Service User Guide*.
**To load an `ecs.config` file from Amazon S3 at launch**
1. Complete the earlier procedures in this section to allow read-only Amazon S3 access to your container instances and store an `ecs.config` file in a private S3 bucket.
1. Launch new container instances and use the following example script in the EC2 User data. The script installs the AWS CLI and copies your configuration file to `/etc/ecs/ecs.config`. For more information, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
```
#!/bin/bash
yum install -y aws-cli
aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config
```
# Installing the Amazon ECS container agent
If you want to register an Amazon EC2 instance with your Amazon ECS cluster and that instance is not using an AMI based on the Amazon ECS-optimized AMI, you can install the Amazon ECS container agent manually using the following procedure. To do this, you can either download the agent from one of the regional Amazon S3 buckets or from Amazon Elastic Container Registry Public. If you download from one of the regional Amazon S3 buckets, you can optionally verify the validity of the container agent file using the PGP signature.
**Note**
The `systemd` units for both Amazon ECS and Docker services have a directive to wait for `cloud-init` to finish before starting both services. The `cloud-init` process is not considered finished until your Amazon EC2 user data has finished running. Therefore, starting Amazon ECS or Docker via Amazon EC2 user data may cause a deadlock. To start the container agent using Amazon EC2 user data you can use `systemctl enable --now --no-block ecs.service`.
## Installing the Amazon ECS container agent on a non-Amazon Linux EC2 instance
To install the Amazon ECS container agent on an Amazon EC2 instance, you can download the agent from one of the regional Amazon S3 buckets and install it.
**Note**
When using a non-Amazon Linux AMI, your Amazon EC2 instance requires `cgroupfs` support for the `cgroup` driver in order for the Amazon ECS agent to support task level resource limits. For more information, see [Amazon ECS agent on GitHub](https://github.com/aws/amazon-ecs-agent).
The latest Amazon ECS container agent files, by Region, for each system architecture are listed below for reference.
| Region | Region name | Amazon ECS init deb files | Amazon ECS init rpm files |
| --- | --- | --- | --- |
| us-east-2 | US East (Ohio) | [Amazon ECS init amd64](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-east-1 | US East (N. Virginia) | [Amazon ECS init amd64](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-west-1 | US West (N. California) | [Amazon ECS init amd64](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-west-2 | US West (Oregon) | [Amazon ECS init amd64](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-east-1 | Asia Pacific (Hong Kong) | [Amazon ECS init amd64](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-northeast-1 | Asia Pacific (Tokyo) | [Amazon ECS init amd64](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-northeast-2 | Asia Pacific (Seoul) | [Amazon ECS init amd64](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-south-1 | Asia Pacific (Mumbai) | [Amazon ECS init amd64](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-southeast-1 | Asia Pacific (Singapore) | [Amazon ECS init amd64](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-southeast-2 | Asia Pacific (Sydney) | [Amazon ECS init amd64](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ca-central-1 | Canada (Central) | [Amazon ECS init amd64](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-central-1 | Europe (Frankfurt) | [Amazon ECS init amd64](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-west-1 | Europe (Ireland) | [Amazon ECS init amd64](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-west-2 | Europe (London) | [Amazon ECS init amd64](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-west-3 | Europe (Paris) | [Amazon ECS init amd64](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| sa-east-1 | South America (São Paulo) | [Amazon ECS init amd64](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.x86_64.rpm) [Amazon ECS init aarch64](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-gov-east-1 | AWS GovCloud (US-East) | [Amazon ECS init amd64](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-gov-west-1 | AWS GovCloud (US-West) | [Amazon ECS init amd64](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
**To install the Amazon ECS container agent on an Amazon EC2 instance using a non-Amazon Linux AMI**
1. Launch an Amazon EC2 instance with an IAM role that allows access to Amazon ECS. For more information, see [Amazon ECS container instance IAM role](instance_IAM_role.md).
1. Connect to your instance.
1. Install the latest version of Docker on your instance.
1. Check your Docker version to verify that your system meets the minimum version requirement. For more information about Docker support, see [Amazon ECS EC2 Container Instances](ecs-agent-versions.md).
```
docker --version
```
1. Download the appropriate Amazon ECS agent file for your operating system and system architecture and install it.
For `deb` architectures:
```
ubuntu:~$ curl -O https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.amd64.deb
ubuntu:~$ sudo dpkg -i amazon-ecs-init-latest.amd64.deb
```
For `rpm` architectures:
```
fedora:~$ curl -O https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.x86_64.rpm
fedora:~$ sudo yum localinstall -y amazon-ecs-init-latest.x86_64.rpm
```
1. Edit the `/lib/systemd/system/ecs.service` file and add the following line at the end of the `[Unit]` section.
```
After=cloud-final.service
```
1. (Optional) To register the instance with a cluster other than the `default` cluster, edit the `/etc/ecs/ecs.config` file and add the following contents. The following example specifies the `MyCluster` cluster.
```
ECS_CLUSTER=MyCluster
```
For more information about these and other agent runtime options, see [Amazon ECS container agent configuration](ecs-agent-config.md).
**Note**
You can optionally store your agent environment variables in Amazon S3 (which can be downloaded to your container instances at launch time using Amazon EC2 user data). This is recommended for sensitive information such as authentication credentials for private repositories. For more information, see [Storing Amazon ECS container instance configuration in Amazon S3](ecs-config-s3.md) and [Using non-AWS container images in Amazon ECS](private-auth.md).
1. Start the `ecs` service.
```
ubuntu:~$ sudo systemctl start ecs
```
## Running the Amazon ECS agent with host network mode
When running the Amazon ECS container agent, `ecs-init` will create the container agent container with the `host` network mode. This is the only supported network mode for the container agent container.
This allows you to block access to the [Amazon EC2 instance metadata service endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) (`http://169.254.169.254`) for the containers started by the container agent. This ensures that containers cannot access IAM role credentials from the container instance profile and enforces that tasks use only the IAM task role credentials. For more information, see [Amazon ECS task IAM role](task-iam-roles.md).
This also makes it so the container agent doesn't contend for connections and network traffic on the `docker0` bridge.
## Amazon ECS container agent log configuration parameters
The Amazon ECS container agent stores logs on your container instances.
For container agent version 1.36.0 and later, by default the logs are located at `/var/log/ecs/ecs-agent.log` on Linux instances and at `C:\ProgramData\Amazon\ECS\log\ecs-agent.log` on Windows instances.
For container agent version 1.35.0 and earlier, by default the logs are located at `/var/log/ecs/ecs-agent.log.timestamp` on Linux instances and at `C:\ProgramData\Amazon\ECS\log\ecs-agent.log.timestamp` on Windows instances.
By default, the agent logs are rotated hourly with a maximum of 24 logs being stored.
The following are the container agent configuration variables that can be used to change the default agent logging behavior. For detailed information about all available configuration parameters, see [Amazon ECS container agent configuration](ecs-agent-config.md) or the [Amazon ECS Agent README](https://github.com/aws/amazon-ecs-agent/blob/master/README.md) on GitHub.
For container agent version 1.36.0 and later, the following is an example log file when the `logfmt` format is used.
```
level=info time=2019-12-12T23:43:29Z msg="Loading configuration" module=agent.go
level=info time=2019-12-12T23:43:29Z msg="Image excluded from cleanup: amazon/amazon-ecs-agent:latest" module=parse.go
level=info time=2019-12-12T23:43:29Z msg="Image excluded from cleanup: amazon/amazon-ecs-pause:0.1.0" module=parse.go
level=info time=2019-12-12T23:43:29Z msg="Amazon ECS agent Version: 1.36.0, Commit: ca640387" module=agent.go
level=info time=2019-12-12T23:43:29Z msg="Creating root ecs cgroup: /ecs" module=init_linux.go
level=info time=2019-12-12T23:43:29Z msg="Creating cgroup /ecs" module=cgroup_controller_linux.go
level=info time=2019-12-12T23:43:29Z msg="Loading state!" module=statemanager.go
level=info time=2019-12-12T23:43:29Z msg="Event stream ContainerChange start listening..." module=eventstream.go
level=info time=2019-12-12T23:43:29Z msg="Restored cluster 'auto-robc'" module=agent.go
level=info time=2019-12-12T23:43:29Z msg="Restored from checkpoint file. I am running as 'arn:aws:ecs:us-west-2:0123456789:container-instance/auto-robc/3330a8a91d15464ea30662d5840164cd' in cluster 'auto-robc'" module=agent.go
```
The following is an example log file when the JSON format is used.
```
{"time": "2019-11-07T22:52:02Z", "level": "info", "msg": "Starting Amazon Elastic Container Service Agent", "module": "engine.go"}
```
# Configuring Amazon ECS container instances for private Docker images
The Amazon ECS container agent can authenticate with private registries, using basic authentication. When you enable private registry authentication, you can use private Docker images in your task definitions. This feature is only supported by tasks using EC2.
Another method of enabling private registry authentication uses AWS Secrets Manager to store your private registry credentials securely and then reference them in your container definition. This allows your tasks to use images from private repositories. This method supports tasks using either EC2 or Fargate. For more information, see [Using non-AWS container images in Amazon ECS](private-auth.md).
The Amazon ECS container agent looks for two environment variables when it launches:
+ `ECS_ENGINE_AUTH_TYPE`, which specifies the type of authentication data that is being sent.
+ `ECS_ENGINE_AUTH_DATA`, which contains the actual authentication credentials.
Linux variants of the Amazon ECS-optimized AMI scan the `/etc/ecs/ecs.config` file for these variables when the container instance launches, and each time the service is started (with the **sudo start ecs** command). AMIs that are not Amazon ECS-optimized should store these environment variables in a file and pass them with the `--env-file path_to_env_file` option to the **docker run** command that starts the container agent.
**Important**
We do not recommend that you inject these authentication environment variables at instance launch with Amazon EC2 user data or pass them with the `--env` option to the **docker run** command. These methods are not appropriate for sensitive data, such as authentication credentials. For information about safely adding authentication credentials to your container instances, see [Storing Amazon ECS container instance configuration in Amazon S3](ecs-config-s3.md).
## Authentication formats
There are two available formats for private registry authentication, `dockercfg` and `docker`.
**dockercfg authentication format**
The `dockercfg` format uses the authentication information stored in the configuration file that is created when you run the **docker login** command. You can create this file by running **docker login** on your local system and entering your registry user name, password, and email address. You can also log in to a container instance and run the command there. Depending on your Docker version, this file is saved as either `~/.dockercfg` or `~/.docker/config.json`.
```
cat ~/.docker/config.json
```
Output:
```
{
"auths": {
"https://index.docker.io/v1/": {
"auth": "zq212MzEXAMPLE7o6T25Dk0i"
}
}
}
```
**Important**
Newer versions of Docker create a configuration file as shown above with an outer `auths` object. The Amazon ECS agent only supports `dockercfg` authentication data that is in the below format, without the `auths` object. If you have the **jq** utility installed, you can extract this data with the following command: **cat \$1/.docker/config.json \$1 jq .auths**
```
cat ~/.docker/config.json | jq .auths
```
Output:
```
{
"https://index.docker.io/v1/": {
"auth": "zq212MzEXAMPLE7o6T25Dk0i",
"email": "email@example.com"
}
}
```
In the above example, the following environment variables should be added to the environment variable file (`/etc/ecs/ecs.config` for the Amazon ECS-optimized AMI) that the Amazon ECS container agent loads at runtime. If you are not using an Amazon ECS-optimized AMI and you are starting the agent manually with **docker run**, specify the environment variable file with the `--env-file path_to_env_file` option when you start the agent.
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
```
You can configure multiple private registries with the following syntax:
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example-01.com"},"repo.example-02.com":{"auth":"fQ172MzEXAMPLEoF7225DU0j","email":"email@example-02.com"}}
```
**docker authentication format**
The `docker` format uses a JSON representation of the registry server that the agent should authenticate with. It also includes the authentication parameters required by that registry (such as user name, password, and the email address for that account). For a Docker Hub account, the JSON representation looks like the following:
```
{
"https://index.docker.io/v1/": {
"username": "my_name",
"password": "my_password",
"email": "email@example.com"
}
}
```
In this example, the following environment variables should be added to the environment variable file (`/etc/ecs/ecs.config` for the Amazon ECS-optimized AMI) that the Amazon ECS container agent loads at runtime. If you are not using an Amazon ECS-optimized AMI, and you are starting the agent manually with **docker run**, specify the environment variable file with the `--env-file path_to_env_file` option when you start the agent.
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}
```
You can configure multiple private registries with the following syntax:
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"username":"my_name","password":"my_password","email":"email@example-01.com"},"repo.example-02.com":{"username":"another_name","password":"another_password","email":"email@example-02.com"}}
```
## Procedure
Use the following procedure to turn on private registries for your container instances.
**To enable private registries in the Amazon ECS-optimized AMI**
1. Log in to your container instance using SSH.
1. Open the `/etc/ecs/ecs.config` file and add the `ECS_ENGINE_AUTH_TYPE` and `ECS_ENGINE_AUTH_DATA` values for your registry and account:
```
sudo vi /etc/ecs/ecs.config
```
This example authenticates a Docker Hub user account:
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}
```
1. Check to see if your agent uses the `ECS_DATADIR` environment variable to save its state:
```
docker inspect ecs-agent | grep ECS_DATADIR
```
Output:
```
"ECS_DATADIR=/data",
```
**Important**
If the previous command does not return the `ECS_DATADIR` environment variable, you must stop any tasks running on this container instance before stopping the agent. Newer agents with the `ECS_DATADIR` environment variable save their state and you can stop and start them while tasks are running without issues. For more information, see [Updating the Amazon ECS container agent](ecs-agent-update.md).
1. Stop the `ecs` service:
```
sudo stop ecs
```
Output:
```
ecs stop/waiting
```
1. Restart the `ecs` service.
+ For the Amazon ECS-optimized Amazon Linux 2 AMI:
```
sudo systemctl restart ecs
```
+ For the Amazon ECS-optimized Amazon Linux AMI:
```
sudo stop ecs && sudo start ecs
```
1. (Optional) You can verify that the agent is running and see some information about your new container instance by querying the agent introspection API operation. For more information, see [Amazon ECS container introspection](ecs-agent-introspection.md).
```
curl http://localhost:51678/v1/metadata
```
# Automatic Amazon ECS task and image cleanup
Each time a task is placed on a container instance, the Amazon ECS container agent checks to see if the images referenced in the task are the most recent of the specified tag in the repository. If not, the default behavior allows the agent to pull the images from their respective repositories. If you frequently update the images in your tasks and services, your container instance storage can quickly fill up with Docker images that you are no longer using and may never use again. For example, you may use a continuous integration and continuous deployment (CI/CD) pipeline.
**Note**
The Amazon ECS agent image pull behavior can be customized using the `ECS_IMAGE_PULL_BEHAVIOR` parameter. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md).
Likewise, containers that belong to stopped tasks can also consume container instance storage with log information, data volumes, and other artifacts. These artifacts are useful for debugging containers that have stopped unexpectedly, but most of this storage can be safely freed up after a period of time.
By default, the Amazon ECS container agent automatically cleans up stopped tasks and Docker images that are not being used by any tasks on your container instances.
**Note**
The automated image cleanup feature requires at least version 1.13.0 of the Amazon ECS container agent. To update your agent to the latest version, see [Updating the Amazon ECS container agent](ecs-agent-update.md).
The following agent configuration variables are available to tune your automated task and image cleanup experience. For more information about how to set these variables on your container instances, see [Amazon ECS container agent configuration](ecs-agent-config.md).
`ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION`
The default time to wait to delete containers for a stopped task. If the value is set to less than 1 second, the value is ignored. By default, this parameter is set to 3 hours, but you can reduce this period to as low as 1 second if you need to for your application.
The image cleanup process cannot delete an image as long as there is a container that references it. After containers are removed, any unreferenced images become candidates for cleanup based on the image cleanup configuration parameters.
`ECS_DISABLE_IMAGE_CLEANUP`
If you set this variable to `true`, then automated image cleanup is turned off on your container instance and no images are automatically removed.
`ECS_IMAGE_CLEANUP_INTERVAL`
This variable specifies how frequently the automated image cleanup process should check for images to delete. The default is every 30 minutes but you can reduce this period to as low as 10 minutes to remove images more frequently.
`ECS_IMAGE_MINIMUM_CLEANUP_AGE`
This variable specifies the minimum amount of time between when an image was pulled and when it may become a candidate for removal. This is used to prevent cleaning up images that have just been pulled. The default is 1 hour.
`ECS_NUM_IMAGES_DELETE_PER_CYCLE`
This variable specifies how many images may be removed during a single cleanup cycle. The default is 5 and the minimum is 1.
When the Amazon ECS container agent is running and automated image cleanup is not turned off, the agent checks for Docker images that are not referenced by running or stopped containers at a frequency determined by the `ECS_IMAGE_CLEANUP_INTERVAL` variable. If unused images are found and they are older than the minimum cleanup time specified by the `ECS_IMAGE_MINIMUM_CLEANUP_AGE` variable, the agent removes up to the maximum number of images that are specified with the `ECS_NUM_IMAGES_DELETE_PER_CYCLE` variable. The least-recently referenced images are deleted first. After the images are removed, the agent waits until the next interval and repeats the process again.