Lab 08: Upgrading an OKS Cluster
Lab Objectives
Section intitulée « Lab Objectives »By the end of this lab, you will be able to:
- Identify the current Kubernetes version of an OKS cluster
- Identify the next available version for the upgrade
- Upgrade the Control Plane of an OKS cluster
- Upgrade the Worker Nodes
- Understand the upgrade order of the different cluster components
- Verify the cluster status before and after the upgrade
Environment Preparation
Section intitulée « Environment Preparation »Before starting this lab, make sure you have the following:
-
A functional OKS cluster. 👉 Click here to access the OKS cluster creation lab if you have not done so yet.
-
Access to the cluster with
kubectl. -
oks-cliinstalled and configured with a profile that allows you to administer the cluster.
Important: a cluster upgrade must be performed one minor version at a time.
For example, to upgrade Kubernetes from
1.32to1.34, the upgrades must be performed successively:
1.32 → 1.33 → 1.34For each version, the Control Plane is upgraded first, then the Worker Nodes must be upgraded to the same version before moving to the next minor version.
Checking the Cluster Status Before the Upgrade
Section intitulée « Checking the Cluster Status Before the Upgrade »Before starting the upgrade, check the Kubernetes version currently used by the cluster.
Check the Control Plane Version
Section intitulée « Check the Control Plane Version »Run:
kubectl versionExample output:
Client Version: v1.32.2Kustomize Version: v5.5.0Server Version: v1.32.13The Server Version field corresponds to the Kubernetes version of the Control Plane.
In this example, the Control Plane is running Kubernetes 1.32.13.
Check the Worker Nodes Version
Section intitulée « Check the Worker Nodes Version »Then check the status and version of the Worker Nodes:
kubectl get nodes -o wideExample:
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IPip-10-50-44-36 Ready <none> 38m v1.32.13 10.50.44.36 <none>ip-10-50-62-191 Ready <none> 60m v1.32.13 10.50.62.191 <none>Before proceeding, make sure that:
- all Worker Nodes are in the Ready state
- the Control Plane and Worker Nodes are using the same Kubernetes minor version
In our example:
Control Plane : v1.32.13Worker 1 : v1.32.13Worker 2 : v1.32.13The cluster is ready for the upgrade.
Upgrading the Control Plane
Section intitulée « Upgrading the Control Plane »The upgrade starts with the Control Plane.
The Worker Nodes will be upgraded in a second step.
Identify the Next Available Version
Section intitulée « Identify the Next Available Version »Retrieve the OKS cluster information:
oks-cli --profile <PROFILE> cluster get \ -p <PROJECT_NAME> \ -c <CLUSTER_NAME>In the output, look for the available_upgrade field:
"statuses": { "status": "ready", "available_upgrade": "1.33"}The available_upgrade field indicates the next minor version available for the cluster upgrade.
In this example:
Current version : 1.32Available version : 1.33Set the New Kubernetes Version
Section intitulée « Set the New Kubernetes Version »Start the upgrade to the version indicated by available_upgrade:
oks-cli --profile <PROFILE> cluster update \ -p <PROJECT_NAME> \ -c <CLUSTER_NAME> \ --version <VERSION>For example, to upgrade Kubernetes from 1.32 to 1.33:
oks-cli --profile <PROFILE> cluster update \ -p <PROJECT_NAME> \ -c <CLUSTER_NAME> \ --version 1.33Only the major.minor version is specified.
OKS automatically selects the corresponding available patch version.
For example:
1.32.13 → 1.33.13Monitoring the Control Plane Upgrade
Section intitulée « Monitoring the Control Plane Upgrade »During the upgrade, regularly check the cluster status:
oks-cli --profile <PROFILE> cluster list \ -p <PROJECT_NAME>Example:
+-----------+--------------------+---------------------+---------------+---------------+----------+| CLUSTER | PROFILE | REGION | CREATED | UPDATED | STATUS |+-----------+--------------------+---------------------+---------------+---------------+----------+| cluster02 | default | cloudgouv-eu-west-1 | an hour ago | a minute ago | ready |+-----------+--------------------+---------------------+---------------+---------------+----------+Wait until the cluster returns to the following state:
readyThen check the cluster information:
oks-cli --profile <PROFILE> cluster get \ -p <PROJECT_NAME> \ -c <CLUSTER_NAME>Relevant output:
{ "version": "1.33", "expected_version": "1.33", "statuses": { "status": "ready", "available_upgrade": "1.34" }}The OKS cluster is now using version 1.33, and version 1.34 is offered as the next upgrade.
Do not immediately upgrade to the next version. The Worker Nodes must first be upgraded to the same version as the Control Plane.
Refreshing the kubeconfig
Section intitulée « Refreshing the kubeconfig »After upgrading the Control Plane, refresh the kubeconfig to retrieve an up-to-date access configuration:
oks-cli --profile <PROFILE> cluster kubeconfig \ -p <PROJECT_NAME> \ -c <CLUSTER_NAME> \ --refresh \ --ttl <TTL>Then verify that access to the cluster works:
kubectl versionExample:
Client Version: v1.32.2Kustomize Version: v5.5.0Server Version: v1.33.13The Server Version field confirms that the Control Plane is now running Kubernetes 1.33.13.
Checking the Worker Nodes
Section intitulée « Checking the Worker Nodes »At this stage, the Control Plane is using the new Kubernetes version, but the Worker Nodes may still be using the previous version.
Check their status:
kubectl get nodesExample:
NAME STATUS ROLES AGE VERSIONip-10-50-44-36 Ready <none> 38m v1.32.13ip-10-50-62-191 Ready <none> 60m v1.32.13We temporarily have two Kubernetes versions in the cluster:
Control Plane : v1.33.13Worker 1 : v1.32.13Worker 2 : v1.32.13This state is temporary.
The Worker Nodes must now be upgraded to the same version as the Control Plane.
Upgrading the Worker Nodes
Section intitulée « Upgrading the Worker Nodes »The manual upgrade of the Worker Nodes is performed one node at a time.
For each Worker Node:
- the node is drained.
- the pods running on the node are evicted.
- the node is deleted from the cluster.
- the NodePool automatically creates a new Worker Node.
- the new Worker joins the cluster with the new Kubernetes version.
Step 1: Identify the Worker Nodes to Upgrade
Section intitulée « Step 1: Identify the Worker Nodes to Upgrade »Display the Worker Nodes:
kubectl get nodesExample:
NAME STATUS ROLES AGE VERSIONip-10-50-44-36 Ready <none> 38m v1.32.13ip-10-50-62-191 Ready <none> 60m v1.32.13Choose the first Worker Node to upgrade.
Step 2: Drain the Worker Node
Section intitulée « Step 2: Drain the Worker Node »Before deleting a Worker Node, it must be drained.
Draining prevents new pods from being scheduled on the node and evicts workloads that can be moved.
Run:
kubectl drain <NODE_NAME> \ --ignore-daemonsets \ --delete-emptydir-dataFor example:
kubectl drain ip-10-50-44-36 \ --ignore-daemonsets \ --delete-emptydir-dataExample output:
node/ip-10-50-44-36 cordonedWarning: ignoring DaemonSet-managed Pods: kube-system/cilium-envoy-xxxxx, kube-system/cilium-xxxxx, ...node/ip-10-50-44-36 drainedThe --ignore-daemonsets option allows pods managed by DaemonSets to be ignored during the drain.
The --delete-emptydir-data option allows the eviction of pods using emptyDir volumes.
Then check the node status:
kubectl get nodesExample:
NAME STATUS ROLES AGE VERSIONip-10-50-44-36 Ready,SchedulingDisabled <none> 39m v1.32.13ip-10-50-62-191 Ready <none> 61m v1.32.13The SchedulingDisabled status indicates that the node has been cordoned and no longer accepts new pods.
Only delete the Worker Node once the drain has completed successfully.
Step 3: Delete the Worker Node
Section intitulée « Step 3: Delete the Worker Node »Once the node has been successfully drained, delete it from the cluster:
kubectl delete node <NODE_NAME>For example:
kubectl delete node ip-10-50-44-36The NodePool detects that the Worker has disappeared and automatically creates a new node to replace it.
Step 4: Wait for the New Worker to Be Created
Section intitulée « Step 4: Wait for the New Worker to Be Created »Monitor the Worker Nodes:
kubectl get nodes -wA new Worker Node should gradually join the cluster.
Once the new node is in the Ready state, exit watch mode with Ctrl+C.
Then check the versions:
kubectl get nodesExample:
NAME STATUS ROLES AGE VERSIONip-10-50-36-2 Ready <none> 31s v1.33.13ip-10-50-62-191 Ready <none> 64m v1.32.13The new Worker is now using the same Kubernetes version as the Control Plane:
Control Plane : v1.33.13Worker 1 : v1.33.13Worker 2 : v1.32.13The first Worker has been successfully upgraded.
Upgrading the Remaining Worker Nodes
Section intitulée « Upgrading the Remaining Worker Nodes »Repeat the same procedure for each Worker that is still using the previous Kubernetes version.
Start by identifying the remaining nodes:
kubectl get nodesFor each Worker concerned, perform the following steps:
kubectl drain <NODE_NAME> \ --ignore-daemonsets \ --delete-emptydir-dataVerify that the drain completes successfully, then delete the node:
kubectl delete node <NODE_NAME>Then wait for its replacement to be created:
kubectl get nodes -wBefore moving to the next Worker, verify that the new node:
- is in the Ready state
- is using the same Kubernetes version as the Control Plane
Worker Nodes must be replaced one at a time. Wait until the new Worker is operational before starting the upgrade of the next one.
Final Upgrade Verification
Section intitulée « Final Upgrade Verification »Once all Worker Nodes have been replaced, check the Control Plane version:
kubectl versionExample:
Client Version: v1.32.2Kustomize Version: v5.5.0Server Version: v1.33.13Then check the Worker Nodes:
kubectl get nodes -o wideExample:
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IPip-10-50-36-2 Ready <none> 4m56s v1.33.13 10.50.36.2 <none>ip-10-50-51-19 Ready <none> 56s v1.33.13 10.50.51.19 <none>The Control Plane and all Worker Nodes must now be using the same Kubernetes version:
Control Plane : v1.33.13Worker 1 : v1.33.13Worker 2 : v1.33.13Finally, check the status of the cluster components:
kubectl get pods -AMake sure that the system pods are operational and that no component remains in an abnormal state.
The upgrade is complete when:
- the Control Plane is using the new Kubernetes version
- all Worker Nodes are using the same version
- all Worker Nodes are in the Ready state
- the Kubernetes cluster components are operational
Upgrading Across Multiple Minor Versions
Section intitulée « Upgrading Across Multiple Minor Versions »If multiple minor versions need to be applied, repeat the entire procedure for each version.
For example, to upgrade Kubernetes from 1.32 to 1.35:
1.32 ↓Control Plane 1.33 ↓Worker Nodes 1.33 ↓Control Plane 1.34 ↓Worker Nodes 1.34 ↓Control Plane 1.35 ↓Worker Nodes 1.35Never start the upgrade to the next minor version until the Worker Nodes have reached the same version as the Control Plane.