Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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.

Build a custom EKS-optimized Amazon Linux AMI

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 Amazon 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 required Amazon plugin.

packer plugins install github.com/hashicorp/amazon

Verify that Packer is installed.

packer --version

Clone or fork the official Amazon EKS AMI repository.

git clone https://github.com/awslabs/amazon-eks-ami.git
cd amazon-eks-ami

To view default values and additional options, run the following command. To learn more about the configurations available to customize your AMI, see the template variables on the Amazon Linux 2023 page.

make help

Create a custom AMI

The following are example commands for various custom AMIs.

EKS NVIDIA AL2 AMI

make k8s=1.32 os_distro=al2 \
  enable_accelerator=nvidia \
  nvidia_driver_major_version=580 \
  enable_efa=true

EKS NVIDIA AL2023 AMI

make k8s=1.36 os_distro=al2023 \
  enable_accelerator=nvidia \
  nvidia_driver_major_version=580 \
  enable_efa=true

EKS NVIDIA AL2023 AMI with NVIDIA driver version 595

make k8s=1.36 os_distro=al2023 \
  enable_accelerator=nvidia \
  nvidia_driver_major_version=595 \
  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:

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