Build a custom Amazon Linux AMI

Important

Amazon EKS will no longer publish EKS-optimized Amazon Linux 2 (AL2) AMIs after November 26th, 2025. Additionally, Kubernetes version 1.32 is the last version for which Amazon EKS will release AL2 AMIs. From version 1.33 onwards, Amazon EKS will continue to release AL2023 and Bottlerocket based AMIs. For more information, see Guide to EKS AL2 & AL2-Accelerated AMIs transition features.

The Amazon EKS-optimized Amazon Linux (AL) AMIs are built on top of AL2 and AL2023, specifically for use as nodes in Amazon EKS clusters. Amazon EKS provides open-source build scripts in the Amazon EKS AMI Build Specification 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 and nodeadm tool for AL2023 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 and runtime.

Prerequisites

• Install the AWS CLI

• Install HashiCorp Packer v1.9.4+

• Install GNU 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 page.

Prerequisites

Install the required Amazon plugin. 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: * Launch a temporary Amazon EC2 instance. * Install Kubernetes components, drivers, and configurations. * 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