Rollback cluster to previous Kubernetes version

With Amazon EKS version rollback, you can revert your cluster’s Kubernetes control plane to the previous minor version after performing an in-place upgrade. If you encounter issues after upgrading, such as application incompatibilities, deprecated API usage, or unexpected behavior, you can roll back to restore your cluster to a known good state.

During a rollback, Amazon EKS reverts the Kubernetes API server and control plane components to the previous version while preserving all etcd data, customer workloads, and persistent volumes.

What gets rolled back

• Kubernetes API server version

• Control plane components and their configurations

• Platform version (reverts to the latest platform version for the previous Kubernetes version)

• EKS Auto Mode worker nodes. For clusters running EKS Auto Mode, EKS automatically manages the rollback of Auto Mode worker nodes before reverting the control plane. For more information, see Rollback EKS Auto Mode clusters.

What does NOT get rolled back

• etcd data. All cluster state, resources, and configurations are preserved.

• Customer workloads. Your pods, deployments, and services continue running.

• EKS add-ons. Add-on versions remain unchanged. You manage these separately.

• Persistent volumes and data. All customer data remains intact.

• Self-managed nodes and hybrid nodes. You are responsible for rolling these back.

• Managed Node Groups. You must roll back these separately using the UpdateNodegroupVersion API.

Prerequisites

Before you can roll back a cluster, all of the following conditions must be met:

Requirement	Details
7-day window	The rollback must be initiated within 7 days of the upgrade completing. After 7 days, rollback is no longer available.
Upgraded cluster	The cluster must have been upgraded to its current version through in-place upgrade. Clusters created at their current version cannot be rolled back.
Single version only	You can only rollback by one minor version (N to N-1). If you upgraded from 1.31 to 1.32 and then to 1.33, you can only rollback to 1.32, not to 1.31.
Supported version	Version rollback is available for currently supported EKS versions.
Extended support policy	To rollback to a version that is in extended support, you must first change the cluster’s upgrade policy to EXTENDED.
No end-of-extended-support auto-upgrade	If your cluster was automatically upgraded at the end of extended support, you cannot roll back to the previous version. If your cluster was automatically upgraded at the end of standard support, you can roll back but must first change the upgrade policy to EXTENDED.
Cluster status	The cluster must be in ACTIVE status. You cannot initiate a rollback while another update is in progress.
EKS feature compatibility	If an EKS feature enabled on your cluster is not supported on the previous version, the rollback request fails. This check cannot be bypassed with --force.

In addition to the preceding requirements, certain conditions make rollback impossible even with the --force flag. These include: the cluster was created at the current version, more than 7 days have passed since the upgrade, the cluster has already been upgraded again to a newer version, or a backward-incompatible EKS feature was enabled at the current version boundary.

Summary

The high-level summary of the Amazon EKS cluster rollback process is as follows:

1. Review rollback readiness insights to identify any issues that could affect the rollback.

2. Resolve any blocking issues (ERROR status insights) or use --force to bypass insight checks.

3. Verify your applications, custom controllers, and third-party tools are compatible with the previous Kubernetes version.

4. If your worker nodes are running the same Kubernetes version as the control plane, roll back the worker nodes first.

5. If you have add-ons running versions incompatible with the previous Kubernetes version, downgrade them to a compatible version.

6. Initiate the control plane rollback.

7. Monitor the rollback progress.

Important

For clusters running EKS Auto Mode, step 4 is handled automatically. When you initiate the rollback, EKS rolls back Auto Mode nodes before the control plane. For more information, see Rollback EKS Auto Mode clusters.

Step 1: Review rollback readiness insights

Amazon EKS automatically evaluates your cluster against a set of point-in-time rollback readiness checks and surfaces any issues through cluster insights under the ROLLBACK_READINESS category. These insights appear after you perform an upgrade and remain available during the 7-day rollback eligibility window.

Viewing rollback readiness insights

AWS Console:

1. Open the Amazon EKS console.

2. Select your cluster.

3. Navigate to the Upgrade insights tab. Rollback readiness insights appear here after an upgrade.

4. Review any insights with ERROR or WARNING status.

AWS CLI:

aws eks list-insights \
  --cluster-name my-cluster \
  --region us-west-2 \
  --filter '{"categories": ["ROLLBACK_READINESS"]}'

To get details on a specific insight:

aws eks describe-insight \
  --cluster-name my-cluster \
  --region us-west-2 \
  --id <insight-id>

Refreshing insights

EKS refreshes insights every 24 hours. You can manually trigger a refresh after resolving issues using the Refresh button in the Amazon EKS console, or by using the CLI:

aws eks start-insights-refresh \
  --cluster-name my-cluster \
  --region us-west-2

Note

EKS automatically refreshes insights when you initiate a rollback to ensure checks are run against the latest cluster state.

Insight status behavior

Status	Meaning	Effect on rollback
PASSING	No issues detected for this check	Rollback allowed
WARNING	Potential issue detected, not blocking	Rollback allowed (advisory only)
ERROR	Blocking issue detected	Rollback blocked until resolved, or use --force to bypass
UNKNOWN	Unable to determine status	Rollback blocked until resolved, or use --force to bypass

Insights with ERROR or UNKNOWN status block the rollback. Insights with PASSING or WARNING status do not prevent you from rolling back.

Rollback readiness checks

Amazon EKS performs a set of checks as part of rollback readiness insights. These checks evaluate API usage compatibility (including field-level change detection), cluster health, kubelet version skew, kube-proxy version skew, and add-on version compatibility. For clusters running EKS Auto Mode, additional checks evaluate NodePool disruption budgets, do-not-disrupt annotations, and PodDisruptionBudget configurations.

Using the --force flag

If rollback readiness insights show ERROR status and you want to proceed without resolving the issues, you can use the --force flag to bypass all insight checks:

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --force \
  --region us-west-2

Warning

Using --force bypasses all insight checks (ERROR, WARNING, UNKNOWN) and proceeds directly with the rollback. EKS cannot guarantee the safety of the rollback when insight checks are bypassed. You accept full responsibility for any issues that arise.

The --force flag only bypasses insight checks. It does not bypass prerequisite validations such as the 7-day window, creation version check, or sequential rollback check. For Auto Mode clusters, --force does not override disruption controls. NodePool disruption budgets, PDBs, and do-not-disrupt annotations are still honored.

Step 2: Prepare worker nodes

Before rolling back the control plane, ensure your worker nodes are compatible with the target version. The Kubernetes version skew policy requires that worker nodes cannot run a version newer than the control plane.

EKS Auto Mode

No action required. When you initiate the rollback, EKS automatically rolls back Auto Mode nodes before the control plane. For more information, see Rollback EKS Auto Mode clusters.

Managed Node Groups (MNG)

You must roll back your managed node groups to the previous version before rolling back the control plane. Use the UpdateNodegroupVersion API:

aws eks update-nodegroup-version \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup \
  --kubernetes-version 1.30 \
  --region us-west-2

The node group update respects your configured update settings (maxUnavailable or maxUnavailablePercentage) and update strategy (Rolling or Force).

Self-managed nodes and hybrid nodes

You are responsible for rolling back self-managed nodes and hybrid nodes. Update your node AMIs or configurations to use the previous Kubernetes version before rolling back the control plane.

Fargate

Version rollback is not supported for Fargate worker nodes. You can roll back the control plane of a cluster that uses Fargate, but Fargate pods running the same Kubernetes version as the control plane trigger the kubelet version skew insight with ERROR status.

EKS cannot automatically rollback Fargate pods to an older kubelet version.

Workaround: If you have Fargate pods running the same Kubernetes version as the control plane, delete those pods before initiating the rollback. Then roll back your control plane. Any remaining pods launch with the rolled-back version when you redeploy them.

Alternatively, use --force to bypass the insight check. However, proceeding with a kubelet version skew violation might result in unexpected behavior for your Fargate workloads until those pods are replaced.

Step 3: Rollback the cluster control plane

You can initiate a rollback using the AWS Console, AWS CLI, or the EKS API.

Rollback cluster using the AWS Console

1. Open the Amazon EKS console.

2. Select your cluster.

3. Choose the Actions dropdown.

4. Choose Rollback cluster version.

5. Review the rollback summary, including any insight warnings.

6. Choose Rollback version.

The rollback takes several minutes to complete. For Auto Mode clusters, the node rollback phase might take longer. For more information, see Rollback EKS Auto Mode clusters.

Rollback cluster using the AWS CLI

Use the existing update-cluster-version command with the previous (N-1) Kubernetes version:

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --region us-west-2

Example response:

{
    "update": {
        "id": "e4091a28-ea14-48fd-a8c7-975aeb469e8a",
        "status": "InProgress",
        "type": "VersionRollback",
        "params": [
            {
                "type": "Version",
                "value": "1.30"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.16"
            }
        ],
        "createdAt": "2026-05-12T16:56:01.082000-04:00",
        "errors": []
    }
}

Note

EKS runs an insight refresh before performing the rollback if insight data is stale.

Step 4: Monitor rollback progress

You can monitor the status of your cluster rollback using the Amazon EKS console or the AWS CLI.

AWS CLI:

aws eks describe-update \
  --name my-cluster \
  --region us-west-2 \
  --update-id e4091a28-ea14-48fd-a8c7-975aeb469e8a

AWS Console:

1. Open the Amazon EKS console.

2. Select your cluster.

3. Navigate to the Update history tab.

4. Locate the update ID associated with the rollback to view its current status.

Status transitions

For standard clusters (without Auto Mode):

InProgress → Successful
InProgress → Failed

For Auto Mode clusters, the cluster status remains ACTIVE while nodes are rolling back and changes to UPDATING only when the control plane rollback begins. Use describe-update to track the overall rollback progress. For more information, see Rollback EKS Auto Mode clusters.

When a Successful status is displayed, the rollback is complete.

Considerations and warnings

Insights are best-effort and point-in-time

Cluster insights are evaluated at the time rollback is triggered. If you make changes to your cluster after insights are checked but before the rollback completes (for example, creating resources using new APIs), those changes are not captured by the initial insight check and could cause issues after rollback completes.

etcd data preservation

EKS preserves etcd data during rollback. Incompatible resources bypassed using the --force flag remain persisted and are not garbage collected.

Extended support charges

If you roll back from a version under standard support to a version under extended support, your cluster begins incurring extended support charges. For example, if you upgrade from 1.30 (extended support) to 1.31 (standard support) and then roll back to 1.30, extended support charges resume.

Shared responsibility model for rollback

EKS rolls back the Kubernetes control plane to the desired version. As part of the shared responsibility model, you are responsible for verifying application compatibility with the previous version:

• EKS is responsible for safely reverting the control plane components.

• You are responsible for ensuring your applications, configurations, and dependencies are compatible with the previous version.

• You must review any incompatibilities between versions, assess your cluster for exposure, and mitigate any issues.

CloudFormation stack rollback behavior

If a CloudFormation stack update fails and triggers a stack rollback, the revert to a previous template version that specifies a lower Kubernetes version does not trigger a cluster version rollback. Version rollback must be explicitly initiated through the UpdateClusterVersion API, CLI, or console.

Rollback and add-ons

EKS does not automatically rollback add-on versions during a cluster version rollback. You must manage add-on versions separately.

Before rolling back the control plane:

1. Check add-on compatibility with the target version using the rollback readiness insights.

2. If an add-on version is incompatible with the previous Kubernetes version, downgrade it first:

aws eks update-addon \
  --cluster-name my-cluster \
  --addon-name vpc-cni \
  --addon-version v1.12.0-eksbuild.2 \
  --region us-west-2

+ . After the control plane rollback completes, verify all add-ons are functioning correctly.

Note

Rollback readiness insights only check EKS-managed add-on versions. For self-managed add-ons, you are responsible for validating compatibility with the target version before rolling back.

Related resources

• Rollback EKS Auto Mode clusters

• Update existing cluster to new Kubernetes version

• Prepare for Kubernetes version upgrades and troubleshoot misconfigurations with cluster insights

• Understand the Kubernetes version lifecycle on EKS

• Update a managed node group

• Best Practices for Cluster Upgrades