**Help improve this page**
To contribute to this user guide, choose the **Edit this page on GitHub** link that is located in the right pane of every page.
# Create nodes with optimized Amazon Linux AMIs
Amazon Elastic Kubernetes Service (Amazon EKS) provides specialized Amazon Machine Images (AMIs) optimized for running Kubernetes worker nodes. These EKS-optimized Amazon Linux (AL) AMIs are pre-configured with essential components—such as `kubelet`, the AWS IAM Authenticator, and `containerd`—to ensure seamless integration and security within your clusters. This guide details the available AMI versions and outlines specialized options for accelerated computing and Arm-based architectures.
## Considerations
+ You can track security or privacy events for Amazon Linux at the [Amazon Linux security center](https://alas.aws.amazon.com/) by choosing the tab for your desired version. You can also subscribe to the applicable RSS feed. Security and privacy events include an overview of the issue, what packages are affected, and how to update your instances to correct the issue.
+ Before deploying an accelerated or Arm AMI, review the information in [Amazon EKS-optimized accelerated Amazon Linux AMIs](#gpu-ami) and [Amazon EKS-optimized Arm Amazon Linux AMIs](#arm-ami).
+ Amazon EC2 `P2` instances aren’t supported on Amazon EKS because they require `NVIDIA` driver version 470 or earlier.
+ Any newly created managed node groups in clusters on version `1.30` or newer will automatically default to using AL2023 as the node operating system.
## Amazon EKS-optimized accelerated Amazon Linux AMIs
Amazon EKS-optimized accelerated Amazon Linux (AL) AMIs are built on top of the standard EKS-optimized Amazon Linux AMIs. They are configured to serve as optional images for Amazon EKS nodes to support GPU, [Inferentia](https://aws.amazon.com/machine-learning/inferentia/), and [Trainium](https://aws.amazon.com/machine-learning/trainium/) based workloads.
For more information, see [Use EKS-optimized accelerated AMIs for GPU instances](ml-eks-optimized-ami.md).
## Amazon EKS-optimized Arm Amazon Linux AMIs
Arm instances deliver significant cost savings for scale-out and Arm-based applications such as web servers, containerized microservices, caching fleets, and distributed data stores. When adding Arm nodes to your cluster, review the following considerations.
+ If your cluster was deployed before August 17, 2020, you must do a one-time upgrade of critical cluster add-on manifests. This is so that Kubernetes can pull the correct image for each hardware architecture in use in your cluster. For more information about updating cluster add-ons, see [Step 1: Prepare for upgrade](update-cluster.md#update-existing-cluster). If you deployed your cluster on or after August 17, 2020, then your CoreDNS, `kube-proxy`, and Amazon VPC CNI plugin for Kubernetes add-ons are already multi-architecture capable.
+ Applications deployed to Arm nodes must be compiled for Arm.
+ If you have DaemonSets that are deployed in an existing cluster, or you want to deploy them to a new cluster that you also want to deploy Arm nodes in, then verify that your DaemonSet can run on all hardware architectures in your cluster.
+ You can run Arm node groups and x86 node groups in the same cluster. If you do, consider deploying multi-architecture container images to a container repository such as Amazon Elastic Container Registry and then adding node selectors to your manifests so that Kubernetes knows what hardware architecture a Pod can be deployed to. For more information, see [Pushing a multi-architecture image](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-multi-architecture-image.html) in the *Amazon ECR User Guide* and the [Introducing multi-architecture container images for Amazon ECR](https://aws.amazon.com/blogs/containers/introducing-multi-architecture-container-images-for-amazon-ecr) blog post.
## More information
For more information about using Amazon EKS-optimized Amazon Linux AMIs, see the following sections:
+ To use Amazon Linux with managed node groups, see [Simplify node lifecycle with managed node groups](managed-node-groups.md).
+ To launch self-managed Amazon Linux nodes, see [Retrieve recommended Amazon Linux AMI IDs](retrieve-ami-id.md).
+ For version information, see [Retrieve Amazon Linux AMI version information](eks-linux-ami-versions.md).
+ To retrieve the latest IDs of the Amazon EKS-optimized Amazon Linux AMIs, see [Retrieve recommended Amazon Linux AMI IDs](retrieve-ami-id.md).
+ For open-source scripts that are used to build the Amazon EKS-optimized AMIs, see [Build a custom EKS-optimized Amazon Linux AMI](eks-ami-build-scripts.md).
# Upgrade from Amazon Linux 2 to Amazon Linux 2023
**Warning**
Amazon EKS stopped publishing EKS-optimized Amazon Linux 2 (AL2) AMIs on November 26, 2025. AL2023 and Bottlerocket based AMIs for Amazon EKS are available for all supported Kubernetes versions including 1.33 and higher.
AL2023 is a Linux-based operating system designed to provide a secure, stable, and high-performance environment for your cloud applications. It’s the next generation of Amazon Linux from Amazon Web Services and is available across all supported Amazon EKS versions.
AL2023 offers several improvements over AL2. For a full comparison, see [Comparing AL2 and Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) in the *Amazon Linux 2023 User Guide*. Several packages have been added, upgraded, and removed from AL2. It’s highly recommended to test your applications with AL2023 before upgrading. For a list of all package changes in AL2023, see [Package changes in Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/release-notes/compare-packages.html) in the *Amazon Linux 2023 Release Notes*.
In addition to these changes, you should be aware of the following:
+ AL2023 introduces a new node initialization process `nodeadm` that uses a YAML configuration schema. If you’re using self-managed node groups or an AMI with a launch template, you’ll now need to provide additional cluster metadata explicitly when creating a new node group. An [example](https://awslabs.github.io/amazon-eks-ami/nodeadm/) of the minimum required parameters is as follows, where `apiServerEndpoint`, `certificateAuthority`, and service `cidr` are now required:
```
---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
cluster:
name: my-cluster
apiServerEndpoint: https://example.com
certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
cidr: 10.100.0.0/16
```
In AL2, the metadata from these parameters was discovered from the Amazon EKS `DescribeCluster` API call. With AL2023, this behavior has changed since the additional API call risks throttling during large node scale ups. This change doesn’t affect you if you’re using managed node groups without a launch template or if you’re using Karpenter. For more information on `certificateAuthority` and service `cidr`, see [https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeCluster.html](https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeCluster.html) in the *Amazon EKS API Reference*.
+ For AL2023, `nodeadm` also changes the format to apply parameters to the `kubelet` for each node using [https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec](https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec). In AL2, this was done with the `--kubelet-extra-args` parameter. This is commonly used to add labels and taints to nodes. An example below shows applying `maxPods` and `--node-labels` to the node.
```
---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
cluster:
name: test-cluster
apiServerEndpoint: https://example.com
certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
cidr: 10.100.0.0/16
kubelet:
config:
maxPods: 110
flags:
- --node-labels=karpenter.sh/capacity-type=on-demand,karpenter.sh/nodepool=test
```
+ Amazon VPC CNI version `1.16.2` or greater is required for AL2023.
+ AL2023 requires `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) and [Get the full benefits of IMDSv2 and disable IMDSv1 across your AWS infrastructure](https://aws.amazon.com/blogs/security/get-the-full-benefits-of-imdsv2-and-disable-imdsv1-across-your-aws-infrastructure). If you would like to use `IMDSv1`, you can still do so by manually overriding the settings using instance metadata option launch properties.
**Note**
For `IMDSv2` with AL2023, the default hop count for managed node groups can vary:
When not using a launch template, the default is set to `1`. This means that containers won’t have access to the node’s credentials using IMDS. If you require container access to the node’s credentials, you can still do so by using a [custom Amazon EC2 launch template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html).
When using a custom AMI in a launch template, the default `HttpPutResponseHopLimit` is set to `2`. You can manually override the `HttpPutResponseHopLimit` in the launch template.
Alternatively, you can use [Amazon EKS Pod Identity](pod-identities.md) to provide credentials instead of `IMDSv2`.
+ AL2023 features the next generation of unified control group hierarchy (`cgroupv2`). `cgroupv2` is used to implement a container runtime, and by `systemd`. While AL2023 still includes code that can make the system run using `cgroupv1`, this isn’t a recommended or supported configuration. This configuration will be completely removed in a future major release of Amazon Linux.
+ `eksctl` version `0.176.0` or greater is required for `eksctl` to support AL2023.
For previously existing managed node groups, you can either perform an in-place upgrade or a blue/green upgrade depending on how you’re using a launch template:
+ If you’re using a custom AMI with a managed node group, you can perform an in-place upgrade by swapping the AMI ID in the launch template. You should ensure that your applications and any user data transfer over to AL2023 first before performing this upgrade strategy.
+ If you’re using managed node groups with either the standard launch template or with a custom launch template that doesn’t specify the AMI ID, you’re required to upgrade using a blue/green strategy. A blue/green upgrade is typically more complex and involves creating an entirely new node group where you would specify AL2023 as the AMI type. The new node group will need to then be carefully configured to ensure that all custom data from the AL2 node group is compatible with the new OS. Once the new node group has been tested and validated with your applications, Pods can be migrated from the old node group to the new node group. Once the migration is completed, you can delete the old node group.
If you’re using Karpenter and want to use AL2023, you’ll need to modify the `EC2NodeClass` `amiFamily` field with AL2023. By default, Drift is enabled in Karpenter. This means that once the `amiFamily` field has been changed, Karpenter will automatically update your worker nodes to the latest AMI when available.
## Additional Information About nodeadm
When utilizing an EKS-optimized Amazon Linux 2023 AMI or building a Custom EKS Amazon Linux 2023 AMI via the Packer scripts provided in the official amazon-eks-ami GitHub repository, you should avoid explicitly running nodeadm init within EC2 User Data or as part of your custom AMI.
If you want to generate dynamic NodeConfig in your user-data, you can write that configuration to a drop-in yaml or json file in `/etc/eks/nodeadm.d`. These configuration files will be merged and applied to your node when nodeadm init is automatically started later in the boot process. For example:
```
cat > /etc/eks/nodeadm.d/additional-node-labels.yaml << EOF
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
kubelet:
flags:
- --node-labels=foo=bar
EOF
```
The EKS-optimized Amazon Linux 2023 AMIs automatically execute nodeadm init in two phases through separate systemd services: nodeadm-config runs before user data execution, while nodeadm-run executes afterward. The nodeadm-config service establishes baseline configurations for containerd and kubelet before user data runs. The nodeadm-run service runs select system daemons and completes any final configurations following user data execution. If the nodeadm init command is run an additional time, via user data or a custom AMI, it may break assumptions about execution ordering, leading to unexpected outcomes including misconfigured ENIs.
# Retrieve Amazon Linux AMI version information
Amazon EKS optimized Amazon Linux AMIs are versioned by Kubernetes version and the release date of the AMI in the following format:
```
k8s_major_version.k8s_minor_version.k8s_patch_version-release_date
```
Each AMI release includes various versions of [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/), the Linux kernel, and [containerd](https://containerd.io/). The accelerated AMIs also include various versions of the NVIDIA driver. You can find this version information in the [Changelog](https://github.com/awslabs/amazon-eks-ami/blob/main/CHANGELOG.md) on GitHub.
# Retrieve recommended Amazon Linux AMI IDs
When deploying nodes, you can specify an ID for a pre-built Amazon EKS optimized Amazon Machine Image (AMI). To retrieve an AMI ID that fits your desired configuration, query the AWS Systems Manager Parameter Store API. Using this API eliminates the need to manually look up Amazon EKS optimized AMI IDs. For more information, see [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html). The [IAM principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#iam-term-principal) that you use must have the `ssm:GetParameter` IAM permission to retrieve the Amazon EKS optimized AMI metadata.
You can retrieve the image ID of the latest recommended Amazon EKS optimized Amazon Linux AMI with the following command, which uses the sub-parameter `image_id`. Make the following modifications to the command as needed and then run the modified command:
+ Replace `` with an [Amazon EKS supported version](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html).
+ Replace *ami-type* with one of the following options. For information about the types of Amazon EC2 instances, see [Amazon EC2 instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html).
+ Use *amazon-linux-2023/x86\$164/standard* for Amazon Linux 2023 (AL2023) `x86` based instances.
+ Use *amazon-linux-2023/arm64/standard* for AL2023 ARM instances, such as [AWS Graviton](https://aws.amazon.com/ec2/graviton/) based instances.
+ Use *amazon-linux-2023/x86\$164/nvidia* for the latest approved AL2023 NVIDIA `x86` based instances.
+ Use *amazon-linux-2023/arm64/nvidia* for the latest approved AL2023 NVIDIA `arm64` based instances.
+ Use *amazon-linux-2023/x86\$164/neuron* for the latest AL2023 [AWS Neuron](https://aws.amazon.com/machine-learning/neuron/) instances.
+ Replace `` with an [Amazon EKS supported AWS Region](https://docs.aws.amazon.com/general/latest/gr/eks.html) for which you want the AMI ID.
```
aws ssm get-parameter --name /aws/service/eks/optimized-ami///recommended/image_id \
--region --query "Parameter.Value" --output text
```
Here’s an example command after placeholder replacements have been made.
```
aws ssm get-parameter --name /aws/service/eks/optimized-ami/1.31/amazon-linux-2023/x86_64/standard/recommended/image_id \
--region us-west-2 --query "Parameter.Value" --output text
```
An example output is as follows.
```
ami-1234567890abcdef0
```
# Build a custom EKS-optimized Amazon Linux AMI
**Warning**
Amazon EKS stopped publishing EKS-optimized Amazon Linux 2 (AL2) AMIs on November 26, 2025. AL2023 and Bottlerocket based AMIs for Amazon EKS are available for all supported Kubernetes versions including 1.33 and higher.
Amazon EKS provides open-source build scripts in the [Amazon EKS AMI Build Specification](https://github.com/awslabs/amazon-eks-ami) repository that you can use to view the configurations for `kubelet`, the runtime, the AWS IAM Authenticator for Kubernetes, and build your own AL-based AMI from scratch.
This repository contains the specialized [bootstrap script for AL2](https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh) and [nodeadm tool for AL2023](https://awslabs.github.io/amazon-eks-ami/nodeadm/) that runs at boot time. These scripts configure your instance’s certificate data, control plane endpoint, cluster name, and more. The scripts are considered the source of truth for Amazon EKS-optimized AMI builds, so you can follow the GitHub repository to monitor changes to our AMIs.
When building custom AMIs with the EKS-optimized AMIs as the base, it is not recommended or supported to run an operating system upgrade (ie. `dnf upgrade`) or upgrade any of the Kubernetes or GPU packages that are included in the EKS-optimized AMIs, as this risks breaking component compatibility. If you do upgrade the operating system or packages that are included in the EKS-optimized AMIs, it is recommended to thoroughly test in a development or staging environment before deploying to production.
When building custom AMIs for GPU instances, it is recommended to build separate custom AMIs for each instance type generation and family that you will run. The EKS-optimized accelerated AMIs selectively install drivers and packages at runtime based on the underlying instance type generation and family. For more information, see the EKS AMI scripts for [installation](https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2023/provisioners/install-nvidia-driver.sh) and [runtime](https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2023/runtime/gpu/nvidia-kmod-load.sh).
## Prerequisites
+ [Install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
+ [Install HashiCorp Packer v1.9.4\$1](https://developer.hashicorp.com/packer/downloads)
+ [Install GNU Make](https://www.gnu.org/software/make/)
## Quickstart
This quickstart shows you the commands to create a custom AMI in your AWS account. To learn more about the configurations available to customize your AMI, see the template variables on the [Amazon Linux 2023](https://awslabs.github.io/amazon-eks-ami/usage/al2023/) page.
### Prerequisites
Install the required [Amazon plugin](https://developer.hashicorp.com/packer/integrations/hashicorp/amazon). For example:
```
packer plugins install github.com/hashicorp/amazon
```
### Step 1. Setup your environment
Clone or fork the official Amazon EKS AMI repository. For example:
```
git clone https://github.com/awslabs/amazon-eks-ami.git
cd amazon-eks-ami
```
Verify that Packer is installed:
```
packer --version
```
### Step 2. Create a custom AMI
The following are example commands for various custom AMIs.
**Basic NVIDIA AL2 AMI:**
```
make k8s=1.31 os_distro=al2 \
enable_accelerator=nvidia \
nvidia_driver_major_version=560 \
enable_efa=true
```
**Basic NVIDIA AL2023 AMI:**
```
make k8s=1.31 os_distro=al2023 \
enable_accelerator=nvidia \
nvidia_driver_major_version=560 \
enable_efa=true
```
**STIG-Compliant Neuron AL2023 AMI:**
```
make k8s=1.31 os_distro=al2023 \
enable_accelerator=neuron \
enable_fips=true \
source_ami_id=ami-0abcd1234efgh5678 \
kms_key_id=alias/aws-stig
```
After you run these commands, Packer will do the following: \$1 Launch a temporary Amazon EC2 instance. \$1 Install Kubernetes components, drivers, and configurations. \$1 Create the AMI in your AWS account.
The expected output should look like this:
```
==> Wait completed after 8 minutes 42 seconds
==> Builds finished. The artifacts of successful builds are:
--> amazon-ebs: AMIs were created:
us-west-2: ami-0e139a4b1a7a9a3e9
--> amazon-ebs: AMIs were created:
us-west-2: ami-0e139a4b1a7a9a3e9
--> amazon-ebs: AMIs were created:
us-west-2: ami-0e139a4b1a7a9a3e9
```
### Step 3. View default values
To view default values and additional options, run the following command:
```
make help
```