A Kubernetes upgrade is a controlled change of cluster version and supporting components while preserving workload availability, compatibility, and recovery options.
The safest upgrade program is routine rather than reactive. Patch releases should be reviewed and applied promptly, while minor-version changes need a deliberate compatibility and maintenance campaign. Waiting until a cluster is near the end of version support compresses API review, add-on testing, workload validation, and recovery planning into a smaller window.
This guide owns the Kubernetes upgrade decision inside the Kubernetes Cluster Management for Small Teams operating model. It focuses on version policy, maintenance risk, workload disruption, sequencing, validation, and recovery—not on kubeadm commands or provider-specific click paths.
At Raff, the maintenance rule is to make production the last environment that discovers an upgrade problem. Release notes, API compatibility, workload disruption, and recovery state should be settled before the maintenance window opens.
Kubernetes upgrades are a lifecycle process, not an emergency
Kubernetes changes continuously. Minor releases introduce new capabilities and deprecations, while patch releases carry bug and security fixes within an existing minor branch.
The Kubernetes project currently maintains the three most recent minor release branches. Minor releases are produced roughly three times per year, and supported branches receive patch releases for about one year. That makes version age an operational constraint rather than a cosmetic number.
A useful maintenance model separates two rhythms:
| Change type | Operating approach | Main question |
|---|---|---|
| Patch release | Routine maintenance | Is there a fix we should adopt promptly? |
| Minor release | Planned upgrade campaign | Are workloads, APIs, add-ons, and recovery ready? |
Patch updates should not require the same governance burden as every minor upgrade. Conversely, treating a minor upgrade as “just another patch” can hide API removals, version-skew constraints, controller compatibility, and workload disruption.
Version age is operational debt: delaying upgrades does not remove the work; it compresses testing and recovery time into a smaller window.
A small team should therefore maintain an explicit version policy. Record the current cluster version, next target version, support status, known blockers, test environment, maintenance owner, and intended production window. The goal is to keep upgrades visible before they become urgent.
Supported versions and version skew define the upgrade path
Kubernetes components are allowed to run at different minor versions only within defined compatibility ranges.
The Kubernetes Version Skew Policy defines these boundaries. In a high-availability control plane, kube-apiserver instances must stay within one minor version of each other. A kubelet must not be newer than its kube-apiserver and may lag by up to three minor versions. kubectl is supported within one minor version newer or older than the API server.
Those ranges provide temporary compatibility during maintenance; they should not be treated as a reason to leave the cluster permanently split across versions.
For a standard Kubernetes upgrade path, the control plane moves first, followed by worker nodes and then clients and supporting components as appropriate. Kubernetes also recommends bringing the current minor release to its latest patch before moving to the latest patch of the target minor release.
Minor versions should be advanced sequentially. The official cluster upgrade overview and kubeadm upgrade guidance do not support skipping minor versions in the normal upgrade path.
A practical policy is therefore:
current minor → latest patch in current minor → next minor, latest patch → validate → next minor only if another upgrade is required
This prevents a long-neglected cluster from turning into one large, poorly understood version jump.
Compatibility review should finish before the maintenance window
The maintenance window is the wrong time to discover that an API disappeared, an admission webhook no longer works, or a storage controller does not support the target version.
Compatibility review should cover more than application Deployments.
Before a minor upgrade, inspect:
- Kubernetes release notes for the target version;
- deprecated or removed API versions used by manifests;
- CustomResourceDefinitions and the operators that manage them;
- admission webhooks and policy controllers;
- CNI and NetworkPolicy components;
- CSI and storage integrations;
- ingress or Gateway controllers;
- monitoring, logging, and metrics components;
- backup and restore tooling;
- Helm charts and controllers installed outside the core platform;
kubectl, automation, CI/CD, and infrastructure tooling that talks to the API server.
The Kubernetes API deprecation policy provides predictable removal rules, but predictable does not mean automatic. Teams still need to find deprecated usage before the target version stops serving it.
The safest sequence is to detect and remove deprecated dependencies while the current version still serves both the old and new behavior. That gives the team a normal deployment window instead of forcing application changes during cluster maintenance.
A staging or pre-production environment should then run the target version with representative workloads. The purpose is not to reproduce every production request. It is to prove that critical controllers start, workloads schedule, storage mounts, networking works, probes become ready, jobs complete, and operational tooling still has access.
The safest maintenance window starts with compatibility evidence, not a calendar invite.
Node maintenance is safe only when workloads can tolerate disruption
Worker upgrades normally require Pods to move away from a node before the node is updated or replaced.
Kubernetes provides kubectl drain for this maintenance pattern. A drain marks the node unschedulable and safely evicts eligible Pods while respecting configured PodDisruptionBudgets. The official node drain guidance treats this as preparation for maintenance rather than as the maintenance itself.
A PodDisruptionBudget can limit how many replicas are voluntarily disrupted at once, but it does not create capacity and it does not protect against involuntary failures.
That distinction matters. Suppose an application has three replicas and a PDB requiring two to remain available. Draining one node may still stall if the remaining cluster has nowhere to schedule the replacement Pod.
A PodDisruptionBudget is only useful when the remaining cluster has capacity to place replacement Pods.
Maintenance readiness therefore depends on several conditions working together:
- enough replicas to tolerate one being unavailable;
- realistic resource requests so replacement Pods can be scheduled;
- spare worker capacity or autoscaling headroom;
- readiness probes that reflect actual service readiness;
- topology that does not place every replica on the same worker;
- stateful workloads that can detach, attach, and recover correctly;
- startup times that fit the maintenance window;
- dependencies such as databases and external APIs that remain available.
Use Kubernetes Requests vs Limits to make scheduling capacity honest, and Kubernetes Cluster Sizing when one-worker-loss headroom is unclear.
The upgrade sequence separates control plane, workers, add-ons, and workloads
A cluster upgrade should have a sequence even when the managed platform performs part of the work.
The exact mechanics depend on how Kubernetes was deployed, but the operating order can remain consistent:
| Stage | What changes | What the team validates |
|---|---|---|
| Pre-check | Compatibility, support status, backup/recovery state | No unresolved blocker remains |
| Control plane | API server and control-plane components | API access, controllers, cluster health |
| Worker pool | Node Kubernetes version or replacement nodes | Scheduling, networking, storage, readiness |
| Cluster add-ons | CNI, CSI, ingress, metrics, policies where required | Add-on compatibility and service behavior |
| Client/tooling | kubectl, automation, CI/CD | Administrative and deployment access |
| Workload verification | Critical applications and jobs | User paths, state, latency, errors, queues |
This is a strategy, not a command list. In a self-managed kubeadm cluster, the operator executes more of these steps directly. In managed Kubernetes, the provider may own control-plane operations and parts of worker replacement. The application team still owns workload compatibility and the evidence that the system remains usable.
Avoid mixing this cluster-version sequence with application rollout strategy. A Deployment rolling update, blue-green release, or canary rollout changes application versions. A Kubernetes upgrade changes the platform on which those workloads run. They can interact, but they should not be performed casually as one combined change.
A strong change window reduces simultaneous variables. Freeze unrelated application releases unless there is a specific reason to combine them.
The decision framework assigns urgency by change type and risk
Not every Kubernetes update should wait for the same cadence.
Use this framework to decide what happens next:
| Situation | Default decision | Why |
|---|---|---|
| Critical security or reliability patch | Review and apply promptly | Exposure or known defect justifies faster maintenance |
| Normal supported patch | Include in routine maintenance | Keeps the cluster current without a full minor campaign |
| New supported minor with no urgent need | Schedule a planned upgrade | Allows compatibility and disruption testing |
| Current minor approaching end of support | Raise upgrade priority | Testing time is disappearing |
| Deprecated API blocks target version | Remediate API usage first | Cluster upgrade should not discover manifest failure |
| Operator, CNI, CSI, or ingress controller is incompatible | Upgrade or replace dependency first | Platform dependency can block cluster health |
| PDB cannot be satisfied during drain | Fix replicas or capacity first | Maintenance would stall or reduce availability |
| Recovery state is unknown | Delay non-critical minor upgrade | Version change should not begin without a recovery path |
| Cluster is several minors behind | Plan sequential campaigns | Unsupported version skipping increases risk |
The framework deliberately separates urgency from convenience. “We have a maintenance window next Friday” is not evidence that the cluster is ready. “The current branch is nearing end of support and all target-version blockers are cleared” is evidence.
At Raff, we use the same logic for small-team maintenance: prove compatibility and disruption behavior first, then choose the window. The calendar is the final scheduling step, not the first technical decision.
Recovery planning should not depend on an untested downgrade
Rollback needs a precise definition because several different systems can be rolled back independently.
An application rollback might restore the previous container image or manifest. A data recovery might restore a database or persistent volume from a protected recovery point. A cluster-version recovery is a different problem and depends on the Kubernetes distribution and provider.
Do not make the maintenance plan depend on an untested in-place downgrade.
Instead, define recovery before the window:
- What application version is known good?
- Which Kubernetes manifests or Git revision recreate that version?
- What data must be protected before maintenance?
- Which databases, volumes, and external state need backups or snapshots?
- What user-visible threshold stops the upgrade?
- Who decides to stop, continue, or recover?
- How is a failed worker replaced?
- What provider-specific cluster recovery options exist?
- Which tests prove that recovery succeeded?
The Kubernetes disruption model helps with voluntary maintenance availability, but it is not a data-protection system. Likewise, replicated storage is not automatically a backup.
For stateful services, upgrade readiness should include the same recovery discipline used for any other production change. If the team cannot explain the most recent restorable data point and the expected restore path, the cluster is not ready for a discretionary minor upgrade.
Raff managed Kubernetes reduces platform work but not upgrade readiness
Raff Kubernetes removes much of the control-plane infrastructure work that a small team would otherwise operate itself. Teams can use managed clusters, worker pools, private networking, autoscaling, and built-in baseline monitoring while keeping workload architecture and Kubernetes APIs under their control.
That changes responsibility during an upgrade, but it does not eliminate it.
Raff can operate the managed Kubernetes infrastructure layer. The workload team still needs to verify:
- application and API compatibility;
- third-party controllers and CRDs;
- PodDisruptionBudgets and replica behavior;
- requests and worker capacity during node maintenance;
- storage and stateful workload behavior;
- application-level monitoring and acceptance tests;
- backup and recovery for business data.
The benefit of managed Kubernetes is not that upgrades stop mattering. It is that the team can spend less effort maintaining the control-plane machinery and more effort validating the workload decisions that affect customers.
For broader day-2 ownership, return to Kubernetes Cluster Management for Small Teams. For recovery design around persistent workloads, use Kubernetes Persistent Storage: Volumes, Storage Classes, and Backups.