Skip to main content
Welcome to this comprehensive guide on upgrading your Kubernetes cluster. In this lesson, we explore the process of upgrading the core control plane components while temporarily setting aside external dependencies such as etcd and CoreDNS. This guide builds on our previous discussion about Kubernetes software releases and component versioning.
The image shows a diagram of Kubernetes components and their versions, including kube-apiserver, controller-manager, kube-scheduler, kubelet, kube-proxy, kubectl, ETCD cluster, and CoreDNS.
It is not mandatory for all components to run the same version. Typically, the kube-apiserver—the primary control plane component—must have a version that is equal to or higher than that of the other components. The controller manager and scheduler may lag by one minor version, while kubelet and kube-proxy can lag by two minor versions. For example, if the kube-apiserver is running version v1.10, the controller manager and scheduler can run at either v1.10 or v1.9, and kubelet and kube-proxy may run at v1.8. However, none of these components should exceed the kube-apiserver’s version (e.g., v1.11). The kubectl utility is an exception—it can be one minor version ahead, equal to, or one minor version behind the apiserver. This permissible version skew facilitates live upgrades by allowing one component to be upgraded at a time.
Upgrading your Kubernetes cluster one minor version at a time ensures smoother transitions and minimizes downtime.

​
When to Upgrade

Imagine your cluster is running version 1.10 and Kubernetes has released versions 1.11 and 1.12. Kubernetes supports only the three most recent minor versions at any given time. For instance, if v1.12 is the latest release, then versions 1.12, 1.11, and 1.10 are supported. When v1.13 is released, the supported versions become 1.13, 1.12, and 1.11. It is always advisable to upgrade your cluster to a newer release before your current version falls out of the supported list.
The image shows a timeline of Kubernetes components (kube-apiserver, controller-manager, kube-scheduler, kubectl, kubelet, kube-proxy) at version 1.10, with support status updates.
Direct upgrades from version 1.10 to 1.13 are not recommended. Instead, upgrade one minor version at a time—from 1.10 to 1.11, then from 1.11 to 1.12, and finally from 1.12 to 1.13. The upgrade steps vary depending on your cluster setup. Managed Kubernetes clusters (e.g., on Google Kubernetes Engine) offer a more streamlined upgrade process, while clusters deployed using kubeadm benefit from tools that help plan and execute the upgrade. For clusters set up manually, all components require an individual upgrade.

​
Upgrading the Control Plane

Consider a production cluster with master and worker nodes running version 1.10 and hosting live applications. The upgrade process is divided into two major steps:
  1. Upgrade the master nodes (control plane components).
  2. Upgrade the worker nodes.
During the master node upgrade, the control plane components (API server, scheduler, and controller manager) experience a brief downtime. While management functions (such as kubectl access and new deployments) are temporarily unavailable, workloads on the worker nodes continue to serve users. Post-upgrade, the cluster operates in a supported mixed-version state (for example, masters at v1.11 while workers remain at v1.10).

​
Upgrading Worker Nodes: Strategies

There are several strategies for upgrading worker nodes:
  1. Upgrade all worker nodes simultaneously:
    This method leads to downtime as pods become unavailable until the upgrade is complete.
The image illustrates "Strategy - 1" with four labeled boxes (M and W) and arrows pointing to a group of people, indicating a process or workflow.
  1. Upgrade one node at a time:
    This approach minimizes downtime because workloads are automatically rescheduled to the remaining nodes.
The image illustrates "Strategy - 2" with icons representing groups and processes, using arrows and labeled boxes with versions v1.11 and v1.10.
  1. Add new worker nodes:
    Deploy new nodes with the updated version, migrate workloads to them, and decommission the older nodes. This strategy is especially effective in cloud environments.
The image illustrates "Strategy - 3" with three labeled boxes (M and W) and arrows pointing to a group of people, indicating a process or workflow.

​
Upgrading with kubeadm

Assume you intend to upgrade your cluster from version 1.11 to 1.13. The kubeadm tool simplifies this process by providing an upgrade command that shows the current cluster version, the kubeadm tool version, and the latest stable Kubernetes version, along with the required steps. Run the following command to plan the upgrade:
The output includes:
  • The current cluster version.
  • The kubeadm tool version.
  • The latest available version in your current series.
  • A table indicating which components require manual upgrades post control plane upgrade (typically the kubelet).
For example, the output might look like:
Before proceeding, ensure that the kubeadm tool itself is updated to the target version since it must match the Kubernetes release series. Remember, only one minor version upgrade is permitted at a time. If you are on v1.11 and wish to reach v1.13, you must first upgrade to v1.12. Begin by upgrading the kubeadm tool:
Then, apply the control plane upgrade:
Upon successful completion, you should see an output similar to:
At this stage, the control plane components have been upgraded to version 1.12. However, running kubectl get nodes will show the kubelet version on each node, which might not yet reflect the updated control plane version.

​
Upgrading the kubelets

If your master nodes are running kubelet processes, you need to upgrade them as well. Upgrade the kubelet package and then restart the kubelet service. For example, check the current node versions:
The output might be:
Proceed to upgrade the kubelet on the master node:
After restarting, verify the upgrade:
The output should now reflect:

​
Upgrading Worker Nodes

Upgrading worker nodes should be performed one at a time to prevent downtime and ensure workloads are rescheduled safely.
  1. Drain the node:
    Draining a node evicts its pods and marks it as unschedulable.
Draining ensures that the node is safely prepared for an upgrade without impacting running applications.
  1. Upgrade packages on the worker node:
    Upgrade both the kubeadm and kubelet packages.
  2. Mark the node schedulable again:
    Once the upgrade is complete, make the node available for new pods.
Repeat these steps for each worker node. For instance, for node-2:
Once every node is upgraded, your cluster will be fully running on version 1.12. You can then repeat similar procedures to upgrade from 1.12 to 1.13.

​
Conclusion

This step-by-step guide has walked you through the critical phases of the Kubernetes cluster upgrade process—from planning the control plane upgrade using kubeadm to carefully upgrading your worker nodes. By upgrading one minor version at a time, you ensure that your cluster remains healthy and your applications experience minimal downtime. For further insights, try upgrading a live cluster with running applications and observe how workloads are seamlessly shifted to minimize disruptions. Happy upgrading!

​
Additional Resources

Watch Video