You are viewing documentation for Kubernetes version: v1.18
Kubernetes v1.18 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
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 (1.22, 1.21, 1.20).
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, plus additional urgent releases, when required.
The Release Managers group owns this decision.
For more information, see the Kubernetes patch releases page.
Supported version skew
kube-apiserver
In highly-available (HA) clusters, the newest and oldest kube-apiserver
instances must be within one minor version.
Example:
- newest
kube-apiserver
is at 1.22 - other
kube-apiserver
instances are supported at 1.22 and 1.21
kubelet
kubelet
must not be newer than kube-apiserver
, and may be up to two minor versions older.
Example:
kube-apiserver
is at 1.22kubelet
is supported at 1.22, 1.21, and 1.20
Note: If version skew exists betweenkube-apiserver
instances in an HA cluster, this narrows the allowedkubelet
versions.
Example:
kube-apiserver
instances are at 1.22 and 1.21kubelet
is supported at 1.21, and 1.20 (1.22 is not supported because that would be newer than thekube-apiserver
instance at version 1.21)
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.22kube-controller-manager
,kube-scheduler
, andcloud-controller-manager
are supported at 1.22 and 1.21
Note: If version skew exists betweenkube-apiserver
instances in an HA cluster, and these components can communicate with anykube-apiserver
instance in the cluster (for example, via a load balancer), this narrows the allowed versions of these components.
Example:
kube-apiserver
instances are at 1.22 and 1.21kube-controller-manager
,kube-scheduler
, andcloud-controller-manager
communicate with a load balancer that can route to anykube-apiserver
instancekube-controller-manager
,kube-scheduler
, andcloud-controller-manager
are supported at 1.21 (1.22 is not supported because that would be newer than thekube-apiserver
instance at version 1.21)
kubectl
kubectl
is supported within one minor version (older or newer) of kube-apiserver
.
Example:
kube-apiserver
is at 1.22kubectl
is supported at 1.23, 1.22, and 1.21
Note: If version skew exists betweenkube-apiserver
instances in an HA cluster, this narrows the supportedkubectl
versions.
Example:
kube-apiserver
instances are at 1.22 and 1.21kubectl
is supported at 1.22 and 1.21 (other versions would be more than one minor version skewed from one of thekube-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.21 to version 1.22.
kube-apiserver
Pre-requisites:
- In a single-instance cluster, the existing
kube-apiserver
instance is 1.21 - In an HA cluster, all
kube-apiserver
instances are at 1.21 or 1.22 (this ensures maximum skew of 1 minor version between the oldest and newestkube-apiserver
instance) - The
kube-controller-manager
,kube-scheduler
, andcloud-controller-manager
instances that communicate with this server are at version 1.21 (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.21 or 1.20 (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
andMutatingWebhookConfiguration
objects are updated to include any new versions of REST resources added in 1.22 (or use thematchPolicy: Equivalent
option 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.22
Upgrade kube-apiserver
to 1.22
Note: Project policies for API deprecation and API change guidelines requirekube-apiserver
to not skip minor versions when upgrading, even in single-instance clusters.
kube-controller-manager, kube-scheduler, and cloud-controller-manager
Pre-requisites:
- The
kube-apiserver
instances these components communicate with are at 1.22 (in HA clusters in which these control plane components can communicate with anykube-apiserver
instance in the cluster, allkube-apiserver
instances must be upgraded before upgrading these components)
Upgrade kube-controller-manager
, kube-scheduler
, and cloud-controller-manager
to 1.22
kubelet
Pre-requisites:
- The
kube-apiserver
instances thekubelet
communicates with are at 1.22
Optionally upgrade kubelet
instances to 1.22 (or they can be left at 1.21 or 1.20)
Warning:Running a cluster with
kubelet
instances that are persistently two minor versions behindkube-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
kube-proxy
kube-proxy
must be the same minor version askubelet
on the node.kube-proxy
must not be newer thankube-apiserver
.kube-proxy
must be at most two minor versions older thankube-apiserver.
Example:
If kube-proxy
version is 1.20:
kubelet
version must be at the same minor version as 1.20.kube-apiserver
version must be between 1.20 and 1.22, inclusive.