How to Upgrade a Kubernetes Worker Node to Match the Control Plane Version
When adding new nodes to your Kubernetes cluster, version compatibility is crucial. Kubernetes allows nodes to be one minor version behind the control plane, but not more. If your cluster is running version v1.32.2, a worker node running an older version, like v1.29.15, will be rejected or marked as NotReady.
In this guide, we’ll walk you through the process of upgrading your worker node to match your control plane’s version and resolve version mismatch issues.
🔍 The Problem
After joining a worker node, running the following command:
kubectl get nodes
Could return something like this:
NAME STATUS ROLES AGE VERSION
worker-node NotReady <none> 20s v1.29.15
control-plane Ready control-plane 30d v1.32.2
another-worker Ready <none> 30d v1.32.2
In this case, worker-node is running v1.29.15, which is too old compared to the cluster’s v1.32.2.
🛠️ Step-by-Step: Upgrade the Worker Node
✅ 1. Unhold Kubernetes Packages
Kubernetes packages may be held to prevent auto-upgrades. You need to unhold them so that you can proceed with the upgrade:
sudo apt-mark unhold kubelet kubeadm kubectl
✅ 2. Add the Correct Kubernetes v1.32 APT Repository
If your system is using an older repository (e.g., for v1.29), replace it with the v1.32 repository:
sudo tee /etc/apt/sources.list.d/kubernetes.list <<EOF
deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /
EOF
sudo apt update
✅ 3. Upgrade Kubernetes Components
Next, install the target version of Kubernetes components:
sudo apt install -y kubelet=1.32.2-1.1 kubeadm=1.32.2-1.1 kubectl=1.32.2-1.1
To confirm available versions, use:
apt-cache policy kubelet | grep 1.32
✅ 4. Hold the Upgraded Versions
Once the upgrade is complete, you can hold the upgraded versions to prevent auto-updating:
sudo apt-mark hold kubelet kubeadm kubectl
✅ 5. Restart kubelet
To apply the upgrade, restart the kubelet service:
sudo systemctl daemon-reexec
sudo systemctl restart kubelet
✅ 6. Verify Node Status
Finally, check the status of the node again:
kubectl get nodes
You should see the worker node now in the Ready state with the updated version:
worker-node Ready <none> X min v1.32.2
🎉 Done!
Your worker node is now running the same version as the control plane. Keeping Kubernetes versions in sync across your nodes ensures cluster stability and avoids potential upgrade issues in the future.