# 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
```