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 team. The patch release team is part of release managers. For more information, see Kubernetes Patch releases.
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:
- newest
kube-apiserveris at 1.13 - other
kube-apiserverinstances are supported at 1.13 and 1.12
kubelet
kubelet must not be newer than kube-apiserver, and may be up to two minor versions older.
Example:
kube-apiserveris at 1.13kubeletis supported at 1.13, 1.12, and 1.11
Note: If version skew exists betweenkube-apiserverinstances in an HA cluster, this narrows the allowedkubeletversions.
Example:
kube-apiserverinstances are at 1.13 and 1.12kubeletis supported at 1.12, and 1.11 (1.13 is not supported because that would be newer than thekube-apiserverinstance at version 1.12)
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-apiserveris at 1.13kube-controller-manager,kube-scheduler, andcloud-controller-managerare supported at 1.13 and 1.12
Note: If version skew exists betweenkube-apiserverinstances in an HA cluster, and these components can communicate with anykube-apiserverinstance in the cluster (for example, via a load balancer), this narrows the allowed versions of these components.
Example:
kube-apiserverinstances are at 1.13 and 1.12kube-controller-manager,kube-scheduler, andcloud-controller-managercommunicate with a load balancer that can route to anykube-apiserverinstancekube-controller-manager,kube-scheduler, andcloud-controller-managerare supported at 1.12 (1.13 is not supported because that would be newer than thekube-apiserverinstance at version 1.12)
kubectl
kubectl is supported within one minor version (older or newer) of kube-apiserver.
Example:
kube-apiserveris at 1.13kubectlis supported at 1.14, 1.13, and 1.12
Note: If version skew exists betweenkube-apiserverinstances in an HA cluster, this narrows the supportedkubectlversions.
Example:
kube-apiserverinstances are at 1.13 and 1.12kubectlis supported at 1.13 and 1.12 (other versions would be more than one minor version skewed from one of thekube-apiservercomponents)
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:
- In a single-instance cluster, the existing
kube-apiserverinstance is 1.n - In an HA cluster, all
kube-apiserverinstances are at 1.n or 1.(n+1) (this ensures maximum skew of 1 minor version between the oldest and newestkube-apiserverinstance) - The
kube-controller-manager,kube-scheduler, andcloud-controller-managerinstances that communicate with this server are at version 1.n (this ensures they are not newer than the existing API server version, and are within 1 minor version of the new API server version) kubeletinstances on all nodes are at version 1.n or 1.(n-1) (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-apiserverinstance will send them:ValidatingWebhookConfigurationandMutatingWebhookConfigurationobjects are updated to include any new versions of REST resources added in 1.(n+1) (or use thematchPolicy: Equivalentoption 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.(n+1)
Upgrade kube-apiserver to 1.(n+1)
Note: Project policies for API deprecation and API change guidelines requirekube-apiserverto not skip minor versions when upgrading, even in single-instance clusters.
kube-controller-manager, kube-scheduler, and cloud-controller-manager
Pre-requisites:
- The
kube-apiserverinstances these components communicate with are at 1.(n+1) (in HA clusters in which these control plane components can communicate with anykube-apiserverinstance in the cluster, allkube-apiserverinstances must be upgraded before upgrading these components)
Upgrade kube-controller-manager, kube-scheduler, and cloud-controller-manager to 1.(n+1)
kubelet
Pre-requisites:
- The
kube-apiserverinstances thekubeletcommunicates with are at 1.(n+1)
Optionally upgrade kubelet instances to 1.(n+1) (or they can be left at 1.n or 1.(n-1))
Warning: Running a cluster withkubeletinstances that are persistently two minor versions behindkube-apiserveris not recommended:
- they must be upgraded within one minor version of
kube-apiserverbefore the control plane can be upgraded- it increases the likelihood of running
kubeletversions older than the three maintained minor releases
Feedback
Was this page helpful?
Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.
Page last modified on October 20, 2019 at 6:39 PM PST by
Update patch release manager to patch release team in version skew po… (#17008) (Page History)