What is a Kubernetes cluster upgrade?
A Kubernetes cluster upgrade is the process of moving a running cluster to a newer Kubernetes version. The control plane goes first, then the worker nodes, then clients such as kubectl. A patch upgrade (1.36.2 to 1.36.3) brings fixes. A minor upgrade (1.36 to 1.37) can add features and remove old APIs.
Think of renovating a hotel while guests stay in it. You close one floor, move its guests to other floors, renovate it and open it again. Nobody leaves the hotel, but you need enough free rooms and a plan for every guest.
Upgrades are not optional for long. Kubernetes ships about three minor releases a year and maintains the three most recent ones, each with roughly a year of patch support.
In what order does an upgrade happen?
The order follows the version skew rules. A kubelet must never be newer than the API server, but it may be up to three minor versions older. That is why the control plane always leads.
Control plane
On the control plane, etcd is upgraded first, then every kube-apiserver instance, then the controller manager and the scheduler. In a highly available control plane, API server instances may differ by one minor version while the upgrade rolls through them.
Worker nodes
Each node is drained, then either replaced by a new node on the target version or upgraded in place and returned to service. Draining matters for minor upgrades, because the kubelet does not support moving to a new minor version in place with pods still running.
One minor at a time
The API server must not skip minor versions. To get from 1.34 to 1.37, a cluster goes through 1.35 and 1.36 on the way. Falling behind turns one routine upgrade into several in a row.
How do workloads survive a node upgrade?
Draining marks the node unschedulable and evicts its pods through the Eviction API, so they shut down gracefully and start again on other nodes. DaemonSet pods stay where they are, since their controller would recreate them on the same node.
Evictions respect PodDisruptionBudgets. A budget of minAvailable: 2 on a three-replica app means only one of its pods can be down at a time, and a drain that would break it waits.
Before a minor upgrade, check these:
- Every Deployment you care about runs at least two replicas.
- PodDisruptionBudgets exist for important apps, and none of them allow zero disruptions.
- The cluster has spare capacity for the pods of one drained node.
- No manifest, Helm chart or controller still uses an API version the target release removes.
Removed API versions are no longer served. Manifests that still use them fail on apply, for example a HorizontalPodAutoscaler on autoscaling/v2beta2 after 1.26. Existing objects stay readable through the newer API, so the fix is updating apiVersion in your sources.
How enum handles Kubernetes cluster upgrades
enum Kubernetes Engine supports the three most recent minor releases and applies patch releases for you. Each cluster has its own isolated control plane, and minor upgrades roll through worker nodes by replacing them one at a time, so replicated workloads keep serving. For upgrade timing on your clusters, ask us.
FAQ
Can I skip a minor version when upgrading? No. The API server has to move one minor version at a time, even in a single-instance control plane. A cluster three releases behind needs three upgrades in sequence, each with its own checks.
Why did my node drain hang during an upgrade? Usually a PodDisruptionBudget blocks the eviction, for example a budget that allows zero disruptions or an app with one replica. Scale the app up or adjust the budget, and the drain continues.
Do I have to upgrade kubectl too? Yes, once the control plane is upgraded. kubectl is supported within one minor version of the API server, older or newer. Keep it close to the cluster version so commands and API fields match what the server expects.