{{ result.summary.heading }}
{{ result.summary.primary }}
{{ result.summary.line }}
{{ badge.label }}
API Control Nodes {{ stage.targetLabel }}
Name the cluster, environment, or upgrade ticket being reviewed.
Choose the compatibility rule set that should gate the upgrade plan.
The calculator flags whether the target must be reached through one-minor hops.
v1.
HA API servers must stay within the selected policy skew while the control plane rolls.
oldest v1.
newest v1.
Enter current minors for the components that talk to the API server load balancer.
controller v1.
scheduler v1.
cloud v1.
Use the full node pool range, including pools paused for drain or surge work.
oldest v1.
newest v1.
Keep this close to node versions unless your platform owns kube-proxy as a managed add-on.
oldest v1.
newest v1.
Use the client used for the maintenance runbook, CI checks, or admin shell.
v1.
{{ result.actionHint }}
Turn this off for clusters that do not run a separate cloud-controller-manager.
Set the largest worker-node batch expected to be unavailable during each node upgrade pass.
nodes
{{ header }} Copy
{{ cell }} 
{{ commandNotes }}
{{ formattedJson }}
Tags: Devops, Sysadmin
Backup Capacity Calculator Size backup repository capacity from source data, retention, copy tiers, reserves, growth, raw overhead, and a live source-to-raw envelope.
Backup Restore Time Calculator Estimate a restore window from backup size, compression, tested throughput, parallel streams, fixed phases, and RTO fit checks.
Ceph Storage Capacity Calculator Estimate Ceph usable capacity from nodes, protection profile, nearfull targets, and failure-domain reserve, with PG and spread checks.
Container Image Pull Time Calculator Estimate container image pull time from image size, cached nodes, changed layers, bandwidth, pull lanes, unpack speed, and retry reserve.
Customize
Advanced
:

Kubernetes upgrades are constrained by version skew: the allowed minor-version distance between the API server and the components that talk to it. A cluster can be healthy today and still block an upgrade if kubelets, kube-proxy, controllers, or kubectl fall outside the target window. The rule is especially important in highly available control planes because API servers are often upgraded one at a time.

The API server is the anchor. Control-plane components must not be newer than the API server instances they can reach. Kubelets and kube-proxy have their own lag windows, and kube-proxy must also stay close to the kubelet on the same node. Kubectl is a client, so it can be one minor version older or newer than the API servers it contacts, but an HA control plane with mixed API server minors narrows that usable client range.

Kubernetes upgrade relationship between API servers, controllers, nodes, and kubectl clients

Skew is not the same as workload compatibility. A component can be inside the supported version window while a workload still uses a removed API, an add-on still needs an upgrade, or a cloud provider requires a stricter sequence. Version skew answers a narrower scheduling question: which components are allowed to run together while the control plane moves from one minor version to the next.

Skipping minor versions is a common planning mistake. Kubernetes upgrade workflows generally move through each minor version and keep control-plane nodes, worker nodes, add-ons, and clients inside the supported window during the transition. Managed platforms may impose tighter windows than upstream policy, especially around node pools and provider add-ons.

A useful skew check records current component ranges before work begins. The oldest and newest API server minors, kubelet range, kube-proxy range, controller versions, and kubectl version all affect whether the target minor is a single rollout, a staged path, or blocked until lagging components are moved.

How to Use This Tool:

  1. Enter a Cluster label that identifies the environment in exported notes.
  2. Choose Policy profile. Use upstream policy for ordinary self-managed checks, stricter managed profiles when your provider runbook requires tighter node or component skew, and lockstep only for platforms that require matching minors.
  3. Set Target control-plane minor. Enter the minor number, such as 36 for v1.36.
  4. Enter the current API server range. In HA clusters, use the oldest and newest API server minors that can receive traffic.
  5. Fill in Control-plane components, Current kubelet range, Current kube-proxy range, and kubectl client minor.
  6. Open Advanced if cloud-controller-manager is in scope or if the node upgrade batch size should be reflected in the order notes.
  7. Review Skew Matrix first. Then use Upgrade Order, Compatibility Chart, Policy Notes, and Command Notes as the evidence trail for a maintenance plan.

If the matrix shows blocked rows, resolve those component versions before scheduling the target API server rollout. A staged-hop warning means the target is more than one minor above the newest current API server, so plan each intermediate minor.

Interpreting Results:

Skew Matrix is the authority for the current inputs. Each row compares a component's current range with the allowed range during the target rollout and the expected range after API convergence. A pass means the whole current range fits. A warning means the range overlaps but not every instance is safely inside. A failure means at least one version must move before the target rollout.

  • kube-apiserver failure usually means the HA API server range is already too wide or the target is older than the newest current API server.
  • kubelet failure means nodes are too old for the target API window or newer than an API server they may contact.
  • kube-proxy failure can come from either API-server skew or its separate relationship to the node's kubelet.
  • kubectl warnings are often operational rather than cluster-fatal, but they matter for automation and administrator workstations that contact mixed API server minors.
  • Policy Notes names the active profile and whether the legacy node guard narrowed the allowed lag for versions below v1.25.

A clean skew matrix does not approve the whole upgrade. Still check release notes, deprecated APIs, add-ons, etcd support, backups, platform runbooks, and workload disruption limits before the maintenance window.

Technical Details:

The model treats each component as either a single minor or a range of minors. Ranges are necessary because HA control planes and node pools commonly contain mixed versions during upgrades. The allowed window is derived from the target API server rollout window and the selected policy profile.

During an HA rollout, the target API window may include the previous and target minor while API servers are upgraded one at a time. Components that can talk to any API server behind a load balancer must be valid against the oldest reachable API server, not only the newest target server.

Rule Core:

Allowed component windows are built from the API range and the policy lag values.

Allowedcomponent = [ max(1,APInewest-Lag) , max(1,APIoldest+ForwardLag) ]
Component Upstream rule reflected in the check Planning consequence
kube-apiserver Newest and oldest HA API servers must stay within one minor version. Upgrade control-plane nodes one at a time without widening the API range beyond the profile limit.
kube-controller-manager, kube-scheduler, cloud-controller-manager Must not be newer than reachable API servers and may be one minor older under upstream policy. When these components use a load balancer, the oldest API server can narrow the allowed version.
kubelet Must not be newer than API servers and may trail by the profile's node lag. Oldest nodes can block a target API rollout before the newest nodes do.
kube-proxy Follows API-server skew and must remain close to the kubelet on the same node. Check both the API window and node relationship before changing add-ons or node pools.
kubectl May be one minor older or newer than every API server it contacts. Mixed API server versions can reduce the safe client range during a live rollout.

Range comparison uses three outcomes. A component passes when its oldest and newest minors are both inside the allowed window. It warns when the current range overlaps the allowed window but includes out-of-window instances. It fails when there is no safe overlap or when another hard rule, such as API HA skew, is violated.

Checkpoint Technical reason Evidence to collect
Inventory Allowed windows depend on actual component ranges, not only the desired target. API server images, controller and scheduler versions, node kubelet versions, kube-proxy version, and kubectl version.
Preflight each minor Skipping minor versions is unsupported in common kubeadm workflows and can miss removed APIs. Release notes, deprecated API checks, add-on compatibility, and backups.
Control plane first API server version controls the allowed windows for components that communicate with it. One-node-at-a-time control-plane upgrade plan and health checks.
Nodes after API Kubelet versions are allowed to lag but not run newer than the API server. Drain plan, node batch size, readiness checks, and workload capacity.

For example, targeting v1.36 from API servers at v1.35 gives a rollout API window of v1.35 to v1.36 under a one-minor HA profile. With upstream node lag of three minors, kubelets in v1.33 to v1.36 can fit the target window, but a managed one-minor profile would narrow that node window to v1.35 to v1.36.

Limitations:

This checker covers version skew only. It does not inspect live cluster objects, provider constraints, add-on release notes, image registries, etcd versions, admission webhooks, CRDs, storage drivers, or workload disruption budgets.

  • Use deprecated API checks before each minor hop, especially for older clusters.
  • Follow managed-service runbooks when they are stricter than upstream policy.
  • Back up critical state and verify rollback or recovery procedures before changing the control plane.

Worked Examples:

Single-hop upstream upgrade. API servers at v1.35 targeting v1.36 with kubelets at v1.33 to v1.35 should usually fit upstream node skew. Skew Matrix should show the target rollout window and Upgrade Order should begin with preflight and one-at-a-time API server work.

Managed one-minor node policy. The same cluster can warn or fail under a stricter managed profile if kubelets at v1.33 are too old for a v1.36 target. The fix is to move nodes closer to the API version before or during the staged rollout according to the provider runbook.

Skipped target minor. If the newest API server is v1.34 and the target is v1.36, Policy Notes should show a staged target. Plan v1.35 first, verify health and deprecated APIs, then repeat the process for v1.36.

FAQ:

Can a clean skew matrix still hide upgrade risk?

Yes. The matrix checks component version windows only. Deprecated APIs, CRDs, admission webhooks, add-ons, provider limits, and workload disruption still need separate review.

Why does HA API server skew narrow other windows?

Components behind a load balancer may contact the oldest or newest API server. They must be valid against every API server they can reach, so a mixed API range narrows the safe component range.

Why did kube-proxy fail when kubelet passed?

Kube-proxy is checked against both the API server window and the kubelet on the same node. It can fail the node relationship even when kubelets fit the API window.

What should I do with a staged-hop warning?

Plan each intermediate minor. Use Upgrade Order for the next hop, then rerun the check after the cluster is healthy at that minor.

Glossary:

Minor version
The middle number in a Kubernetes version such as v1.36.
Version skew
The supported difference between component minor versions while they operate together.
API server range
The oldest and newest kube-apiserver minors reachable during an HA rollout.
Target rollout window
The allowed API server range while moving toward the selected target minor.
Legacy node guard
The narrower node and kube-proxy lag rule applied when versions below v1.25 are in scope.

References: