Kubernetes upgrades are safest when treated as a compatibility and recovery exercise, not simply a version change. This guide provides a reusable method for checking support status, selecting a target release, finding deprecated APIs, validating add-ons, preparing backups, and deciding whether a rollback plan is realistic before maintenance begins.
Overview
Kubernetes version support has several layers. The upstream project publishes minor releases and eventually ends maintenance for older ones, while a managed Kubernetes provider, operating-system vendor, or platform team may impose a different support window. A cluster can therefore be technically capable of running a version while still being outside the support policy that applies to your organization.
Start by recording four separate values:
- Current control-plane version: The Kubernetes version running the API server and other control-plane components.
- Current node versions: Worker nodes may not all be on the same patch or minor version during a rolling upgrade.
- Target version: The release you intend to run after the change, including its patch level if already selected.
- Support source: The upstream Kubernetes release information plus the support policy for your cloud provider, distribution, or internal platform.
Do not rely on a static version table copied into a runbook. Release dates, end-of-support dates, provider policies, and upgrade tooling change. Maintain a small internal matrix with columns for minor version, release date, upstream maintenance status, provider support status, current cluster count, and planned upgrade date. Verify each row against the relevant official release and platform documentation before using it for a production decision.
For a first inventory, compare the server and client views rather than assuming they match. Commands such as kubectl version and your provider or distribution’s cluster-version command can reveal different versions. The kubectl client is not the source of truth for the control plane, and a successful client connection does not prove that workloads or add-ons are compatible with a proposed target.
Checklist by scenario
Before choosing a target version
- Confirm the current control-plane and node versions.
- Check the upstream Kubernetes release and support information.
- Check the support window and upgrade path for your managed service or distribution.
- Confirm whether the platform permits direct movement to the target or requires sequential minor upgrades.
- Review the target release notes, known issues, and any provider-specific prerequisites.
- Choose a patch release that is supported by your platform and compatible with your operational tooling.
Before upgrading an existing production cluster
- Export a current inventory of namespaces, deployments, stateful workloads, custom resources, admission webhooks, and scheduled jobs.
- Search manifests, Helm charts, Git repositories, and generated YAML for APIs removed or changed between the current and target versions.
- Test the target version in a development or staging cluster with representative workloads.
- Validate the compatibility of the Container Network Interface, Container Storage Interface drivers, ingress controller, service mesh, monitoring stack, policy engine, autoscalers, and backup software.
- Confirm that image registries, certificate automation, identity integrations, and admission controllers remain reachable and supported.
- Take and test a control-plane data backup according to the platform’s documented procedure. A backup that has never been restored is an assumption, not a recovery plan.
- Define maintenance ownership, communication steps, success criteria, abort criteria, and an observation period after the change.
For a managed Kubernetes service
Separate the provider’s control-plane operation from the work your team still owns. The provider may upgrade or operate control-plane components, but your team may remain responsible for node pools, workload disruption budgets, storage drivers, ingress components, and application behavior. Read the provider’s version-skew, node-upgrade, maintenance-window, and deprecation documentation. Confirm whether node pools upgrade automatically, require replacement, or can be rolled back independently.
For self-managed Kubernetes
Document the exact installation method and configuration source before changing anything. If the cluster uses kubeadm, review the output of its upgrade-planning command and follow the version-specific sequence in the official documentation. For other distributions, use that distribution’s supported procedure instead of mixing commands from unrelated installation methods. Preserve the configuration for certificates, networking, storage, runtime settings, and control-plane endpoints before beginning.
What to double-check
Deprecated and removed APIs
An object can continue running even when its API version is no longer accepted for new or updated requests. Inspect live objects and source manifests separately. Look for Ingress, autoscaling, policy, batch, admission, and custom-resource definitions because API changes often affect these areas. Use a version-aware scanner or audit tool where appropriate, but verify findings against the target release documentation. A scanner’s output is a starting point; it may miss generated resources or objects managed outside the repository.
Extension and add-on compatibility
Build a compatibility sheet for every component that interacts with the API server or node runtime. Record its installed version, target-compatible version, upgrade order, owner, and recovery method. Pay particular attention to webhooks: an unavailable or incorrectly configured webhook can block ordinary deployment and deletion operations. Also confirm that CRD versions, conversion webhooks, storage drivers, and monitoring agents support the target release.
Workload disruption and storage
Review replica counts, readiness probes, PodDisruptionBudgets, topology rules, anti-affinity, and capacity headroom. A rolling node upgrade can expose scheduling assumptions that are invisible during normal operation. For stateful applications, confirm the provider’s rules for volume attachment, zone placement, snapshots, and failover. Do not treat a replicated application as automatically recoverable without testing its restoration process.
Rollback reality
Control-plane rollback is not always a simple version reversal. Database schema changes, CRD changes, persistent data writes, and add-on migrations can make a downgrade unsafe or unsupported. Define what “rollback” means before the upgrade: stopping at the current step, replacing a node pool, restoring a cluster backup, redeploying workloads, or invoking a provider recovery process. If the chosen platform does not support a direct downgrade, use a tested recovery or rebuild strategy instead.
Common mistakes
- Choosing only by age: The newest available version may not be the right target if add-ons, policies, or provider support lag behind it.
- Checking only running pods: Jobs, CronJobs, CRDs, admission configurations, and stored objects can fail later when they are updated.
- Upgrading nodes before validating the control plane: Follow the supported sequence for the chosen platform and respect version-skew limits.
- Ignoring patch-level differences: Patch releases can contain important fixes and may be the only versions approved by a provider.
- Treating a successful upgrade as the end: Review events, API-server errors, controller logs, node conditions, workload latency, failed jobs, and backup status afterward.
- Using an untested backup as a rollback plan: Schedule a restore exercise before the maintenance window when the cluster supports critical services.
- Updating manifests without updating their owners: Record the repository, team, release process, and alerting contact for every changed API or add-on.
For image and runtime compatibility, also review the container images used by cluster components and workloads. A base-image change can introduce separate operating-system, certificate, shell, or runtime differences; keep that work distinct from the Kubernetes version change where possible. See How to Choose a Container Base Image for a broader image-selection checklist.
When to revisit
Review this plan at least monthly for production clusters, before seasonal traffic or change freezes, and whenever Kubernetes or your platform provider publishes a minor release, support announcement, deprecation notice, or upgrade-tool change. Revisit it immediately after adding a major add-on, changing storage or networking, moving to a new provider, or discovering a failed restore test.
Before each upgrade, complete this short action list:
- Refresh the current-versus-target version matrix from authoritative release and provider documentation.
- Run a version-aware API and manifest audit, then assign every finding to an owner.
- Confirm add-on compatibility, node capacity, disruption settings, and maintenance timing.
- Take a verified backup and write down the recovery procedure, not just the backup location.
- Test the target in a representative environment and record measurable success and abort criteria.
- After production changes, monitor control-plane health, nodes, storage, networking, workloads, and user-facing service indicators before closing the change.
This checklist should remain a living operational document. The safest Kubernetes upgrade decision is the one based on the versions, APIs, extensions, recovery options, and support policies that exist at the time of the change.
