amazon-eks-ami: building your own EKS-optimized node AMI with Packer

The problem amazon-eks-ami solves, and who actually needs it

Kubernetes nodes need a boot image that already contains a container runtime, kubelet, the AWS-specific bootstrap wiring and, on some instance families, GPU or networking drivers. Amazon publishes an EKS-optimized AMI that covers the common case, and most clusters never think about it again. The gap opens when you need something the published image does not carry: a kernel module for a security agent, a hardened sysctl set, an internal certificate bundle, or a pinned kubelet build. amazon-eks-ami is the repository that produces the official image, and it is published so you can fork the recipe and produce your own. The README states plainly that this is the same configuration Amazon EKS uses to create the official EKS-optimized AMI. The audience is therefore narrow and specific: platform engineers who already run EKS, who have a compliance or driver requirement that cannot be met with user data scripts at boot time, and who are comfortable owning an image pipeline. If your customization can be expressed as a bootstrap script, you do not need this repository.

How the Packer templates, Makefile and nodeadm fit together

The build is a Packer run against a source AMI in a chosen region. The repository layout separates the pieces: templates/ holds the Packer definitions, Config/ holds the provisioning configuration, build-tools/ and hack/ hold helper scripts, and nodeadm/ holds the Go bootstrap component. The Makefile is described in the README as a small wrapper around invoking Packer directly, which is the honest framing. It exists to resolve the variables Packer needs, not to hide them.

The variable resolution is the part worth reading. The Makefile derives K8S_VERSION_MINOR from kubernetes_version by splitting on dots, and if kubernetes_version is empty it can read it out of a PACKER_VARIABLE_FILE with awk. It then composes AMI_VARIANT from AMI_VARIANT (default amazon-eks), appending -al2023 when os_distro is al2023, -arm64 when arch is arm64, -fips when enable_fips is true, and the accelerator name when enable_accelerator is set. The final ami_name is built from that variant plus the minor version and a date-stamped AMI_VERSION, which defaults to v$(date '+%Y%m%d'). The instance type is not free either: arm64 builds default to m6g.xlarge and everything else to m5.xlarge. Region handling is hardcoded for two special cases, cn-northwest-1 and the us-gov regions, which get different source_ami_owners. That is a useful signal about how the project treats partitions: as explicit branches rather than a general abstraction.

Installing Packer and running your first EKS-optimized AMI build

There is no package to install for amazon-eks-ami itself. You clone the repository and run it locally. The prerequisites section of the README is short and strict: Packer version 1.8.0 or later, and AWS account credentials configured so that Packer can make AWS API calls on your behalf. The README links to the Packer authentication documentation for the credential setup rather than restating it.

Once Packer and credentials are in place, the build is a single make invocation from the repository root. The README gives this exact example, with a Kubernetes version and an OS distribution:

# build an AMI with a specific Kubernetes version
make k8s=1.29 os_distro=al2023

# check default value and options in help doc
make help

The Makefile enforces both variables. If you invoke build, k8s or validate without os_distro, it errors with os_distro is required (e.g., os_distro=al2023); without k8s, it errors with k8s is required (e.g., k8s=1.35). So a bare make build will not quietly produce something unexpected.

Two defaults are worth knowing before you start. The region defaults to us-west-2, so a build you intended for another region will land in the wrong one unless you pass aws_region. And the README warns that the default instance type does not qualify for the AWS free tier, meaning you are charged for instances created during the build. What you should see at the end is an AMI registered in your account under the composed name, for example an amazon-eks-al2023 variant with the Kubernetes minor version and today's date appended.

The AL2 cutoff and other limits you inherit

The most consequential constraint is a date, not a bug. The README carries an important note that Amazon EKS stopped publishing EKS-optimized Amazon Linux 2 (AL2) AMIs on November 26, 2025, and that AL2023 and Bottlerocket based AMIs are available for all supported Kubernetes versions including 1.33 and higher. Anyone arriving with an older tutorial that builds os_distro=al2 is working against a base that is no longer published upstream. The Makefile's own error message now suggests os_distro=al2023, which matches.

A second limitation is structural. This repository builds an image; it does not manage nodes. There is no controller, no reconciliation loop, no upgrade path for running instances. When upstream publishes a new release, your existing nodes do not change. You rebuild, then you roll your node groups yourself. That is the cost of the control you asked for.

Accelerated variants add licence surface. The README lists several third-party components bundled into those images: the NVIDIA Cloud End User License Agreement for NVIDIA accelerated AMIs, open-gpu-kernel-modules under a dual MIT/GPLv2 licence, nvidia-container-toolkit under Apache-2.0, the Neuron Driver under GPLv2, and the Elastic Fabric Adapter Driver under GPLv2. The repository itself is MIT-0, but the image you ship is not MIT-0 alone. Finally, security reports are explicitly routed away from GitHub: the README asks that suspected or confirmed issues go to AWS Security rather than an issue or pull request, so the public tracker is not the place to look for vulnerability discussion.

amazon-eks-ami versus Bottlerocket and managed node groups

The README names Bottlerocket as the alternative base for EKS AMIs, alongside AL2023. The difference in approach is the operating system model, not the build tool. amazon-eks-ami produces a general-purpose Linux image with a package manager, a shell and the nodeadm bootstrap component in the image; you customize it by editing Packer provisioning steps or adding your own. Bottlerocket is a minimal, image-based OS with a different update and configuration model, and it is the better fit when you want the host to be as small and immutable as possible. Choosing between them is a choice about how much host surface you want to own, and the repository does not make that choice for you.

The other alternative is not an AMI at all: a managed node group using the published EKS-optimized AMI. That path gives you the same base image with none of the Packer, credential or rebuild work. The trade-off is that you cannot change what is inside the image. If your requirement is a driver or an agent that must exist before kubelet starts, managed node groups with the stock AMI will not get you there, and that is precisely when this repository becomes the right tool. If your requirement is a configuration file or a DaemonSet, it will not.

Maintenance cadence, release tags and upgrade cost

The release history is dense. Tags v20260923, v20260917 and v20260911 all landed within roughly two weeks of each other, and the last push to main was on 2026-09-24. Each tag corresponds to an AMI release, and the Makefile's AMI_VERSION default of a date stamp mirrors that convention. The practical consequence is that staying current means rebuilding often. If you fork this repository and modify the templates, every upstream release is a potential merge, and the merge is against Packer templates and shell provisioning rather than a versioned library API. There is no compatibility contract that tells you a template change is safe.

On licensing, the repository is MIT-0, which is permissive and does not require attribution. That applies to the code here. It does not extend to the accelerated image contents listed above, which bring their own terms, including GPLv2 components and the NVIDIA EULA. This is a description of what the README says, not legal advice; if you redistribute an accelerated AMI, the terms of the bundled drivers are the ones that matter.

Editorial conclusion

Adopt amazon-eks-ami if you need to bake kernel modules, agents or hardening steps into the node image and you accept owning the rebuild loop, because each upstream release arrives as a new tag such as v20260923 rather than a patch to your image. Do not adopt it if a managed node group with the published EKS-optimized AMI already covers your requirements, or if your team cannot run Packer builds and AMI lifecycle management. Before your first build, verify that Packer is at version 1.8.0 or later, that AWS credentials are configured for the target region, that os_distro=al2023 is the right base now that AL2 publication stopped on November 26, 2025, and that the accelerator licences you would inherit (NVIDIA, Neuron, EFA) are acceptable for your use.

Frequently asked questions

Official sources

1. awslabs/amazon-eks-ami on GitHub
2. License: MIT-0
3. Project website
4. README
5. Releases