Skip to main content
Karpenter is a controller that runs in your cluster and is not tied to a specific Kubernetes version. Use your existing upgrade mechanisms to keep Karpenter up to date with bug fixes and new features.
Karpenter v1.0+ dropped support for v0.36 and below. Upgrade to a supported version before proceeding. If you are upgrading from v1beta1 APIs (pre-v1.1), follow the v1 Migration Guide first.

​
Kubernetes and EKS compatibility

Karpenter requires a minimum Kubernetes version depending on the Karpenter release. Use the table below to verify your cluster version is compatible.
Kubernetes1.291.301.311.321.331.341.35
Karpenter>= 0.34>= 0.37>= 1.0.5>= 1.2>= 1.5>= 1.61.9.x
Karpenter follows Semantic Versioning 2.0.0. Breaking changes are only introduced in minor version increments. Check for a version-specific section in this guide every time you upgrade to a new minor version.

​
Release types

TypeDescriptionProduction-safe?
Stable (e.g. 1.9.0)Recommended for all environmentsYes
Release candidate (e.g. 1.9.0-rc.0)Early access for testing before GANo
SnapshotBuilt from every merged commit, available in a private ECR repoNo
Snapshot releases are ephemeral and removed 90 days after publication. Never use snapshot releases in production.

​
CRD upgrades

Karpenter ships Custom Resource Definitions (CRDs) that must be kept in sync with the controller version. Helm does not automatically upgrade CRDs after initial installation. Karpenter publishes CRDs in two ways:
  • Standalone karpenter-crd chart (recommended) — manages CRD lifecycle independently via Helm
  • Bundled in the karpenter chart — installs CRDs only on first install; subsequent upgrades do not update them
Upgrade CRDs before upgrading the controller: 
KARPENTER_NAMESPACE=kube-system

helm upgrade --install karpenter-crd \
  oci://public.ecr.aws/karpenter/karpenter-crd \
  --version x.y.z \
  --namespace "${KARPENTER_NAMESPACE}" \
  --create-namespace
If you see invalid ownership metadata; label validation error: when installing the karpenter-crd chart from an older version, see the Troubleshooting Guide.

​
Upgrade process

1

Review compatibility and breaking changes

Check the compatibility matrix to confirm your Kubernetes version is supported by the target Karpenter version.Read the version-specific sections in Breaking changes by version for every minor version between your current and target release.
2

Back up your current configuration

Save your existing NodePool and EC2NodeClass resources:
kubectl get nodepools -A -o yaml > nodepools-backup.yaml
kubectl get ec2nodeclasses -A -o yaml > ec2nodeclasses-backup.yaml
Document your current Karpenter version:
helm list -n kube-system
3

Validate in a staging environment

Deploy the target version to a staging cluster first. Run tests that cover:
  • Node provisioning (scale up a deployment)
  • Disruption (manually delete nodes, verify replacement)
  • NodePool and EC2NodeClass validation webhooks
  • Controller health (kubectl get pods -n kube-system -l app.kubernetes.io/name=karpenter)
4

Upgrade CRDs

Always upgrade CRDs before upgrading the controller:
helm upgrade --install karpenter-crd \
  oci://public.ecr.aws/karpenter/karpenter-crd \
  --version <TARGET_VERSION> \
  --namespace kube-system
5

Upgrade the Karpenter controller

helm upgrade --install karpenter \
  oci://public.ecr.aws/karpenter/karpenter \
  --version <TARGET_VERSION> \
  --namespace kube-system \
  --reuse-values
Use --reuse-values to carry forward your existing Helm values, or pass an explicit values file with -f values.yaml.
6

Verify the upgrade

Confirm the controller is healthy:
kubectl get pods -n kube-system -l app.kubernetes.io/name=karpenter
kubectl logs -n kube-system -l app.kubernetes.io/name=karpenter --tail=50
Verify node provisioning is working by checking that pending pods are being scheduled and nodes are being created.
Use a CI/CD pipeline (GitHub Actions, ArgoCD, Flux, AWS CodePipeline, or GitLab CI) to automate staging validation and require manual approval before deploying to production. This ensures every upgrade is tested and reviewed before affecting production workloads.

​
Breaking changes by version

This section covers the key changes to be aware of when upgrading to each version. Read every section between your current version and your target version.

​
Upgrading to 1.9.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide to migrate from v1beta1 APIs.
  • The IAM policy in the getting-started CloudFormation template has been split from one policy into five policies. If your IAM role depends on that policy, attach all five new policies. There are no permission changes from v1.8.

​
Upgrading to 1.8.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide.Avoid v1.8.4 — it contains a regression that may prevent scheduling pods with specific TopologySpreadConstraint configurations. See kubernetes-sigs/karpenter#2785.
  • Adds support for Static Capacity. Upgrade your Karpenter CRDs to use this feature.

​
Upgrading to 1.7.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide.
  • Instance profiles are now created with the path /karpenter/{region}/{cluster-name}/{nodeclass-uid}/ instead of /. No action needed for existing profiles; new ones use the new path.
  • The Karpenter controller role now requires the additional IAM permission iam:ListInstanceProfiles.
  • Metric karpenter_pods_pods_drained_total renamed to karpenter_pods_drained_total.
  • Metric reason label liveness on karpenter_nodeclaims_disrupted_total renamed to registration_timeout.
  • Pods with ResourceClaim requests are explicitly ignored. DRA is not currently supported by Karpenter.

​
Upgrading to 1.6.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide.
  • Native ODCR support graduated to beta and is enabled by default. If you were using open ODCRs with earlier Karpenter versions and have not migrated to native ODCR support, review the capacity reservations guide before upgrading.
  • New configuration option MinValuesPolicy: controls how the scheduler treats minValues. Options: Strict (default, existing behavior) or BestEffort.
  • New configuration option DisableDryRun (v1.6.2+): disables dry-run calls during EC2NodeClass validation.

​
Upgrading to 1.5.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide.
No breaking changes.

​
Upgrading to 1.4.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide.
No breaking changes.

​
Upgrading to 1.3.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide.
  • Alpha metric karpenter_ignored_pod_count renamed to karpenter_scheduler_ignored_pod_count.
  • With the ReservedCapacity feature gate, a new karpenter.sh/capacity-type value (reserved) is introduced. Applications that use nodeSelector to explicitly select on-demand and want to use ODCR capacity must update their requirements to use nodeAffinity and include both reserved and on-demand.

​
Upgrading to 1.2.0+

Do not upgrade to v1.1.0+ without first completing the v1 Migration Guide.
  • Metric reason labels on karpenter_voluntary_disruption_queue_failures_total and karpenter_nodeclaims_disrupted_total changed from camelCase to snake_case:
    • Drifted → drifted
    • Empty → empty
    • Expired → expired
    • Underutilized → underutilized
  • nodeclass.termination and nodeclass.status controllers merged into a single nodeclass controller. Update any log queries or metric dashboards that reference the old controller names.

​
Upgrading to 1.1.0+

v1.1.0 drops support for v1beta1 APIs. Do not upgrade without first completing the v1 Migration Guide.
  • v1beta1 compatibility annotations are removed. Complete migration before upgrading.
  • nodeClassRef.group and nodeClassRef.kind are now strictly required on all NodePools and NodeClaims. Set these values before upgrading.
  • Bottlerocket amiFamily now supports instanceStorePolicy: RAID0. This configuration requires Bottlerocket v1.22.0+. Earlier Bottlerocket versions with RAID0 will fail to join the cluster.
  • AWS Neuron accelerator label (karpenter.k8s.aws/instance-accelerator-name) values corrected to trainium, inferentia, inferentia2. Previously all Neuron accelerators returned inferentia.
  • Karpenter now uses eks:eks-cluster-name instead of karpenter.k8s.aws/cluster for launch template tagging.
  • Generic operator metrics deprecated and replaced by resource-specific metrics.

​
Upgrading to 1.0.0+

v1.0.0 introduces v1 APIs and uses conversion webhooks to support existing v1beta1 resources. Do not upgrade without following the v1 Migration Guide.
Refer to the v1 Migration Guide for the full changelog.

Build docs developers (and LLMs) love

Get started for freeTalk to us