EKS Upgrades: A Reversibility-First Reference

Scope

This guide focuses on EKS's approach to Kubernetes control plane upgrades using three key capabilities: Extended Support, Upgrade Insights, and Version Rollback. You'll learn how to make version changes routine rather than high-stakes events.

What's covered:

• Version lifecycle planning with Extended Support (26-month windows)
• Pre-upgrade analysis using Upgrade Insights
• Rollback mechanics and decision criteria
• Integration with existing change management

What's not covered:

• Node group upgrade strategies
• Application-level compatibility testing
• Multi-cluster upgrade orchestration

Key Concepts and Definitions

Extended Support: EKS supports each Kubernetes version for 26 months instead of the standard 14 months. This gives you more time between major version updates and reduces the frequency of forced upgrades.

Upgrade Insights: This automated analysis scans your cluster configuration to identify compatibility issues before an upgrade. It highlights deprecated APIs, resource conflicts, and version-specific breaking changes.

Version Rollback: You can revert a control plane upgrade without rebuilding the cluster. Available since July 2026, this isn't for disaster recovery but for managing unexpected compatibility issues.

Control Plane vs. Data Plane: The control plane (API server, scheduler, controller manager) runs Kubernetes itself. The data plane (worker nodes) runs your workloads. Rollback applies to the control plane only.

Requirements Breakdown

Extended Support Windows

Standard support: 14 months from release
Extended support: Additional 12 months (26 months total)

Timeline example:

• Kubernetes 1.28 released: August 2023
• Standard support ends: October 2024
• Extended support ends: October 2025

Extended Support costs extra, but it buys you time to:

• Batch multiple minor version upgrades
• Align upgrades with application release cycles
• Test thoroughly in non-production environments

Upgrade Insights Requirements

Runs automatically when you initiate an upgrade through the EKS console or API. It's part of the upgrade workflow.

What it checks:

• Deprecated API usage (e.g., batch/v1beta1 CronJobs in 1.25+)
• Resource quota conflicts
• Admission webhook compatibility
• Custom resource definition (CRD) version requirements

Output format: JSON report with severity levels (critical, warning, info) and remediation steps.

Version Rollback Mechanics

Rollback window: Available immediately after upgrade completion. It stays open until you perform another upgrade or explicitly close it.

Supported rollback paths:

• 1.29 → 1.28 (one minor version)
• Not supported: 1.30 → 1.28 (multi-version jumps)

State preservation: ConfigMaps, Secrets, and RBAC policies created during the new version persist after rollback. Pods running on the control plane restart.

Implementation Guidance

Phase 1: Pre-Upgrade Analysis

1. Run Upgrade Insights two weeks before your planned upgrade window

   aws eks describe-update \
     --name your-cluster \
     --update-id upgrade-id
   

   Review the insights section for critical findings.

2. Categorize findings by remediation timeline

   • Immediate blockers: Deprecated APIs in active use
   • Pre-upgrade fixes: Webhook timeouts, quota adjustments
   • Post-upgrade monitoring: Performance regressions, new API behavior

3. Test in a non-production cluster first

   Create a cluster snapshot or use a staging environment with identical workload patterns. Run the upgrade there and monitor for 48 hours before touching production.

Phase 2: Upgrade Execution

1. Schedule during low-traffic windows

   Even though rollback exists, minimize impact. The control plane restarts during upgrade, causing brief API unavailability (typically 30-90 seconds).

2. Enable detailed CloudWatch logging

   {
     "clusterLogging": {
       "enabledTypes": [
         {"type": "api"},
         {"type": "audit"},
         {"type": "controllerManager"}
       ]
     }
   }
   

3. Document your rollback criteria before upgrading

   Example criteria:

   • API error rate exceeds 2% for 5 minutes
   • Critical workload pods fail to schedule
   • Authentication/authorization failures in production namespaces

Phase 3: Post-Upgrade Validation

Monitor these metrics for 4 hours:

• API server request latency (p95, p99)
• Pod scheduling success rate
• Persistent volume claim binding time
• Custom controller reconciliation loops

If you hit rollback criteria, execute within the first 24 hours. After that, you're committed to forward fixes.

Phase 4: Rollback Decision

Salesforce's experience shows the practical use of Version Rollback to handle unexpected compatibility issues, then re-plan their upgrade with additional testing.

Rollback command:

aws eks update-cluster-version \
  --name your-cluster \
  --kubernetes-version 1.28 \
  --rollback

Post-rollback actions:

• Review logs for root cause
• Update Upgrade Insights remediation plan
• Schedule retry with fixes applied

Common Pitfalls

Treating rollback as a replacement for testing: Rollback is a safety net, not a testing strategy. You still need staging environments and canary deployments.

Ignoring node version skew: Your worker nodes can run one minor version behind the control plane. If you rollback from 1.29 to 1.28 but your nodes are still on 1.28, you're fine. If nodes are on 1.29, you've created an unsupported configuration.

Delaying Extended Support decisions: You can't retroactively add Extended Support to a version nearing end-of-life. Decide at least 3 months before standard support expires.

Over-relying on automated insights: Upgrade Insights catches API deprecations and configuration conflicts. It doesn't catch application-level bugs, performance regressions, or third-party operator incompatibilities.

Quick Reference Table

Feature	Timeline	Use Case	Limitation
Extended Support	26 months total	Delay upgrades for testing/planning	Costs extra; not indefinite
Upgrade Insights	Pre-upgrade scan	Identify breaking changes	Doesn't test runtime behavior
Version Rollback	Immediate post-upgrade	Revert unexpected issues	One minor version only
Standard Support	14 months	Normal upgrade cadence	Forces upgrades or Extended Support decision

Upgrade frequency recommendation: Every 6-9 months during standard support windows. This keeps you within one version of latest, giving you maximum rollback flexibility.

Rollback testing cadence: Quarterly in non-production. Verify the rollback path works before you need it in anger.

Kubernetes upgrade documentation