Kubernetes component version skew policy: how far apart component versions can be in a supported cluster
The maximum version difference Kubernetes supports between cluster components, one record per governed component pair (kube-apiserver to kubelet, kube-proxy, kubectl, and the kube-controller-manager/kube-scheduler/cloud-controller-manager group, plus the kube-apiserver-to-kube-apiserver HA rule and the kube-proxy-to-kubelet rule), from the project's own version-skew-policy page. Answers 'how many minor versions behind can my kubelet be', 'can kubectl be newer than kube-apiserver', 'what must already be upgraded before I upgrade this component'. Getting this wrong during a rolling upgrade breaks node registration or blocks the upgrade path, usually discovered mid-rollout. The rule text is stable in structure release to release; the version numbers in the worked examples move with each Kubernetes minor release, so the numeric examples need re-verification on that cadence.
The data
| Component pair | Skew rule | Max skew (minor versions) | May the second component be newer? | Worked example | Newest release when captured | Upgrade prerequisite | HA cluster caveat | Exception for older versions |
|---|---|---|---|---|---|---|---|---|
| kube-apiserver and kube-apiserver (HA instances) | the newest and oldest kube-apiserver instances must be within one minor version | 1 | symmetric - the page bounds the gap between the newest and oldest instance without naming a governed side | newest kube-apiserver is at 1.37 other kube-apiserver instances are supported at 1.37 and 1.36 | 1.37 | In a single-instance cluster, the existing kube-apiserver instance is 1.36 In an HA cluster, all kube-apiserver instances are at 1.36 or 1.37 | ||
| kube-apiserver and kube-controller-manager, kube-scheduler, or cloud-controller-manager | They are expected to match the kube-apiserver minor version, but may be up to one minor version older (to allow live upgrades). | 1 | no - these components must not be newer than the kube-apiserver instances they communicate with | kube-apiserver is at 1.37 kube-controller-manager, kube-scheduler, and cloud-controller-manager are supported at 1.37 and 1.36 | 1.37 | The kube-apiserver instances these components communicate with are at 1.37 | If version skew exists between kube-apiserver instances in an HA cluster, and these components can communicate with any kube-apiserver instance in the cluster (for example, via a load balancer), this narrows the allowed versions of these components. | |
| kube-apiserver and kube-proxy | kube-proxy may be up to three minor versions older than kube-apiserver | 3 | no - kube-proxy must not be newer than kube-apiserver | kube-apiserver is at 1.37 kube-proxy is supported at 1.37, 1.36, 1.35, and 1.34 | 1.37 | The kube-apiserver instances kube-proxy communicates with are at 1.37 | If version skew exists between kube-apiserver instances in an HA cluster, this narrows the allowed kube-proxy versions. | kube-proxy < 1.25 may only be up to two minor versions older than kube-apiserver |
| kube-apiserver and kubectl | kubectl is supported within one minor version (older or newer) of kube-apiserver. | 1 | yes - kubectl is supported one minor version older or newer than kube-apiserver | kube-apiserver is at 1.37 kubectl is supported at 1.38, 1.37, and 1.36 | 1.37 | If version skew exists between kube-apiserver instances in an HA cluster, this narrows the supported kubectl versions. | ||
| kube-apiserver and kubelet | kubelet may be up to three minor versions older than kube-apiserver | 3 | no - kubelet must not be newer than kube-apiserver | kube-apiserver is at 1.37 kubelet is supported at 1.37, 1.36, 1.35, and 1.34 | 1.37 | The kube-apiserver instances the kubelet communicates with are at 1.37 | If version skew exists between kube-apiserver instances in an HA cluster, this narrows the allowed kubelet versions. | kubelet < 1.25 may only be up to two minor versions older than kube-apiserver |
| kubelet and kube-proxy | kube-proxy may be up to three minor versions older or newer than the kubelet instance it runs alongside | 3 | yes - kube-proxy may be older or newer than the kubelet instance it runs alongside | 1.37 | kube-proxy < 1.25 may only be up to two minor versions older or newer than the kubelet instance it runs alongside |
Where this came from
Every record above links the page it was taken from and quotes the sentence that states it. These are the 1 source this dataset was assembled from.
- kubernetes.iohttps://kubernetes.io/releases/version-skew-policy/
Machine-readable
- data.jsonThe whole dataset — every record with its source URL and source quote.
- Open Knowledge Format bundleOne JSON object per line — every record's frontmatter and quoted span exactly as it is held here, in one fetch.
- data.csvThe same records as one flat table, for a spreadsheet or a dataframe. The last four columns are the source URL, the quoted sentence it was read from, the date we last checked it, and which columns are our reading rather than the page's words.
- How this is made and checkedWhat "verified against source" does and does not mean.
From your own code
Same records, same quotes, without scraping the page: refsource is on PyPI and npm. Each value comes back carrying the URL it was read from and the sentence on that page that states it — .source and .quote sit on the value itself rather than in a side channel, so the checking step is available instead of skipped.
pip install refsource
refsource lookup kubernetes-version-skew-policy max_skew_minor_versions=1
npx -y refsource lookup kubernetes-version-skew-policy max_skew_minor_versions=1Set your AI assistant up to use this
Two files and no account. Put this in .mcp.json at the root of your project — Claude Code, Cursor, Windsurf, VS Code and Codex all read that file — and your assistant can look this dataset up instead of recalling it. The server is remote, keyless and read-only.
{
"mcpServers": {
"referencesource": {
"type": "http",
"url": "https://referencesource.org/mcp"
}
}
}Add to Cursor · or, on the command line: claude mcp add --transport http referencesource https://referencesource.org/mcp --scope project
Then one line in the project's CLAUDE.md or AGENTS.md, so the assistant knows when to reach for it:
When a question needs "Kubernetes component version skew policy: how far apart component versions can be in a supported cluster", call the referencesource MCP server at https://referencesource.org/mcp (tool `search_records`, dataset_slug `kubernetes-version-skew-policy`) instead of answering from memory — every record it returns carries its source URL and a verbatim quote from that page.What each tool does, and the servers built over single registers: Connect your AI assistant.