/karpenter

name: karpenter
description: Design, install, debug, review, plan capacity, audit scaling history, migrate from Cluster Autoscaler, and upgrade Karpenter v1.x on EKS. Covers NodePool, EC2NodeClass, NodeClaim, Spot diversity, disruption strategy, Pod Identity/IRSA, interruption queue, private clusters, AMI rotation, and GitOps integration. Use when asked to "set up Karpenter", "debug why nodes aren't provisioning", "review my NodePool", "what would Karpenter provision for this workload", "why did this node terminate", "migrate from CA", or "upgrade Karpenter".
argument-hint: "[generate|debug|review|audit|plan|migrate|upgrade] [description or file path]"
title: "Karpenter Command"
sidebar_label: "karpenter"
custom_edit_url: null

Design, install, debug, review, plan capacity, audit, migrate, and upgrade Karpenter on EKS.

Verify current stable version before installing (Karpenter uses OCI, not a Helm repo):

crane ls public.ecr.aws/karpenter/karpenter | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -5

Pin to the version from that output, e.g.:

helm upgrade --install karpenter oci://public.ecr.aws/karpenter/karpenter --version x.y.z

All guidance targets the `karpenter.sh/v1` API. The v0.x `Provisioner`/`AWSNodeTemplate` API was removed in v1.0 — if you are on v0.x, use `migrate` mode first.

---

Interactive Wizard (fires when no arguments are provided)

When invoked with no arguments, ask before proceeding:

**Q1 — Mode?**

What do you need?
  1. generate — design NodePool and EC2NodeClass from requirements
  2. debug    — diagnose why nodes are not provisioning or pods are stuck Pending
  3. review   — production-readiness review of existing NodePool/EC2NodeClass
  4. audit    — reconstruct scale-out/scale-in history and explain why it happened
  5. plan     — predict what Karpenter would provision for a given workload before deploying
  6. migrate  — move from Cluster Autoscaler to Karpenter
  7. upgrade  — upgrade Karpenter version (including v0.x → v1.x CRD migration)

Enter 1–7 or mode name:

**Q2 — Environment context** (ask after mode, one question at a time):

1. EKS cluster version?  (e.g. 1.29, 1.30, 1.31)
2. Karpenter version currently installed (or target version for fresh install)?
3. Identity method for Karpenter controller?
     a) EKS Pod Identity  (recommended, requires EKS 1.24+)
     b) IRSA              (IAM Roles for Service Accounts)
4. Is this a private cluster (no public API endpoint)?  [yes/no]
5. Do you use Spot instances?  [yes / no / mixed]
6. Are you migrating from Cluster Autoscaler?  [yes/no]

Use the answers to set defaults for every section below. If the user pastes a manifest or error, infer as much as possible and skip questions already answered.

---

Mode: generate

Design a production-ready NodePool and EC2NodeClass from requirements.

**Steps:**

1. Collect (or infer from context):

• Workload profile: general-purpose / compute-optimised / memory-optimised / GPU / Spot-flex
• Instance family preferences (e.g. `m`, `c`, `r`, `g4dn`) and architecture (`amd64`, `arm64`/Graviton, or both)
• AMI family: `AL2023` (default, recommended) | `Bottlerocket` | `Windows2022`
• Environment: **dev/staging** or **production** — this drives the AMI strategy
• Whether scale-to-zero is needed (requires `limits` planning)
• Disruption tolerance: can workloads survive consolidation? Are there PDBs?
• GitOps method: Flux / Argo CD / direct kubectl

2. Generate `EC2NodeClass` with:

• `amiSelectorTerms`: use `alias: al2023@latest` for dev/staging; use a **pinned AMI ID** (`id: ami-xxxx`) for production. Floating `@latest` in production means an untested AMI can land on fleet nodes during any scheduled SSM parameter update. Ask the user which environment this is for before choosing.

> Ask user: "What is your EKS cluster name?" — substitute into `karpenter.sh/discovery: <cluster-name>` before applying.

• `subnetSelectorTerms` and `securityGroupSelectorTerms` using `karpenter.sh/discovery: <cluster-name>` tags
• `instanceProfile` or `role` matching the Karpenter node IAM role
• `blockDeviceMappings` with encrypted EBS and IMDSv2 enforced via `metadataOptions`
• `tags` including at minimum `karpenter.sh/discovery`, `Environment`, and billing tags

3. Generate `NodePool` with:

• `spec.template.spec.requirements` covering at least 3 instance families and both `On-Demand`/`Spot` capacity types (or explicit single type)
• `minValues` on instance family or size requirements to guarantee Spot diversity
• `limits` on CPU and memory — **never omit**, uncapped NodePools can runaway
• `weight` if this is one of multiple NodePools (higher weight = preferred)
• `disruption` block: `consolidationPolicy`, `consolidateAfter`, `budgets`
• `expireAfter` set to `720h` (30 days) unless the user has a reason to extend

4. Generate companion resources:

• IRSA or Pod Identity IAM policy (minimum permissions — see references)
• `PodDisruptionBudget` for stateful workloads that will land on Karpenter nodes
• Flux `Kustomization` dependency or Argo CD `syncWave` annotation if GitOps is in use

5. Show validation:

   kubectl apply --dry-run=server -f ec2nodeclass.yaml
   kubectl apply --dry-run=server -f nodepool.yaml
   kubectl describe nodepool <name>   # check Conditions: Ready=True

Reference: `references/karpenter.md` → NodePool design, EC2NodeClass, IAM

**Rollback:** `kubectl delete nodepool <name> && kubectl delete ec2nodeclass <name>` — Karpenter immediately stops provisioning nodes from these templates. Existing nodes remain until drained by the scheduler or TTL.

---

Mode: debug

Diagnose why pods are stuck Pending or nodes are not provisioning.

**Steps:**

1. Collect evidence first — do not suggest fixes before seeing output:

   # Pending pods and their scheduling failure reason
   kubectl get pods -A --field-selector=status.phase=Pending
   kubectl descr