Tutorial: Upgrading the Kubernetes Version of a Cluster

The aim of this tutorial is to present the different steps that you need to complete in order to upgrade the Kubernetes version of one of your clusters.

When you create a cluster, OKS uses the latest supported version of Kubernetes by default. However, existing clusters are not automatically upgraded to new minor Kubernetes versions. When a new minor version is supported by OKS, you need to manually upgrade your cluster’s control plane. You also need to upgrade the associated node pools so that they use the same Kubernetes version as the control plane.

When you upgrade a cluster, you can specify the major and minor version to use, while the patch version is always the latest supported by OKS. For more information about the supported Kubernetes versions, see About OKS > Supported Kubernetes Versions.

Your clusters are automatically upgraded to the latest patch version supported by OKS during their maintenance window, if the automatic upgrade strategy is enabled.

  • You cannot downgrade a cluster from its current version. If you want to use a previous supported version of Kubernetes, you need to create a new cluster with this specific version.

  • You can only upgrade to one superior minor version at a time. For example, you can upgrade your cluster from version 1.30 to 1.31, but you cannot directly upgrade it to version 1.32. If you want to upgrade a cluster from version 1.30 to 1.32, you will need to update and upgrade your cluster to version 1.31, and repeat the process for version 1.32.

Upgrading to a New Major or Minor Kubernetes Version

Before you begin:

Retrieving the Kubernetes Version of Your Cluster Using OKS CLI

Before updating your cluster’s control plane, you need to determine which Kubernetes version your cluster is using, and which is the next Kubernetes version you can upgrade your cluster to. To obtain this information, use the cluster get command following this syntax:

Request sample
$ oks-cli cluster get \
    --cluster-name NAME_OF_CLUSTER \
    --project-name NAME_OF_PROJECT \
    --output json

This command contains the following options that you need to specify:

  • cluster-name: The name of the cluster that you want to retrieve information from.

  • project-name: The name of the project containing the cluster.

  • (optional) output: The output format for the response (json | yaml). By default, the response format is JSON.

The cluster get command returns information about the specified cluster, including:

  • version: The current Kubernetes version deployed for the cluster.

  • available_upgrade: The available version of Kubernetes for upgrade (if a newer version of Kubernetes is supported by OKS CLI).

Result sample
{
...
    "version": "1.28",
    "statuses": {
        "created_at": "2026-02-19T10:45:40.677486Z",
        "updated_at": "2026-02-19T10:52:42.303192Z",
        "status": "ready",
        "available_upgrade": "1.29"
    }
}

Updating the Kubernetes Version of the Control Plane Using OKS CLI

Once you have retrieved the Kubernetes version used by your cluster, you need to update your cluster’s control plane with the Kubernetes version that is available for upgrade. To do so, use the cluster update command following this syntax:

Request sample
$ oks-cli cluster update \
    --project-name NAME_OF_PROJECT \
    --cluster-name NAME_OF_CLUSTER \
    --version KUBERNETES_VERSION \
    --output json

This command contains the following options that you need to specify:

  • cluster-name: The name of the cluster that you want to update.

  • project-name: The name of the project containing the cluster.

  • version: The Kubernetes version to use for the cluster.

  • (optional) output: The output format for the response (json | yaml). By default, the response format is JSON.

The cluster update command returns information about the updated cluster, including the current version, and the expected version once the upgrade is completed:

  • version: The current Kubernetes version of the cluster.

  • statuses: The status information of the cluster.

    • created_at: The timestamp when the cluster was created.

    • updated_at: The timestamp when the cluster was last updated.

    • status: The status of the cluster.

    • available_upgrade: The available version of Kubernetes for upgrade.

Result sample
{
...
    "version": "1.28",
    "statuses": {
        "created_at": "2026-02-19T10:45:40.677486Z",
        "updated_at": "2026-02-23T10:51:36.614823Z",
        "status": "pending",
        "available_upgrade": "1.29"
    }
}

You can use the cluster get command to get information about the cluster you are updating, including its planned Kubernetes version. Your cluster status will go from pending to updating, to ready.

Result sample
{
...
    "statuses": {
        "created_at": "2026-02-19T10:45:40.677486Z",
        "updated_at": "2026-02-23T10:56:38.783584Z",
        "status": "ready",
        "available_upgrade": "1.29"
    }
}

Upgrading the Kubernetes Version of the Control Plane Using OKS CLI

After updating your cluster’s control plane, you can apply the planned upgrade using the cluster upgrade command following this syntax:

Request sample
$ oks-cli cluster upgrade \
    --project-name NAME_OF_PROJECT \
    --cluster-name NAME_OF_CLUSTER \
    --output json

This command contains the following options that you need to specify:

  • cluster-name: The name of the cluster you want to upgrade.

  • project-name: The name of the project containing the cluster.

  • (optional) output: The output format for the response (json | yaml). By default, the response format is JSON.

You are prompted to confirm the upgrade in the terminal. Information about your cluster is returned to confirm that your cluster is upgrading to the version you have specified in the previous step:

Result sample
{
...
    "version": "1.28",
    "expected_version": "1.29",
    "statuses": {
        "created_at": "2026-02-19T10:45:40.677486Z",
        "deleted_at": null,
        "updated_at": "2026-02-24T08:27:37.887467Z",
        "status": "pending",
        "available_upgrade": "1.29"
    }
}

If you use the cluster get command again, the status of your cluster will go from pending to upgrading, to ready.

Upgrading the Worker Nodes of the Cluster Using kubectl

Once you have upgraded the Kubernetes version of your cluster’s control plane, you need to upgrade your worker nodes to this Kubernetes version as well.

To ensure optimal performance, the version difference between a cluster’s control plane and a cluster’s worker nodes should not exceed one minor version.

By default, a new worker node uses the same Kubernetes version as the cluster’s control plane.

Worker nodes can either upgrade automatically if their upgrade strategy enables it, or be manually upgraded.

Checking if the Automatic Upgrade Strategy is Enabled

By default, the automatic upgrade strategy is enabled for OKS clusters and their worker nodes. To check if this parameter is set to true, use the kubectl get nodepools command following this syntax:

Request sample
$ kubectl get nodepools \
    --output json

You can use either json or yaml with the output option.

The kubectl get nodepools command returns information about the upgrade strategy of your node pools:

  • autoUpgradeEnabled: If true, indicates that the automatic upgrade strategy is enabled.

  • autoUpgradeMaintenance: Information about the automatic upgrade strategy.

    • durationHours: Duration of the maintenance window, in hours. During this time, upgrades are allowed to proceed.

    • startHour: Start time of the maintenance window, in 24-hour format (0–23).

    • weekDay: Day of the week when the maintenance window applies.

Result sample
{
...
                "upgradeStrategy": {
                    "autoUpgradeEnabled": true,
                    "autoUpgradeMaintenance": {
                        "durationHours": 1,
                        "startHour": 12,
                        "weekDay": "Tue"
                    }
                }
}

If the automatic upgrade is enabled, your worker nodes will be automatically upgraded to the control plane’s Kubernetes version at the indicated time and date.

You can modify your upgrade strategy by using an upgrade strategy manifest. For more information, see Node Pool Manifest Reference > Upgrade Strategy Manifest.

Manually Upgrading the Worker Nodes

To manually upgrade the existing worker nodes, you need to drain them and then delete them from the cluster, one by one. A new worker node will then automatically be created to replace the previous one.

If the automatic upgrade strategy is disabled, and you don’t manually upgrade your worker nodes, these worker nodes will never be upgraded to the planned Kubernetes version.

  1. Use the kubectl get nodes command to obtain the list of worker nodes present in your cluster:

    Result sample
    NAME              STATUS   ROLES    AGE   VERSION
ip-10-50-37-71    Ready    <none>   38m   v1.28.15
ip-10-50-59-102   Ready    <none>   38m   v1.28.15

  2. Use the kubectl drain command following this syntax to drain a node:

    Request sample
    $ kubectl drain NAME_OF_NODE --ignore-daemonsets --delete-emptydir-data

    A message is returned to confirm that your node is drained.

    Result sample
    node/ip-12-34-54-78 cordoned
...
node/ip-12-34-54-78 drained

  3. Use the kubectl delete command following this syntax to delete the previously drained node:

    Request sample
    $ kubectl delete node NAME_OF_NODE

    A message is returned to confirm that your node is deleted.

    Result sample
    node "NAME_OF_NODE" deleted

    A new node with the control plane’s Kubernetes version will automatically be created to replace the node you have deleted. This may take a few minutes.

  4. Repeat steps 2 and 3 for every node of your node pool.

Upgrading to a New Patch Kubernetes Version

Before you begin:

Checking if the Automatic Upgrade Strategy is Enabled

If the automatic upgrade strategy is enabled for your cluster, it will be automatically upgraded to the latest patch version supported by OKS during its maintenance window. In this case, you don’t have to manually upgrade your cluster.

To verify if this parameter is enabled, use the cluster get command following this syntax:

Request sample
$ oks-cli cluster get \
    --cluster-name NAME_OF_CLUSTER \
    --project-name NAME_OF_PROJECT \
    --output json

This command contains the following options that you need to specify:

  • cluster-name: The name of the cluster that you want to retrieve information from.

  • project-name: The name of the project containing the cluster.

  • (optional) output: The output format for the response (json | yaml). By default, the response format is JSON.

The cluster get command returns information about the specified cluster, including:

  • patch_upgrade_maintenance: Information about the maintenance window for patch upgrades, including:

    • enabled: If true, indicates that the automatic upgrade strategy in enabled.

    • duration_hours: Duration of the maintenance window, in hours. During this time, upgrades are allowed to proceed.

    • start_hour: Start time of the maintenance window, in 24-hour format (0–23).

    • week_day: Day of the week when the maintenance window applies.

    • tz: The timezone for the maintenance window.

Result sample
{
...
        "patch_upgrade_maintenance": {
            "enabled": true,
            "duration_hours": 0,
            "start_hour": 12,
            "week_day": "Tue",
            "tz": "UTC"
        }

}

If the automatic upgrade is enabled, your cluster and its worker nodes will be automatically upgraded to the latest patch version available.

Manually Applying a Patch Upgrade

If the automatic upgrade strategy is disabled, or if you don’t want to wait for the defined maintenance window, you can manually upgrade your cluster and cluster’s worker nodes.

  1. Use the cluster update command following this syntax to prepare your cluster for the upgrade:

    Request sample
    $ oks-cli cluster update \
    --project-name NAME_OF_PROJECT \
    --cluster-name NAME_OF_CLUSTER

  2. Use the cluster upgrade command following this syntax to upgrade your cluster’s control plane to the latest patch version available, and confirm you want to proceed with the upgrade:

    Request sample
    $ oks-cli cluster upgrade \
    --project-name NAME_OF_PROJECT \
    --cluster-name NAME_OF_CLUSTER

  3. Use the kubectl drain command following this syntax to drain a node:

    Request sample
    $ kubectl drain NAME_OF_NODE --ignore-daemonsets --delete-emptydir-data

    A message is returned to confirm that your node is drained.

    Result sample
    node/ip-12-34-54-78 cordoned
...
node/ip-12-34-54-78 drained

  4. Use the kubectl delete command following this syntax to delete the previously drained node:

    Request sample
    $ kubectl delete node NAME_OF_NODE

    A message is returned to confirm that your node is deleted.

    Result sample
    node "NAME_OF_NODE" deleted

    A new node with the control plane’s Kubernetes version will automatically be created to replace the node you have deleted. This may take a few minutes.

  5. Repeat steps 3 and 4 for every node of your node pool.

Related Pages

Export to PDF