Kubernetes Version Skew Policy and Upgrade Planning Guide

Overview

If you run Kubernetes for more than a few months, upgrades stop being a one-time task and become recurring operational work. That is why the Kubernetes version skew policy matters: it defines which component versions can safely coexist while you move a cluster from one minor release to another.

The policy is simple in principle but easy to misapply under pressure. A team may know that a cluster is “going to 1.36” and still hit avoidable problems if they upgrade nodes before the control plane, let kubelets drift too far behind, or overlook the narrower compatibility window that appears in high-availability control planes during rolling updates.

At a high level, the official policy describes supported version skew between the Kubernetes control plane and key node components. The most important rules from the current Kubernetes guidance are:

• Supported branches: the project maintains release branches for the most recent three minor versions.
• Patch support: Kubernetes 1.19 and newer generally receive about one year of patch support.
• HA kube-apiserver skew: in a highly available cluster, the newest and oldest kube-apiserver instances must be within one minor version.
• kubelet skew: a kubelet must never be newer than the kube-apiserver, and it may be up to three minor versions older in modern supported ranges. Older kubelet lines before 1.25 had a narrower two-minor-version allowance.
• kube-proxy skew: kube-proxy also must not be newer than the kube-apiserver, and it may generally be up to three minor versions older, with older pre-1.25 versions subject to the narrower two-minor-version rule.

The practical implication is that upgrade planning is not just about choosing a target version. It is about choosing a sequence that keeps every intermediate state supported.

This matters even more in managed or opinionated environments, because the upstream skew policy is only the baseline. Your cluster deployment tool, cloud provider, or distribution may impose stricter rules. The safest evergreen interpretation is: start with the upstream policy, then check whether your platform narrows it further.

Core framework

The easiest way to use the Kubernetes version skew policy is to think in terms of a repeatable framework: inventory, support window, upgrade order, compatibility checks, and rollback posture. That gives you a process you can revisit for every minor release.

1. Inventory every version that matters

Before planning any upgrade, collect the current versions of:

• kube-apiserver
• kube-controller-manager
• kube-scheduler
• etcd if you manage it directly
• kubelet on all node pools
• kube-proxy
• cluster add-ons such as CNI, CSI, ingress controllers, metrics-server, and admission webhooks
• deployment tooling such as kubeadm, managed service control plane versions, or GitOps automation assumptions

The skew policy focuses on core Kubernetes components, but outages often come from adjacent dependencies. A cluster can be technically within upstream skew rules and still fail because a CNI plugin or webhook does not support the target API behavior.

2. Confirm your support window

The Kubernetes project maintains the most recent three minor release branches. That means staying close to current releases is not just a best practice for features; it is also the easiest way to remain in a supported patch stream.

For evergreen planning, use this rule of thumb: if your cluster is more than two minor versions behind current stable, you should treat upgrade scheduling as an operational priority. Waiting too long reduces your room to move, increases the chance that one skipped check turns into several chained upgrades, and makes API deprecations more painful.

It also helps to separate patch upgrades from minor upgrades:

• Patch upgrades move within a minor line, such as 1.35.x to a newer 1.35.y. These are usually lower risk and should be routine.
• Minor upgrades move between lines, such as 1.35 to 1.36. These are where version skew rules matter most.

3. Follow the safe upgrade order

For most clusters, the safest default order is:

1. Read release notes and deprecation notices for the target version.
2. Validate platform-specific constraints from your provider or installer.
3. Upgrade control plane components first.
4. Upgrade node-level components next, especially kubelet and kube-proxy.
5. Upgrade add-ons and ecosystem components that depend on API compatibility.
6. Only then remove compatibility shims or old APIs from your manifests.

That order aligns with the core skew rule that node agents must not be newer than the API server. In other words, do not lead with nodes. The control plane establishes the version ceiling, and nodes follow.

4. Account for HA narrowing during rolling control plane upgrades

This is the point many teams miss. In a highly available control plane, not every kube-apiserver instance upgrades at the same moment. During the rollout, the cluster may temporarily run mixed API server minor versions, and the newest and oldest API server instances must remain within one minor version.

That mixed state narrows the effective compatibility range for node components. The official example is useful: if some API servers are on 1.36 and others remain on 1.35 during the rollout, a kubelet at 1.36 is not supported because it would be newer than the 1.35 API server instance it might talk to. In that temporary state, supported kubelet versions would be 1.35, 1.34, and 1.33.

The planning lesson is straightforward: in HA clusters, design for the oldest currently active API server, not the highest target version.

5. Treat API compatibility as part of upgrade planning

Version skew policy tells you whether core binaries can coexist. It does not guarantee your workloads and integrations are ready. Before a minor upgrade, review:

• removed or deprecated APIs used by manifests
• admission controllers and policy engines
• custom resource definitions and controllers
• monitoring agents scraping control plane or kubelet endpoints
• authentication and identity integrations

This is where broader platform concerns meet Kubernetes operations. For example, clusters that rely on workload identity, OIDC, or external authorization hooks should include identity-related smoke tests in every upgrade plan. If identity is part of your platform model, it is worth pairing this guide with a review of workload identity patterns so control plane changes do not surprise downstream auth flows.

6. Define the rollback boundary before you begin

A good upgrade plan includes a clear answer to: what happens if this phase fails? For patching worker nodes, that may be as simple as draining and replacing a canary node pool. For control plane changes, rollback may depend on the capabilities of your managed provider or provisioning tool.

In practice, rollback is easiest when you upgrade in small steps, keep the cluster within supported skew at every stage, and validate after each move rather than after the whole program is complete.

Practical examples

The policy becomes easier to remember when you turn it into real upgrade paths.

Example 1: Single-instance control plane from 1.35 to 1.36

Suppose a small internal cluster runs:

• kube-apiserver 1.35
• kubelet 1.34 on all nodes
• kube-proxy 1.34

This cluster is in a reasonable state before the upgrade. Since kubelet and kube-proxy are older than the API server but still within the supported skew, the safe plan is:

1. Upgrade the control plane to 1.36.
2. Verify API health, scheduler behavior, and critical workloads.
3. Upgrade kubelets and kube-proxy to 1.36, or to 1.35 first if your process stages nodes separately.
4. Patch everything to the latest 1.36.x after validation.

What you should not do is upgrade kubelets to 1.36 while the API server is still on 1.35, because kubelets must not be newer than the API server.

Example 2: HA control plane rollout with mixed API server versions

Now consider a three-control-plane-node cluster. You begin upgrading from 1.35 to 1.36. Midway through the rollout:

• two kube-apiserver instances are 1.36
• one kube-apiserver instance is still 1.35

This state is supported because the newest and oldest API servers are within one minor version. But your node version options are constrained by the oldest API server still present. That means:

• kubelet 1.36 is not yet a safe fleet-wide target
• kubelet 1.35, 1.34, and 1.33 remain within the supported envelope

The operational takeaway is to finish the API server rollout first, then move node agents. This is one of the clearest examples of why Kubernetes upgrade order matters.

Example 3: Aging worker nodes lagging behind the control plane

Imagine the API server is already at 1.36, but one old node pool still runs kubelet 1.32. Based on the current upstream rule, a kubelet may be up to three minor versions older than the API server, so 1.33 would be the lower bound in this case. A 1.32 kubelet would fall outside the supported skew.

Even if the node appears healthy, you should treat that configuration as overdue for remediation. Unsupported skew is not the same as immediate failure, but it means you have moved outside the tested compatibility range.

Example 4: Distribution-specific restrictions

Many managed Kubernetes services and enterprise distributions intentionally restrict supported upgrade paths more than upstream Kubernetes does. For example, they may require sequential minor upgrades, limit temporary skew during managed rollouts, or tie add-on versions to specific cluster versions.

The evergreen rule here is simple: if upstream says a state is supported and your platform says it is not, follow the platform. Upstream policy defines general component compatibility; your provider defines what it will actually operate and support.

Example 5: Add-on breakage despite valid skew

Suppose your control plane and nodes all follow the skew policy correctly, but after the upgrade your ingress controller fails because it still references a removed API version. That is not a contradiction. It means binary skew support was valid, but workload and add-on API compatibility was not addressed.

This is why mature upgrade runbooks combine version checks with manifest scanning, webhook validation, and observability review. Teams that already invest in strong telemetry and controlled rollouts tend to catch this class of problem earlier. If your platform work includes reliability-sensitive pipelines, the same habits described in observability-heavy architectures, such as those discussed in cloud networking and observability patterns, are useful during cluster upgrades too.

Common mistakes

Most Kubernetes upgrade incidents are not caused by obscure edge cases. They come from a few repeatable planning errors.

Upgrading nodes before the control plane

This is the most direct violation of the skew policy. Since kubelets and kube-proxy must not be newer than the API server, node-first upgrades create unsupported states immediately.

Ignoring the temporary mixed-version state in HA clusters

Teams often plan for the beginning and end state only. In reality, the riskiest point is the middle of a rolling control plane upgrade, when different API server instances serve different minor versions. During that window, the oldest API server still governs what node versions are allowed.

Using “supported” to mean “risk-free”

The skew policy tells you what versions may coexist. It does not promise that your CRDs, admission webhooks, sidecars, CNI, CSI, or deployment tooling are all ready. Support boundaries are necessary, but they are not the whole upgrade plan.

Letting clusters fall too far behind

When teams delay minor upgrades for too long, every future upgrade becomes harder. API removals stack up, dependent tools drift, and the path back to current releases may require multiple tightly scheduled maintenance windows.

Forgetting patch hygiene

Minor versions get the attention, but patch cadence matters too. Because Kubernetes maintains only the most recent three minor branches and newer versions generally receive about a year of patch support, staying current on patches reduces both security exposure and operational surprise.

Skipping post-upgrade validation

A successful version bump is not the same as a successful platform upgrade. Validate node registration, DNS, networking, storage mounts, autoscaling, admission control, observability pipelines, and workload identity flows. In regulated or private environments, this kind of disciplined verification aligns well with broader operational controls seen in private cloud operating models.

When to revisit

The best Kubernetes upgrade guides are living documents. Revisit your version skew assumptions whenever one of the inputs changes, not just when a maintenance ticket appears.

Update your plan when:

• a new Kubernetes minor release becomes available
• the official version skew policy changes
• your provider or distribution changes its supported upgrade paths
• you introduce or replace core add-ons such as CNI, CSI, ingress, or policy engines
• you add new admission webhooks, CRDs, or identity integrations
• your cluster topology changes, especially from single control plane to HA
• you discover worker node pools are drifting across different minor versions

For a practical operating rhythm, keep a short checklist in your runbook:

1. Monthly: review current cluster versions, patch levels, and end-of-support proximity.
2. Before each minor upgrade: read upstream release notes, check skew policy, and verify provider-specific restrictions.
3. Before change approval: confirm upgrade order, canary scope, rollback boundaries, and validation tests.
4. After upgrade: record the final component matrix and any add-on issues discovered.
5. Quarterly: review whether your runbook still matches current Kubernetes policy and platform tooling.

If you want one practical habit to keep, make it this: maintain a simple version matrix for every cluster. List the API server, kubelet, kube-proxy, add-ons, and the intended next target version. That one document turns the Kubernetes version skew policy from a page you search during incidents into an operational control you can use confidently.

Kubernetes does not require perfectly uniform versions at every moment, but it does require disciplined sequencing. Respect the supported skew rules, upgrade the control plane before the nodes, assume the oldest active API server sets the limit in HA rollouts, and validate the surrounding ecosystem rather than only the core binaries. Do that consistently, and upgrades become routine maintenance instead of high-stakes troubleshooting.