Kubernetes Upgrade Skew Calculator

A Kubernetes upgrade changes several cooperating programs, not one cluster-wide version. API servers, controller managers, schedulers, kubelets, kube-proxy instances, and maintenance clients can temporarily run different minor releases. Version-skew policy defines which combinations are supported during that transition.

The versions that can communicate matter more than the label attached to one node. In a highly available control plane, an old and a new API server may both sit behind the same endpoint. A controller or kubectl client that can reach either server must fit both servers' support windows, which is narrower than checking only the newest instance.

Compatibility is only one upgrade gate. Deprecated APIs, admission webhooks, etcd, Container Network Interface and Container Storage Interface plugins, CoreDNS, backups, rollback, workload disruption, capacity, and provider-specific rules can block an upgrade even when every component version is in range.

Minor releases must be upgraded one at a time. Patch versions matter for security and bug fixes, but this calculation compares only the minor number after v1.. Use the latest supported patch in the current and target minor when planning the actual maintenance.

How to Use This Tool:

Inventory the versions that are actually reachable or deployed, then evaluate only the next minor hop.

1. Choose Upstream Kubernetes policy unless a provider runbook imposes a stricter limit. The managed one-minor and lockstep profiles are planning overlays, not universal Kubernetes rules.
2. Enter the Final control-plane target as a minor number such as 36 for v1.36. Enter the oldest and newest reachable API server minors to represent the mixed high-availability window.
3. Add the controller-manager and scheduler minors, then the oldest and newest kubelet and kube-proxy minors. Include cloud-controller-manager only when it is a separate deployed component.
4. Enter the maintenance kubectl minor and an optional node drain batch. The batch value affects the generated sequence, not the compatibility verdict.
5. Stop when any matrix row is Blocked. Resolve its stated version action and rerun the check before changing an API server; review partial rows and provider rules before treating a ready result as approval to upgrade.

Interpreting Results:

Next-hop upgrade gate describes the immediately executable minor transition, even when the final target is farther away. Ready means every entered range fits that hop; Staged means the entered versions fit but more than one sequential hop remains.

• Review means at least one deployed range overlaps the allowed window without fitting completely.
• Blocked means one or more components have no acceptable fit under the selected profile. Upgrade or constrain those components before the API hop.
• A green kube-proxy row is based on aggregate ranges. Verify each kube-proxy against the kubelet on the same node before maintenance.
• A compatible matrix does not prove that workloads, add-ons, deprecated APIs, backups, or rollback plans are ready.

Technical Details:

The version-skew calculation treats every component as a closed interval of minor versions. Support is the intersection of the intervals allowed by every API server that the component may contact. This makes a mixed API-server rollout narrower than a steady-state cluster.

Rule Core

For a reachable API interval from a_old through a_new, lag allowance L, and forward allowance F, the shared component interval is:

Forward allowance is zero for controllers, kubelets, and kube-proxy because they cannot be newer than the API server. It is one for kubectl. A current interval wholly inside the allowed interval is Ready; any overlap is Partial; no overlap is Blocked.

The next target is the lesser of the final target and one minor above the newest current API server. The rollout API window spans that next target and the permitted older API minor, unless every API server is already on the target. A final target two minors ahead therefore yields two hops rather than one skipped upgrade.

kube-proxy receives two checks. Its aggregate range is compared with both the API-derived interval and a conservative kubelet envelope from newest kubelet − allowed pair lag through oldest kubelet + allowed pair lag. A full fit is required for Ready; partial overlap produces Partial. Aggregate minima and maxima cannot prove every node-local pair, so the per-node relationship remains a required manual check.

The last two profiles are deliberately stricter repo-authored overlays. Provider support policies can be stricter still. The final gate becomes Blocked when any row is blocked, Review when none is blocked but at least one is partial, Staged when all rows fit and multiple minor hops remain, and Ready otherwise.

Limitations:

This is a version-policy check based on entered inventory. It does not connect to a cluster or inspect patch versions, workloads, APIs, or provider controls.

• Confirm the current upstream policy and the platform's supported upgrade path before every maintenance window.
• Inventory versions from all reachable API servers and every node pool; an omitted old instance can make a safe-looking interval wrong.
• Review release notes, API removals, webhooks, etcd, CNI, CSI, CoreDNS, backups, capacity, disruption budgets, and rollback separately.
• Drain nodes before minor kubelet upgrades and verify workload health between approved batches.

Worked Examples:

References:

• Kubernetes Version Skew Policy, Kubernetes.
• Upgrading kubeadm clusters, Kubernetes.
• Kubernetes API deprecation guide, Kubernetes.
• How to cordon and drain a Kubernetes node, Simplified Guide.