Skip to content

Update

Steps to update an EKS cluster to a new Kubernetes version.

Important: You can only upgrade one minor version at a time (e.g., 1.29 → 1.30). Downgrades are not supported. Once the upgrade starts, it cannot be paused or stopped.

Step 0: Read Changelogs

Step 1: Pre-upgrade checks

Cluster health

Node version skew

Nodes must be on the same minor version as the control plane before upgrading the control plane. Starting from Kubernetes 1.28, kubelet may be up to 3 minor versions older than the kube-apiserver (2 minor versions for ≤1.27).

kubectl version
kubectl get nodes

EKS upgrade insights

Check Amazon EKS upgrade insights in the console (Observability → Upgrade insights tab) or with the CLI:

aws eks list-insights --cluster-name <cluster-name> --region <region>

Insights are refreshed every 24 hours, or you can refresh them manually. Fix all findings before proceeding. Note: it can take up to 30 days for insights to clear after fixing deprecated API usage (rolling 30-day window).

Kubernetes API compatibility

Check for deprecated or removed APIs using tools like:

Infrastructure requirements

Amazon EKS requires up to 5 available IP addresses from the subnets specified at cluster creation:

CLUSTER=<cluster-name>
aws ec2 describe-subnets --subnet-ids \
  $(aws eks describe-cluster --name ${CLUSTER} \
  --query 'cluster.resourcesVpcConfig.subnetIds' \
  --output text) \
  --query 'Subnets[*].[SubnetId,AvailabilityZone,AvailableIpAddressCount]' \
  --output table

Also verify the cluster IAM role is present and has the correct permissions (including KMS key access if secret encryption is enabled).

Add-ons compatibility

The installed add-ons must be compatible with the next release. Check cluster insights for this. Update add-ons to a version compatible with both the current and target Kubernetes versions before upgrading.

EKS add-ons are not automatically upgraded during a control plane upgrade. They can only be upgraded one minor version at a time.

Relevant add-on docs:

Application compatibility

Check critical workloads (ingress controllers, monitoring agents, storage drivers, autoscalers) for compatibility with the target Kubernetes version. Components using the Kubernetes API directly (often in *-system namespaces) are the most likely to be affected.

Step 2: Upgrade the control plane

Trigger the control plane upgrade using one of:

eksctl:

eksctl upgrade cluster --name <cluster-name> --version <version-number> --approve

AWS CLI:

aws eks update-cluster-version --name <cluster-name> \
  --kubernetes-version <version-number> --region <region-code>

# Monitor the update status
aws eks describe-update --name <cluster-name> \
  --region <region-code> --update-id <update-id>

The update takes several minutes. AWS manages the rolling replacement of API server nodes; running workloads are not affected. If checks fail, EKS rolls back automatically.

Step 3: Upgrade the worker nodes

After the control plane is upgraded, update all nodes to the same minor version.

Managed node groups:

aws eks update-nodegroup-version --cluster-name <cluster-name> \
  --nodegroup-name <nodegroup-name> --region <region-code>

Self-managed nodes: Replace nodes with new AMIs for the target version. See: https://docs.aws.amazon.com/eks/latest/userguide/update-workers.html

EKS Auto Mode: No manual data plane upgrade needed — after the control plane upgrade, EKS Auto Mode incrementally updates managed nodes respecting PodDisruptionBudgets.

Fargate: New pods get the updated kubelet automatically. Redeploy existing Fargate pods to update them.

Step 4: Post-upgrade tasks

  • Update Cluster Autoscaler to match the new Kubernetes minor version: https://github.com/kubernetes/autoscaler/releases
  • Update NVIDIA device plugin if the cluster has GPU nodes
  • Update EKS add-ons (VPC CNI, CoreDNS, kube-proxy) to the recommended versions
  • Update kubectl to within one minor version of the control plane

EKS Auto Mode upgrades

With EKS Auto Mode the data plane upgrade is fully automated. After you initiate the control plane upgrade (same as any other cluster), Auto Mode handles the rest:

  • As nodes expire, Auto Mode replaces them with new nodes running the target Kubernetes version.
  • Pod disruption budgets are respected during node replacement.
  • No manual node group update or rollout is needed.

Components managed automatically

The following components are part of the Auto Mode service and do not need manual updates:

  • Amazon VPC CNI
  • CoreDNS
  • kube-proxy
  • AWS Load Balancer Controller
  • Karpenter
  • AWS EBS CSI driver

Your responsibilities

You are still responsible for updating:

  • Apps and workloads deployed to the cluster
  • Self-managed add-ons and controllers
  • Any Amazon EKS Add-ons installed manually

Reference

Version lifecycle

  • Standard support: 14 months after release
  • Extended support: 12 months after end of standard support (additional cost)
  • Clusters running past the 26-month lifecycle (standard + extended) are auto-upgraded by AWS