A Kubernetes upgrade is easier to manage when readiness is treated as a set of verifiable inputs rather than a calendar event. This checklist helps platform teams review API deprecations, version compatibility, workload disruption, backups, add-ons, rollback options, and post-upgrade validation before moving from development to staging and production.
Overview
A cluster upgrade changes more than the Kubernetes control plane. It can affect API availability, admission controllers, cloud integrations, ingress components, storage drivers, observability agents, deployment tooling, and the behavior of workloads that depend on them. The right preparation depends on the target version, the current version, the cluster provider, and the applications running in the cluster.
Use this Kubernetes upgrade checklist to produce a written readiness record for each environment. A useful record should answer five questions:
- Which Kubernetes versions and upgrade paths are supported?
- Which APIs, controllers, and add-ons need changes before the upgrade?
- Can critical workloads tolerate the expected disruption?
- Can the team restore data and recover service if the upgrade fails?
- What evidence will show that the upgraded cluster is healthy?
Do not assume that a successful control-plane operation means the upgrade is complete. Worker nodes, system components, applications, and external integrations all need separate validation.
How to estimate upgrade readiness
Estimate readiness by scoring the major risk areas as ready, needs work, or unknown. “Unknown” should be treated as a blocking condition for production until someone gathers evidence.
| Readiness area | Evidence to collect | Suggested decision |
|---|---|---|
| Version path | Current version, target version, provider-supported paths, and upgrade sequencing | Proceed only when the path is documented |
| API compatibility | Deprecated API usage, manifests, custom resources, and controller support | Convert or remove incompatible objects first |
| Workload disruption | PodDisruptionBudgets, replicas, probes, scheduling capacity, and stateful-service procedures | Test disruption behavior in a non-production environment |
| Data recovery | Recent backups, restore evidence, retention, and ownership | Do not rely on an untested backup |
| Observability | Control-plane, node, workload, and upgrade-event visibility | Confirm alerts and dashboards before the change |
| Rollback or recovery | Provider recovery options, replacement-cluster plan, and forward-fix procedure | Write down the recovery decision before starting |
For a simple estimate, count the number of areas marked “ready” and “needs work,” but do not reduce upgrade approval to a single percentage. A cluster with strong monitoring but an untested database restore is not ready for production. Use the table to expose dependencies, not to conceal them in an average score.
Keep the readiness record with the change request or release plan. This makes assumptions visible to application owners and gives the team a baseline for comparing development, staging, and production.
Inputs and assumptions
1. Confirm the version and upgrade path
Record the current Kubernetes version, the intended target version, the versions of node images or operating systems, and the provider’s documented constraints. Managed Kubernetes services may control the order of control-plane and node upgrades, restrict version-skipping, or require separate maintenance settings. Self-managed clusters have different responsibilities for certificates, control-plane components, node images, and recovery.
Build a compatibility matrix that includes Kubernetes, container runtime, ingress controller, service mesh, CSI and CNI components, autoscaling tools, policy engines, monitoring agents, deployment tools, and custom operators. For each item, record the installed version, target-compatible version, test status, and owner. If an add-on has no clear compatibility statement, test it rather than assuming compatibility.
2. Review Kubernetes API deprecations
API deprecations are a configuration and inventory problem as much as a code problem. Search source repositories, Helm charts, GitOps definitions, generated manifests, admission policies, and automation scripts for API versions that may be removed or no longer served by the target release. Also inspect live objects, because manually created resources can exist outside the main repository.
Review custom resource definitions and the controllers that reconcile them. A CRD may still exist while its controller is incompatible, or a controller may require a migration before the cluster upgrade. Check conversion behavior, stored versions, webhook availability, and whether a failed webhook could block ordinary workload operations.
Validate the revised manifests in a disposable cluster or staging environment. A JSON formatter can help inspect generated payloads and manifests during review; for broader API contract and validation workflows, see the API testing workflow guide. The important result is not merely a clean file—it is evidence that the target cluster accepts and reconciles the resources.
3. Check workload disruption
Review PodDisruptionBudgets for services that must remain available during voluntary disruption. Confirm that replica counts, topology spread rules, node capacity, taints, affinity, readiness probes, and termination behavior allow pods to move. A strict disruption budget combined with insufficient spare capacity can stall a node rotation.
Give special attention to stateful services. Document how volumes are detached and reattached, how leaders or members are replaced, what quorum requires, and how application-level backups are verified. A Kubernetes object backup alone may not be enough to restore application data.
4. Verify backup and recovery inputs
List the data and configuration that must be recoverable: persistent volumes, cluster resources, secrets, external databases, DNS records, certificates, identity integrations, and deployment definitions. Confirm the backup timestamp, retention period, encryption access, restore destination, and responsible operator. Perform a restore test where the risk justifies it, and record the observed recovery time rather than relying on an estimate.
5. Define the recovery decision
A rollback is not always a simple version reversal. Depending on the platform and the failure point, the safer response may be to repair the forward path, replace worker nodes, restore application data, or recover into a separate cluster. Document the signals that trigger a pause, escalation, or recovery action. Include communication owners, change-freeze boundaries, and the last known-good deployment references.
Worked examples
Example A: stateless web application
Assume a web service has multiple replicas, a tested readiness probe, a disruption budget that allows one pod to be unavailable, and enough spare node capacity for rescheduling. Its container image, ingress controller, autoscaler, and deployment automation have been tested against the target version. In this case, the main upgrade risks are API compatibility, ingress behavior, and whether monitoring detects increased error rates.
The smoke-test template might include:
- Confirm nodes report the expected version and become ready.
- Deploy a small test change through the normal delivery path.
- Check service discovery, ingress routing, TLS, and authentication.
- Generate representative requests and compare error and latency behavior with the pre-upgrade baseline.
- Verify logs, metrics, traces, alerts, and autoscaling signals.
Example B: stateful service with an operator
Assume a stateful service is managed by a custom operator and stores data on persistent volumes. Readiness depends on more than node availability. The team must confirm that the operator supports the target Kubernetes version, the CRD is compatible, volume snapshots or backups can be restored, and the service maintains quorum during node replacement.
Here, a reasonable go/no-go rule is that the upgrade does not begin until the operator test, backup restore, and controlled member replacement have all produced evidence. If any of those tests is unknown, the team should treat the upgrade as a recovery exercise rather than a routine maintenance event.
Example C: an API migration is incomplete
Suppose a repository contains manifests using an API version that the target release may remove. The correct response is to update the manifests, verify live objects, test the new version in staging, and check every automation path that creates or patches the resource. Do not solve the problem by changing only the repository file while leaving older live objects or generated templates untouched.
Keep deployment failures and upgrade failures separate during testing. The CI/CD pipeline failure triage playbook can help distinguish runner, artifact, and test issues from cluster-level faults.
When to recalculate
Revisit the Kubernetes upgrade readiness record whenever an input changes. At minimum, update it before each minor-version upgrade and review it on a regular platform-maintenance cycle. Recalculate sooner when the provider changes its supported upgrade paths, the target version changes, an API removal is announced, or a critical add-on releases a compatibility update.
Also repeat the review after major workload changes: adding a stateful system, changing storage, introducing a service mesh, adopting a new policy engine, or moving from manual deployments to GitOps. These changes can alter disruption, recovery, and API-compatibility assumptions even if the Kubernetes version remains unchanged.
After the upgrade, capture the actual duration, interruptions, failed smoke tests, remediation steps, and recovery observations. Turn those findings into the next checklist revision. A practical final sequence is:
- Freeze the target version and record the approved upgrade path.
- Complete API, add-on, workload, backup, and capacity checks.
- Run the same procedure in development or staging.
- Review evidence with application and operations owners.
- Execute the production change with explicit pause and recovery criteria.
- Run smoke tests, monitor the agreed signals, and document the outcome.
That process makes cluster upgrades repeatable without pretending that every environment has the same risk. The checklist should evolve with the cluster, its workloads, and the provider or tooling constraints that shape the upgrade path.