|
| 1 | +--- |
| 2 | +reviewers: |
| 3 | +- sig-api-machinery |
| 4 | +- sig-architecture |
| 5 | +- sig-cli |
| 6 | +- sig-cluster-lifecycle |
| 7 | +- sig-node |
| 8 | +- sig-release |
| 9 | +title: Kubernetes Version and Version Skew Support Policy |
| 10 | +content_template: templates/concept |
| 11 | +weight: 70 |
| 12 | +--- |
| 13 | + |
| 14 | +{{% capture overview %}} |
| 15 | +This document describes the maximum version skew supported between various Kubernetes components. |
| 16 | +Specific cluster deployment tools may place additional restrictions on version skew. |
| 17 | +{{% /capture %}} |
| 18 | + |
| 19 | +{{% capture body %}} |
| 20 | + |
| 21 | +## Supported versions |
| 22 | + |
| 23 | +The Kubernetes project maintains release branches for the most recent three minor releases, |
| 24 | +and expects users to be running those versions in production. |
| 25 | + |
| 26 | +Applicable bug and security fixes may be backported to those three release branches, depending on severity and feasibility. |
| 27 | +Patch releases are cut from those branches at a regular cadence, |
| 28 | +or on an as-needed basis as determined by the [patch release manager](https://github.com/kubernetes/sig-release/blob/master/release-team/role-handbooks/patch-release-manager/README.md#release-timing). |
| 29 | + |
| 30 | +With minor releases happening approximately every three months, |
| 31 | +that means each minor release is maintained for approximately nine months. |
| 32 | + |
| 33 | +## Supported version skew |
| 34 | + |
| 35 | +### `kube-apiserver` |
| 36 | + |
| 37 | +In HA deployments, the newest and oldest `kube-apiserver` must be within one minor version. |
| 38 | + |
| 39 | +Example: |
| 40 | + |
| 41 | +* newest `kube-apiserver` is at `1.x` |
| 42 | +* other `kube-apiserver` components are supported at `1.x` and `1.x-1` |
| 43 | + |
| 44 | +### `kubelet` |
| 45 | + |
| 46 | +`kubelet` must not be newer than `kube-apiserver`, and may be up to two minor versions older. |
| 47 | + |
| 48 | +Example: |
| 49 | + |
| 50 | +* `kube-apiserver` is at `1.x` |
| 51 | +* `kubelet` is supported at `1.x`, `1.x-1`, and `1.x-2` |
| 52 | + |
| 53 | +Note that if `kube-apiserver` skew exists in a highly available (HA) control plane, this narrows the allowed `kubelet` versions. |
| 54 | + |
| 55 | +Example: |
| 56 | + |
| 57 | +* `kube-apiserver` components are at `1.x` and `1.x-1` |
| 58 | +* `kubelet` is supported at `1.x-1`, and `1.x-2` (`1.x` is not supported because that would be newer than the `kube-apiserver` at version `1.x-1`) |
| 59 | + |
| 60 | +### `kube-controller-manager` and `kube-scheduler` |
| 61 | + |
| 62 | +`kube-controller-manager` and `kube-scheduler` must not be newer than `kube-apiserver`. They are expected to match the `kube-apiserver` minor version, but may be one minor version older during upgrades. |
| 63 | + |
| 64 | +Example: |
| 65 | + |
| 66 | +* `kube-apiserver` is at `1.x` |
| 67 | +* `kube-controller-manager` and `kube-scheduler` are supported at `1.x` and `1.x-1` |
| 68 | + |
| 69 | +Note that if `kube-apiserver` skew exists in an HA control plane, this narrows the allowed `kube-controller-manager` versions. |
| 70 | + |
| 71 | +Example: |
| 72 | + |
| 73 | +* `kube-apiserver` components are at `1.x` and `1.x-1` |
| 74 | +* `kube-controller-manager` and `kube-scheduler` are supported at `1.x-1` (`1.x` is not supported because that would be newer than the `kube-apiserver` at version `1.x-1`) |
| 75 | + |
| 76 | +### `kubectl` |
| 77 | + |
| 78 | +`kubectl` is supported within one minor version (older or newer) of `kube-apiserver`. |
| 79 | + |
| 80 | +Example: |
| 81 | + |
| 82 | +* `kube-apiserver` is at `1.x` |
| 83 | +* `kubectl` is supported at `1.x+1`, `1.x`, and `1.x-1` |
| 84 | + |
| 85 | +Note that if `kube-apiserver` skew exists in an HA control plane, this narrows the supported `kubectl` versions. |
| 86 | + |
| 87 | +Example: |
| 88 | + |
| 89 | +* `kube-apiserver` components are at `1.x` and `1.x-1` |
| 90 | +* `kubectl` is supported at `1.x` and `1.x-1` (other versions would be more than one minor version skewed from one of the `kube-apiserver` components) |
| 91 | + |
| 92 | +## Supported component upgrade order |
| 93 | + |
| 94 | +The supported version skew between components has implications on the order in which components must be upgraded. |
| 95 | +This section describes the order in which components must be upgraded to transition an existing cluster from version `1.x` to version `1.x+1`. |
| 96 | + |
| 97 | +### Pre-requisites |
| 98 | + |
| 99 | +1. `kube-apiserver` components are at `1.x` (in an HA cluster, all `kube-apiserver` components are at the same version) |
| 100 | +2. `kube-controller-manager` and `kube-scheduler` are at version `1.x` (this ensures they are not newer than the existing API server, and are within 1 minor version of the new API server) |
| 101 | +3. `kubelet` components on all nodes are at version `1.x` or `1.x-1` (this ensures they are not newer than the existing API server, and are within 2 minor versions of the new API server) |
| 102 | +4. registered admission webhooks are capable of understanding all the versions of REST resources they are registered for (including any new versions available in `1.x+1`) |
| 103 | + |
| 104 | +### Upgrade order |
| 105 | + |
| 106 | +1. `kube-apiserver` |
| 107 | + * Upgrade `kube-apiserver` to `1.x+1` |
| 108 | + * In HA deployments, all API servers should be upgraded before upgrading other control plane components |
| 109 | +2. `kube-controller-manager` and `kube-scheduler` |
| 110 | + * Upgrade `kube-controller-manager` and `kube-scheduler` to `1.x+1` |
| 111 | +3. `kubelet` |
| 112 | + * Optionally upgrade `kubelet` components to `1.x+1` (or they can be left at `1.x` or `1.x-1`) |
0 commit comments