A safe Amazon EKS upgrade is a staged change, not a single control-plane command. First verify the target version, deprecated API usage, node and add-on compatibility, disruption budgets, backups, and application tests. Then upgrade one Kubernetes minor version at a time: control plane first, data plane next, followed by EKS add-ons, controllers, and clients. Observe the cluster between stages and keep a tested rollback decision ready.
Amazon EKS now allows an eligible in-place control-plane upgrade to be rolled back to the previous minor version within seven days. That is a useful safety net, but it does not automatically reverse managed node groups, self-managed nodes, or EKS add-ons. Teams still need a deliberate upgrade and rollback runbook.
What you need to know
- Upgrade only one Kubernetes minor version at a time and treat every step as a separate production change.
- Use EKS upgrade insights, API-deprecation checks, workload tests, and a component inventory before touching the control plane.
- Bring managed nodes, add-ons, controllers, and kubectl into a supported version relationship after the control-plane update.
- Test availability with real disruption scenarios; a passing deployment does not prove that pods can drain safely.
- Use the seven-day EKS rollback window as a contingency, not as a substitute for backups, validation, or a recovery plan.
What is the safe order for an Amazon EKS upgrade?
The practical order is readiness review, control plane, worker nodes, EKS add-ons, workload controllers, and client tools. AWS recommends bringing nodes to the same minor version as the existing control plane before advancing the control plane again. After the control-plane update succeeds, update the data plane and the components that depend on the Kubernetes API.
This order matters because the control plane, kubelet, kube-proxy, add-ons, autoscalers, admission webhooks, and command-line clients do not all have the same compatibility rules. A cluster can report ACTIVE while an application, webhook, or controller is still incompatible with the new API behavior.
| Stage | Primary task | Evidence to continue |
|---|---|---|
| 1. Prepare | Review lifecycle, insights, APIs, add-ons, nodes, quotas, backups, and tests | Named owner, approved target, clean or accepted findings |
| 2. Control plane | Upgrade to the next minor version | Update status Successful and API health stable |
| 3. Data plane | Roll managed, self-managed, hybrid, or Fargate workloads as applicable | Nodes Ready and workloads available |
| 4. Components | Update VPC CNI, CoreDNS, kube-proxy, controllers, and clients | Compatibility and functional checks pass |
| 5. Observe | Monitor service indicators and rollback readiness | No unresolved regression or capacity risk |
Continue reading: AWS: update an existing EKS cluster ↗ · EKS architecture explained
Start with the EKS version lifecycle and business deadline
Amazon EKS provides standard support for a Kubernetes minor version for 14 months after that version is released in EKS, followed by 12 months of extended support. A cluster that reaches the end of its 26-month lifecycle is automatically upgraded. Extended support can provide planning time, but it is not a permanent alternative to maintaining an upgrade path.
Record the current control-plane version, node versions, support status, target version, required intermediate versions, and the date by which the change must complete. If a cluster is several releases behind, plan multiple sequential maintenance events. EKS and upstream Kubernetes do not support skipping minor versions for a control-plane upgrade.
Avoid selecting a target only because it is the newest available version. Check application dependencies, EKS add-on compatibility, controller release notes, and organizational change windows. The right target is a supported version that the complete platform can operate on and the team can validate.
Continue reading: AWS: Kubernetes version lifecycle on EKS ↗ · Amazon EKS complete guide
Build a pre-upgrade inventory and test plan
A useful inventory connects every cluster component to an owner, version, source, target, and validation method. Include managed and self-managed node groups, Fargate profiles, EKS add-ons, CSI drivers, ingress controllers, autoscalers, policy engines, service meshes, observability agents, admission webhooks, custom resource definitions, operators, and deployment tooling.
Review Kubernetes release notes and the deprecated API migration guide for every minor version in the path. Search manifests and Helm output, but also check what the API server has actually observed. Static files may miss resources produced by an operator or old API calls made by a controller.
Test the application against the target version before production. Cover startup, scaling, service discovery, ingress, storage attachment, DNS, secrets, scheduled jobs, observability, admission, and failure recovery. Tie each check to a measurable result rather than a broad statement that the environment looks healthy.
- Confirm that production manifests no longer depend on APIs removed in the target release.
- Check IP, EC2, load balancer, and volume quotas for temporary upgrade capacity.
- Verify that PodDisruptionBudgets allow planned node drains while preserving the required replicas.
- Confirm backup coverage for Kubernetes state and persistent application data, then document restoration ownership.
- Freeze unrelated platform changes during the upgrade and observation window.
Continue reading: Kubernetes deprecated API migration guide ↗ · EKS security best practices
Use EKS upgrade insights, but verify beyond them
Amazon EKS cluster insights automatically checks clusters for issues that may affect a Kubernetes version upgrade. Upgrade insights can flag deprecated API usage, component version concerns, and other version-specific conditions. Review ERROR, WARNING, and UNKNOWN findings for the target version, resolve or explicitly accept each one, and refresh the insights after remediation.
Insights refresh automatically every 24 hours and can also be refreshed on demand. Deprecated API findings may reflect a rolling observation window, so a finding can remain visible after the last caller was fixed. Compare the finding, last refresh time, affected resource, and deployment history before deciding that it is stale.
A passing insight is not a complete application test. EKS-managed checks cannot validate every self-managed add-on, business transaction, custom controller, or workload-specific dependency. Treat insights as one readiness gate alongside release review, integration tests, canary evidence, and owner approval.
Continue reading: AWS: EKS cluster insights ↗
Upgrade the control plane one minor version at a time
Before the request, confirm that the cluster is ACTIVE, no other update is running, node versions are understood, and the readiness decision is recorded. EKS replaces API server nodes with nodes running the target version while maintaining a highly available managed control plane. The change still deserves a maintenance window because API clients and workloads can reveal incompatibilities after the update.
Submit the update through the console, AWS CLI, or eksctl. Do not start the next stage until the update reports Successful and the team has checked API responsiveness, system namespaces, admission webhooks, controllers, and critical application paths.
aws eks update-cluster-version \
--name <cluster-name> \
--kubernetes-version <next-minor-version> \
--region <region>
aws eks describe-update \
--name <cluster-name> \
--region <region> \
--update-id <update-id>Continue reading: Amazon EKS definition
Roll the data plane without breaking availability
After the control plane is stable, update managed node groups to the target minor version. Configure a rolling strategy and a maximum unavailable count or percentage that the application can tolerate. Ensure the cluster has enough spare capacity and subnet addresses for replacement nodes before starting.
PodDisruptionBudgets help protect replicated workloads during voluntary disruption, but an overly strict budget can prevent nodes from draining and cause a managed node group update to fail. Do not use a forced update as the first fix. Determine whether the budget, replica count, topology, unhealthy pods, or capacity plan is wrong, then correct the operating condition.
Self-managed and hybrid nodes require their own image and rollout procedure. Existing Fargate pods are not automatically changed by the control-plane upgrade; newly launched pods use a kubelet version aligned with the cluster. Validate every data-plane type present rather than assuming one node-group result covers the whole cluster.
| Check | Why it matters | Example evidence |
|---|---|---|
| Capacity | Replacement nodes need room to launch before old nodes leave | Ready nodes, free IPs, quota headroom |
| Disruption | Drains must preserve required application availability | PDB status, replica health, drain events |
| Scheduling | Taints, affinity, zones, and resources can strand pods | Pending-pod causes and scheduler events |
| Workload health | Ready nodes do not prove the service works | Synthetic transactions and service indicators |
Continue reading: AWS: update a managed node group ↗
Update add-ons, controllers, and clients deliberately
A control-plane upgrade does not automatically update EKS add-ons. Review compatible versions and update Amazon VPC CNI, CoreDNS, and kube-proxy as required. Preserve and test any supported custom configuration instead of assuming a default replacement is safe.
Match Cluster Autoscaler to the cluster's Kubernetes major and minor version. Check ingress controllers, CSI drivers, policy engines, service meshes, metrics components, operators, and admission webhooks against their maintainers' compatibility guidance. A controller that starts successfully can still use a removed API or mishandle a new field.
Keep kubectl within one minor version of the API server. Kubernetes permits kubelet and kube-proxy to be older within defined limits, but routinely leaving components at maximum skew creates upgrade debt. AWS recommends aligning nodes with the control plane as a best practice before the next control-plane advance.
Continue reading: Kubernetes version skew policy ↗ · Amazon ECS vs EKS
Understand the seven-day EKS rollback window
For an eligible cluster upgraded in place, Amazon EKS can roll the control plane back to the previous minor version within seven days of the upgrade completing. The rollback preserves etcd data, workloads, services, and persistent volumes. Only one minor version can be reversed, and the previous version must remain supported under the applicable EKS policy.
The rollback is not a full environment rewind. EKS add-ons remain at their current versions. Managed node groups, self-managed nodes, and hybrid nodes must be made compatible with the previous control-plane version; Auto Mode handles its worker-node rollback automatically. Fargate also requires special attention because existing pods may carry a kubelet version that is too new for the rolled-back control plane.
Review rollback readiness insights before acting. ERROR or UNKNOWN findings block rollback unless a force option is used, while some prerequisites cannot be bypassed. Decide in advance who can authorize rollback, which service indicators trigger it, and how much of the seven-day window is reserved for validation rather than discussion.
| Area | Rolled back automatically? | Team responsibility |
|---|---|---|
| EKS control plane | Yes, when eligible | Initiate, monitor, and validate |
| EKS Auto Mode nodes | Yes | Validate disruption settings and workloads |
| Managed or self-managed nodes | No | Return nodes to a compatible version first |
| EKS and self-managed add-ons | No | Check and change versions separately |
| Application data and cluster state | Preserved, not rewound | Use application backups for data recovery needs |
Continue reading: AWS: roll back an EKS cluster version ↗
A production runbook for the change window
A runbook should be short enough to use under pressure and specific enough that a second operator can verify each gate. Record timestamps, commands or console actions, update IDs, findings, owners, and the result of each service check. Stop when evidence is unclear; do not continue merely because the maintenance window is closing.
Before the window
Approve the target and intermediate versions, resolve upgrade insights, complete application tests, confirm backups, check temporary capacity, communicate the change, freeze unrelated work, and capture a baseline of service and cluster indicators.
During the window
Upgrade the control plane and wait for Successful status. Run API and application checks. Roll one node group or a small workload cohort first, observe it, and then continue. Update add-ons and controllers in the documented order, validating after each material change.
After the window
Confirm node and component versions, review events and error rates, test scaling and disruption, refresh cluster insights, verify backups and monitoring, and record the rollback deadline. Keep enhanced observation through the agreed period before closing the change.
- Stop if the API is unstable, critical admission fails, capacity is insufficient, or service indicators breach the agreed threshold.
- Do not advance another minor version until nodes, add-ons, controllers, and clients are ready for the next step.
- Close the change only after the application owner—not only the platform dashboard—confirms expected behavior.
Frequently asked questions
Can Amazon EKS skip Kubernetes minor versions during an upgrade?
No. Upgrade the EKS control plane one minor version at a time. If a cluster is several versions behind, plan and validate each intermediate version separately.
Does an EKS control-plane upgrade update worker nodes and add-ons?
No. After the control-plane update, you must update or replace the applicable worker nodes and separately manage EKS add-ons, controllers, and client tools. EKS Auto Mode manages more of the data-plane lifecycle, but the workloads still require validation.
Can an EKS Kubernetes upgrade be rolled back?
An eligible in-place upgrade can be rolled back to the previous minor version within seven days. The rollback covers the control plane and, for Auto Mode, its nodes. Other nodes and add-ons require separate compatibility work.
Do passing EKS upgrade insights guarantee a safe upgrade?
No. Upgrade insights identify known cluster conditions, but they do not test every application path, self-managed component, controller, or business transaction. Use them with release review, integration tests, canaries, monitoring, and accountable approval.
Sources and further reading
- AWS: Update an existing cluster to a new Kubernetes version ↗
- AWS: Understand the Kubernetes version lifecycle on EKS ↗
- AWS: Prepare for upgrades with EKS cluster insights ↗
- AWS: Roll back a cluster to a previous Kubernetes version ↗
- Kubernetes: Version skew policy ↗
- Kubernetes: Deprecated API migration guide ↗