Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Roll back a cluster to a 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

The following components are rolled back:

What does NOT get rolled back

The following components are not rolled back:

Prerequisites

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

In addition to the preceding requirements, certain conditions make rollback impossible even with the --force flag. These conditions include the following: 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 following is the high-level summary of the Amazon EKS cluster rollback process:

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:

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

Amazon EKS refreshes insights every 24 hours. You can manually trigger a refresh after resolving issues by choosing 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

Insight status behavior

The following table describes the meaning of each insight status and its effect on rollback:

Insights with ERROR or UNKNOWN status block the rollback. Insights with PASSING or WARNING status don’t 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

The --force flag only bypasses insight checks. It doesn’t bypass prerequisite validations such as the 7-day window, creation version check, or sequential rollback check. For Auto Mode clusters, --force doesn’t 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, make sure that your worker nodes are compatible with the target version. The Kubernetes version skew policy requires that worker nodes can’t run a version newer than the control plane.

EKS Auto Mode

No action required. When you initiate the rollback, Amazon 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.

Amazon EKS can’t automatically roll back 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: Roll back the cluster control plane

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

Roll back a cluster by using the AWS Console

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.

Roll back a cluster by 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": []
    }
}

Step 4: Monitor rollback progress

You can monitor the status of your cluster rollback by 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:

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 might cause issues after rollback completes.

etcd data preservation

Amazon EKS preserves etcd data during rollback. Incompatible resources bypassed by 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

Amazon 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:

CloudFormation stack rollback behavior

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

Rollback and add-ons

Amazon EKS doesn’t automatically roll back add-on versions during a cluster version rollback. You must manage add-on versions separately.

Before rolling back the control plane:

Related resources