A Kubernetes upgrade is safer when treated as a compatibility exercise rather than a single maintenance command. This readiness checklist helps platform teams review cluster versions, deprecated APIs, workloads, add-ons, storage, security controls, backups, and rollback plans before changing production. Use it for each minor-version step, then repeat the same checks in a staging environment that resembles the target cluster.
Overview
A cluster upgrade can affect more than the control plane and worker nodes. Applications may still reference removed API versions, admission webhooks may reject new objects, a storage driver may require a different Kubernetes version, or an ingress controller and Helm chart may depend on behavior that changes during the upgrade.
The safest approach is to create a version-specific upgrade record containing:
- Current Kubernetes version and target version.
- Cloud-provider or distribution prerequisites.
- Supported control-plane and node-version combinations.
- Deprecated and removed API usage.
- Critical add-on and CRD compatibility.
- Backup evidence and a tested recovery procedure.
- Health indicators, maintenance windows, owners, and rollback actions.
Do not assume that a minor-version upgrade can safely skip intermediate versions. Follow the supported upgrade path for your managed Kubernetes service or distribution. Kubernetes release support windows, API removals, provider prerequisites, and add-on matrices change over time, so record the documentation version used for each upgrade decision.
How to estimate upgrade readiness
Use a simple readiness score to turn a broad review into a repeatable decision. This is not a substitute for testing, but it makes unresolved risk visible.
For each check, assign one of three states:
- Ready: evidence exists and the check passed in the intended environment.
- Conditional: a workaround, maintenance step, or owner is documented.
- Blocked: compatibility is unknown, a dependency is unsupported, or recovery has not been verified.
You can calculate a basic readiness percentage as:
readiness = ready checks / total required checks × 100
Keep blocked checks separate from the percentage. A cluster with many low-risk checks marked ready may still be unsuitable for production if its backup restore, storage driver, or critical admission webhook is unverified. Define mandatory gates before scheduling the upgrade. Typical gates include a tested backup, a documented target version, no unresolved removed-API usage, a compatible node image, healthy control-plane and workload metrics, and a staging result that meets the team’s rollback criteria.
Break the change into stages: audit, remediate, test, upgrade a non-production cluster, upgrade a small production slice if possible, and then expand. This staged workflow reduces the amount of traffic and state exposed to an unproven change.
Inputs and assumptions
Version and provider inputs
- Write down the current control-plane, node, and client versions. The client version alone does not describe cluster compatibility.
- Confirm the provider’s supported upgrade sequence, maintenance behavior, node-image requirements, and any restrictions on control-plane or node skew.
- Check whether the target version changes default behavior, feature gates, admission behavior, or networking assumptions used by your workloads.
- Use a version-by-version matrix rather than a single statement that an add-on is “Kubernetes compatible.”
| Area | What to verify | Evidence to keep |
|---|---|---|
| APIs | Deprecated or removed versions used by manifests, templates, or operators | Scan output and remediation pull requests |
| Nodes | Supported node images, runtime, kernel, labels, taints, and capacity | Provider matrix and node-pool plan |
| Admission | Webhook service health, certificates, timeouts, and failure policies | Webhook inventory and staging test |
| CRDs | CRD schema, conversion webhooks, stored versions, and operator support | CRD export and vendor compatibility statement |
| Networking | CNI, DNS, ingress or Gateway components, network policies, and load balancers | Connectivity tests and component versions |
| Storage | CSI driver, snapshot support, volume expansion, and reclaim behavior | Restore test and storage-driver documentation |
| Workloads | Probes, resource requests, autoscaling, PDBs, and rollout behavior | Workload test results and capacity plan |
| Recovery | Control-plane or object backup, persistent-data recovery, and runbook ownership | Recent restore evidence and timed procedure |
Audit deprecated APIs before the upgrade
Start with manifests in Git, Helm values, Kustomize overlays, and generated deployment output. Then compare those findings with live objects. Tools that inspect server resources can identify API versions currently served or stored by the cluster; use the tool’s documentation for the exact command and version support rather than copying an outdated command into production.
Useful checks include:
kubectl api-resources
kubectl get --raw /openapi/v2 > openapi.json
kubectl get crd
kubectl get validatingwebhookconfiguration,mutatingwebhookconfiguration
These commands provide inventory, not a complete deprecated-API audit. Pair them with a dedicated deprecated-API scanner, admission or audit logs, CI manifest validation, and a review of controller documentation. Search repositories for old apiVersion values, but do not treat text search as proof that a live object is safe or unsafe.
Review workloads and add-ons
Check deployments, StatefulSets, DaemonSets, Jobs, and critical custom resources for readiness and liveness behavior. Verify that resource requests allow the scheduler to place replacement pods during node rotation. Review PodDisruptionBudgets: a restrictive budget can prevent voluntary evictions, while an overly permissive policy can reduce availability during maintenance.
Inventory ingress controllers, Gateway API implementations, DNS, metrics and logging agents, service meshes, autoscalers, policy engines, secrets integrations, image pull components, and backup operators. For each one, record the installed version, target-cluster support, required CRDs, webhook dependencies, and upgrade order. A Helm release review should include rendered manifests, values, hooks, CRD handling, and rollback behavior. For related chart checks, see the Helm chart review checklist.
Worked examples
Example 1: API compatibility blocks the plan
A team plans to move one minor version forward and discovers that a release manifest still emits an older API version. The correct response is not to hide the warning or proceed because existing pods look healthy. Update the chart or manifest, render it in CI, apply it to staging, and confirm that existing resources can be read and managed through the supported API. If a custom resource has conversion or stored-version concerns, involve the operator owner before touching production.
Example 2: Node rotation exposes capacity risk
A cluster appears healthy, but its workloads use nearly all available capacity and several deployments have strict disruption budgets. During a node upgrade, evicted pods cannot be scheduled. The readiness review should identify spare capacity requirements, temporarily adjust capacity or workload placement where appropriate, and test node drain behavior. Validate critical services after each node-pool stage instead of assuming that a successful drain means the application remained healthy.
Example 3: Add-on compatibility is conditional
An ingress controller supports the target Kubernetes version, but its chart also installs a CRD and an admission webhook. The team records the controller as conditional rather than ready until it tests CRD installation, webhook certificate rotation, traffic routing, and rollback in staging. The same method applies to CSI drivers, autoscalers, policy engines, and service meshes: verify the complete dependency chain, not just the headline component version.
Example 4: Recovery changes the go or no-go decision
A backup job reports success, but the team has never restored a representative application with its persistent data and secrets. The upgrade remains blocked. Run a restore into an isolated environment, verify object relationships and data integrity, measure the procedure, and assign an owner for each recovery step. A backup that cannot be restored within the required operational window is not sufficient evidence of rollback readiness.
When to recalculate and revisit the checklist
Recalculate readiness for every Kubernetes minor-version change, provider maintenance event, node-image change, and major add-on upgrade. Revisit it after a failed staging upgrade, a new operator or CRD installation, an ingress or storage migration, a change to admission policy, or a material change in workload capacity and disruption settings.
At least twice a year, review the checklist even if no upgrade is scheduled. Confirm that links, supported-version assumptions, deprecated-API scans, backup tests, and cloud-provider prerequisites still reflect the environments you operate. Refresh the document whenever the upstream release documentation or a provider compatibility matrix changes.
Before approving production, attach evidence to the change record: the version matrix, API audit, add-on inventory, rendered manifests, staging results, monitoring plan, backup restore result, maintenance communication, and rollback decision tree. During the upgrade, pause after each stage to check control-plane health, node readiness, scheduling, error rates, API latency, storage operations, ingress traffic, and application-level signals. If a gate fails, stop at the current stage and use the documented recovery procedure rather than improvising under pressure.
For the surrounding platform work, pair this checklist with a Gateway API and Ingress migration review, a secrets-management assessment, and your organization’s IAM access review. A Kubernetes upgrade is complete only when the cluster, its add-ons, and the workloads that depend on them are all operating against the intended compatibility assumptions.