# Version Skew Policy

> The maximum version skew supported between various Kubernetes components.

---

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->
This document describes the maximum version skew supported between various Kubernetes components.
Specific cluster deployment tools may place additional restrictions on version skew.

<!-- body -->

## Supported versions

Kubernetes versions are expressed as **x.y.z**, where **x** is the major version,
**y** is the minor version, and **z** is the patch version, following
[Semantic Versioning](https://semver.org/) terminology. For more information, see
[Kubernetes Release Versioning](https://git.k8s.io/sig-release/release-engineering/versioning.md#kubernetes-release-versioning).

The Kubernetes project maintains release branches for the most recent three minor releases
(1.36, 1.35, 1.34).
Kubernetes 1.19 and newer receive [approximately 1 year of patch support](/releases/patch-releases/#support-period).
Kubernetes 1.18 and older received approximately 9 months of patch support.

Applicable fixes, including security fixes, may be backported to those three release branches,
depending on severity and feasibility. Patch releases are cut from those branches at a
[regular cadence](/releases/patch-releases/#cadence), plus additional urgent releases, when required.

The [Release Managers](/releases/release-managers/) group owns this decision.

For more information, see the Kubernetes [patch releases](/releases/patch-releases/) page.

## Supported version skew

### kube-apiserver

In [highly-available (HA) clusters](/docs/setup/production-environment/tools/kubeadm/high-availability/),
the newest and oldest `kube-apiserver` instances must be within one minor version.

Example:

* newest `kube-apiserver` is at **1.36**
* other `kube-apiserver` instances are supported at **1.36** and **1.35**

### kubelet

* `kubelet` must not be newer than `kube-apiserver`.
* `kubelet` may be up to three minor versions older than `kube-apiserver` (`kubelet` < 1.25 may only be up to two minor versions older than `kube-apiserver`).

Example:

* `kube-apiserver` is at **1.36**
* `kubelet` is supported at **1.36**, **1.35**,
  **1.34**, and **1.33**


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>If version skew exists between <code>kube-apiserver</code> instances in an HA cluster, this narrows the allowed <code>kubelet</code> versions.</div>


Example:

* `kube-apiserver` instances are at **1.36** and **1.35**
* `kubelet` is supported at **1.35**, **1.34**,
  and **1.33** (**1.36** is not supported because that
  would be newer than the `kube-apiserver` instance at version **1.35**)

### kube-proxy

* `kube-proxy` must not be newer than `kube-apiserver`.
* `kube-proxy` may be up to three minor versions older than `kube-apiserver`
  (`kube-proxy` < 1.25 may only be up to two minor versions older than `kube-apiserver`).
* `kube-proxy` may be up to three minor versions older or newer than the `kubelet` instance
  it runs alongside (`kube-proxy` < 1.25 may only be up to two minor versions older or newer
  than the `kubelet` instance it runs alongside).

Example:

* `kube-apiserver` is at **1.36**
* `kube-proxy` is supported at **1.36**, **1.35**,
  **1.34**, and **1.33**


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>If version skew exists between <code>kube-apiserver</code> instances in an HA cluster, this narrows the allowed <code>kube-proxy</code> versions.</div>


Example:

* `kube-apiserver` instances are at **1.36** and **1.35**
* `kube-proxy` is supported at **1.35**, **1.34**,
  and **1.33** (**1.36** is not supported because that would
  be newer than the `kube-apiserver` instance at version **1.35**)

### kube-controller-manager, kube-scheduler, and cloud-controller-manager

`kube-controller-manager`, `kube-scheduler`, and `cloud-controller-manager` must not be newer than the
`kube-apiserver` instances they communicate with. They are expected to match the `kube-apiserver` minor version,
but may be up to one minor version older (to allow live upgrades).

Example:

* `kube-apiserver` is at **1.36**
* `kube-controller-manager`, `kube-scheduler`, and `cloud-controller-manager` are supported
  at **1.36** and **1.35**


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>If version skew exists between <code>kube-apiserver</code> instances in an HA cluster, and these components
can communicate with any <code>kube-apiserver</code> instance in the cluster (for example, via a load balancer),
this narrows the allowed versions of these components.</div>


Example:

* `kube-apiserver` instances are at **1.36** and **1.35**
* `kube-controller-manager`, `kube-scheduler`, and `cloud-controller-manager` communicate with a load balancer
  that can route to any `kube-apiserver` instance
* `kube-controller-manager`, `kube-scheduler`, and `cloud-controller-manager` are supported at
  **1.35** (**1.36** is not supported
  because that would be newer than the `kube-apiserver` instance at version **1.35**)

### kubectl

`kubectl` is supported within one minor version (older or newer) of `kube-apiserver`.

Example:

* `kube-apiserver` is at **1.36**
* `kubectl` is supported at **1.37**, **1.36**,
  and **1.35**


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>If version skew exists between <code>kube-apiserver</code> instances in an HA cluster, this narrows the supported <code>kubectl</code> versions.</div>


Example:

* `kube-apiserver` instances are at **1.36** and **1.35**
* `kubectl` is supported at **1.36** and **1.35**
  (other versions would be more than one minor version skewed from one of the `kube-apiserver` components)

## Supported component upgrade order

The supported version skew between components has implications on the order
in which components must be upgraded. This section describes the order in
which components must be upgraded to transition an existing cluster from version
**1.35** to version **1.36**.

Optionally, when preparing to upgrade, the Kubernetes project recommends that
you do the following to benefit from as many regression and bug fixes as
possible during your upgrade:

* Ensure that components are on the most recent patch version of your current
  minor version.
* Upgrade components to the most recent patch version of the target minor
  version.

For example, if you're running version 1.35,
ensure that you're on the most recent patch version. Then, upgrade to the most
recent patch version of 1.36.

### kube-apiserver

Pre-requisites:

* In a single-instance cluster, the existing `kube-apiserver` instance is **1.35**
* In an HA cluster, all `kube-apiserver` instances are at **1.35** or
  **1.36** (this ensures maximum skew of 1 minor version between the oldest and newest `kube-apiserver` instance)
* The `kube-controller-manager`, `kube-scheduler`, and `cloud-controller-manager` instances that
  communicate with this server are at version **1.35**
  (this ensures they are not newer than the existing API server version, and are within 1 minor version of the new API server version)
* `kubelet` instances on all nodes are at version **1.35** or **1.34**
  (this ensures they are not newer than the existing API server version, and are within 2 minor versions of the new API server version)
* Registered admission webhooks are able to handle the data the new `kube-apiserver` instance will send them:
  * `ValidatingWebhookConfiguration` and `MutatingWebhookConfiguration` objects are updated to include
    any new versions of REST resources added in **1.36**
    (or use the [`matchPolicy: Equivalent` option](/docs/reference/access-authn-authz/extensible-admission-controllers/#matching-requests-matchpolicy) available in v1.15+)
  * The webhooks are able to handle any new versions of REST resources that will be sent to them,
    and any new fields added to existing versions in **1.36**

Upgrade `kube-apiserver` to **1.36**


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>Project policies for <a href="/docs/reference/using-api/deprecation-policy/">API deprecation</a> and
<a href="https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api_changes.md">API change guidelines</a>
require <code>kube-apiserver</code> to not skip minor versions when upgrading, even in single-instance clusters.</div>


### kube-controller-manager, kube-scheduler, and cloud-controller-manager

Pre-requisites:

* The `kube-apiserver` instances these components communicate with are at **1.36**
  (in HA clusters in which these control plane components can communicate with any `kube-apiserver`
  instance in the cluster, all `kube-apiserver` instances must be upgraded before upgrading these components)

Upgrade `kube-controller-manager`, `kube-scheduler`, and
`cloud-controller-manager` to **1.36**. There is no
required upgrade order between `kube-controller-manager`, `kube-scheduler`, and
`cloud-controller-manager`. You can upgrade these components in any order, or
even simultaneously.

### kubelet

Pre-requisites:

* The `kube-apiserver` instances the `kubelet` communicates with are at **1.36**

Optionally upgrade `kubelet` instances to **1.36** (or they can be left at
**1.35**, **1.34**, or **1.33**)


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>Before performing a minor version <code>kubelet</code> upgrade, <a href="/docs/tasks/administer-cluster/safely-drain-node/">drain</a> pods from that node.
In-place minor version <code>kubelet</code> upgrades are not supported.</div>


<div class="alert alert-danger" role="note"><h4 class="alert-heading">Warning:</h4>Running a cluster with <code>kubelet</code> instances that are persistently three minor versions behind
<code>kube-apiserver</code> means they must be upgraded before the control plane can be upgraded.</div>


### kube-proxy

Pre-requisites:

* The `kube-apiserver` instances `kube-proxy` communicates with are at **1.36**

Optionally upgrade `kube-proxy` instances to **1.36**
(or they can be left at **1.35**, **1.34**,
or **1.33**)

<div class="alert alert-danger" role="note"><h4 class="alert-heading">Warning:</h4>Running a cluster with <code>kube-proxy</code> instances that are persistently three minor versions behind
<code>kube-apiserver</code> means they must be upgraded before the control plane can be upgraded.</div>