Skip to main content
Karpenter strongly recommends against using @latest AMI aliases in production environments. A faulty AMI can cause downtime across your cluster. Pin to a specific version and promote new versions through a staging process.
amiSelectorTerms:
  - alias: al2023@v20240807
Understanding how Karpenter assigns AMIs to nodes lets you ensure workloads run successfully on those nodes and continue to run as AMIs are updated over time. This guide explains how AMI selection works, how to control it, and best practices for safely rolling out new AMI versions.

​
How Karpenter assigns AMIs to nodes

When you create an EC2NodeClass, you must specify amiSelectorTerms. These terms determine which AMIs Karpenter can use when launching nodes. Karpenter always selects the newest compatible AMI from those matched by your terms.

​
Static vs dynamic selector terms

Some amiSelectorTerm types always resolve to the same AMI (static), while others may resolve to different AMIs over time (dynamic).
TypeBehaviorExample
idStatic — always resolves to one specific AMIid: ami-052c9ea013e6e3567
name (exact)Static — resolves to the AMI with that exact namename: al2023-ami-2023.3.20240219.0-kernel-6.1-x86_64
alias (versioned)Static per K8s version — resolves to a pinned release matching the cluster control planealias: al2023@v20240807
alias (@latest)Dynamic — resolves to the newest release of that AMI familyalias: al2023@latest
name (wildcard)Dynamic — resolves to whichever AMI matches at launch timename: al2023-ami-*
tagsDynamic — resolves to whichever tagged AMI exists at launch timetags: { env: prod }
When a dynamic term resolves to a new AMI, any node replacement triggered after that point will use the new AMI — potentially without prior testing.

​
AMI families and aliases

Karpenter supports the following well-known AMI families, each with a corresponding alias:
AMI familyAlias prefixNotes
Amazon Linux 2al2Legacy; consider migrating to AL2023
Amazon Linux 2023al2023Recommended default
BottlerocketbottlerocketContainer-optimized, immutable OS
Windows Server 2019windows2019Windows workloads
Windows Server 2022windows2022Windows workloads
Windows Server 2025windows2025Windows workloads
Alias format: <family>@<version> or <family>@latest 
amiSelectorTerms:
  - alias: al2023@v20240807      # Pinned version
  # - alias: al2023@latest       # Latest (not recommended for production)
  # - alias: bottlerocket@v1.20.0
Versioned aliases (e.g. al2023@v20240807) pin the AMI release but still account for the Kubernetes control plane version of your cluster. If you upgrade your EKS cluster’s Kubernetes version, Karpenter will drift nodes to a new AMI that matches both the pinned release version and the new K8s version. By contrast, id and name terms are fully static regardless of K8s version.

​
When node replacement occurs

Whenever a node is replaced, the replacement node uses the newest AMI matched by your amiSelectorTerms. Replacement is triggered by:
  • Expiration — node reaches its configured TTL and is automatically replaced
  • Consolidation — Karpenter finds a cheaper node configuration for the same workloads
  • Drift — the node’s actual state no longer matches the desired state in NodePool or EC2NodeClass
  • Interruption — involuntary disruption (e.g. Spot interruption, EC2 health events)
Of these, Drift is the most relevant to AMI management because it is triggered whenever the AMI selected by your amiSelectorTerms changes — either from a manual update or from a dynamic term resolving to a new release.

​
Controlling AMI replacement

Karpenter gives you several tools to control the risk of rolling out new AMIs:
  • Pin AMIs — ensure only a tested AMI is used in production
  • Test AMIs — validate new releases in lower environments before promoting
  • Use disruption budgets — limit the pace and schedule of node replacements

​
Pinning AMIs

Pinning ensures Karpenter uses only a specific, tested AMI. There are several ways to express a pin:
Pins to a specific AMI release. Karpenter still accounts for the cluster’s K8s version, so the actual AMI ID may change after a Kubernetes upgrade.
amiSelectorTerms:
  - alias: al2023@v20240219
Pinning prevents automatic security patches from reaching your nodes when new AMIs are released. Balance security patch cadence against the risk of deploying untested AMIs.

​
Testing AMIs

The safest approach is to validate new AMI releases in lower environments before promoting to production. Test cluster — use @latest to always run the most recent AMI: 
amiSelectorTerms:
  - alias: al2023@latest     # Always the newest, acceptable in non-production
Production cluster — pin to the version you have validated: 
amiSelectorTerms:
  - alias: al2023@v20240807  # Promoted after testing in staging
When you’re confident a new release works correctly, update the version pin in your production EC2NodeClass. Karpenter will detect the change and drift existing nodes to the new AMI over time.
Combine AMI pinning with disruption budgets when rolling out even a pre-tested AMI to production. Issues sometimes only surface under production-scale traffic and concurrency.

​
Using disruption budgets

Disruption budgets let you control the speed and schedule of node replacements, limiting blast radius if a new AMI causes problems.

​
Node disruption budgets

Set disruption.budgets in your NodePool spec: 
disruption:
  budgets:
    # Limit to 15% of nodes disrupted at any time
    - nodes: 15%

    # Or an absolute cap
    - nodes: "3"

    # Block all disruption on weekends
    - nodes: "0"
      schedule: "0 9 * * sat,sun"
      duration: 24h

    # Block drift-caused disruption outside working hours Mon–Fri
    - nodes: "0"
      schedule: "0 17 * * mon-fri"
      duration: 16h
      reasons:
        - Drifted
Budget options:
  • nodes — maximum nodes to disrupt simultaneously (percentage or absolute count)
  • schedule — cron expression for when this budget is active (uses crontab format)
  • duration — how long the budget remains active after schedule fires
  • reasons — restrict the budget to specific disruption types (Drifted, Expired, Underutilized)

​
Pod disruption budgets

Configure Pod Disruption Budgets for applications running on your cluster. Karpenter respects PDBs during graceful disruption — if replacing a node would violate a PDB, Karpenter will not replace that node. This is especially important during an AMI rollout: if a faulty AMI begins causing application failures, PDBs signal to Karpenter that nodes must stop being replaced, preventing the bad AMI from propagating cluster-wide.

​
The drift mechanism

Drift is Karpenter’s reconciliation loop that detects when a node’s actual state no longer matches the desired state declared in your NodePool or EC2NodeClass. For AMIs specifically:
  1. You update amiSelectorTerms (e.g. change a version pin, or a dynamic term resolves to a new AMI)
  2. Karpenter evaluates existing nodes against the new desired state
  3. Nodes whose AMI no longer matches are marked as drifted
  4. Karpenter replaces drifted nodes subject to your disruption budgets
If you use @latest aliases, Karpenter also polls periodically for new AMI releases. A newly published AMI can trigger drift automatically without any manual change to your configuration.
Unlike Managed Node Groups (MNG), which never automatically upgrade AMIs when launching replacement nodes, Karpenter will use the newest matching AMI whenever a node is replaced. This means dynamic selector terms can introduce a new AMI into your cluster at any time a node is replaced — not just when drift is explicitly triggered.

​
Best practices for production environments

Always pin AMIs in production. Use versioned aliases (al2023@v20240807) or explicit id/name terms. Never use @latest in production.
Use a staged rollout process. Run @latest in non-production clusters to catch issues early, then promote tested versions to production by updating the version pin.
Set disruption budgets before rolling out AMI changes. Limit the percentage of nodes that can be replaced simultaneously and block replacements outside of business hours using schedule.
Configure Pod Disruption Budgets for all critical workloads. This provides an automatic circuit breaker if a new AMI causes application failures during rollout.
Use CI/CD-managed tags for flexible AMI promotion. Tag validated AMIs with your pipeline and use a tags selector term in production. Update the tag in your pipeline to promote without editing the EC2NodeClass manifest.

Build docs developers (and LLMs) love

Get started for freeTalk to us