Setup

Edit This Page

Kubernetes Version and Version Skew Support Policy

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

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 terminology. For more information, see Kubernetes Release Versioning.

The Kubernetes project maintains release branches for the most recent three minor releases.

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, or as needed. This decision is owned by the patch release manager. The patch release manager is a member of the release team for each release.

Minor releases occur approximately every 3 months, so each minor release branch is maintained for approximately 9 months.

Supported version skew

kube-apiserver

In highly-available (HA) clusters, the newest and oldest kube-apiserver instances must be within one minor version.

Example:

kubelet

kubelet must not be newer than kube-apiserver, and may be up to two minor versions older.

Example:

Note: If version skew exists between kube-apiserver instances in an HA cluster, this narrows the allowed kubelet versions.

Example:

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:

Note: 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.

Example:

kubectl

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

Example:

Note: If version skew exists between kube-apiserver instances in an HA cluster, this narrows the supported kubectl versions.

Example:

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.n to version 1.(n+1).

kube-apiserver

Pre-requisites:

Upgrade kube-apiserver to 1.(n+1)

Note: Project policies for API deprecation and API change guidelines require kube-apiserver to not skip minor versions when upgrading, even in single-instance clusters.

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

Pre-requisites:

Upgrade kube-controller-manager, kube-scheduler, and cloud-controller-manager to 1.(n+1)

kubelet

Pre-requisites:

Optionally upgrade kubelet instances to 1.(n+1) (or they can be left at 1.n or 1.(n-1))

Warning: Running a cluster with kubelet instances that are persistently two minor versions behind kube-apiserver is not recommended:

  • they must be upgraded within one minor version of kube-apiserver before the control plane can be upgraded
  • it increases the likelihood of running kubelet versions older than the three maintained minor releases

Feedback