그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그 그
4 minute read
Version Skew Policy
This document describes the maximum version skew supported between various Gardener components.
Supported Gardener Versions
Gardener 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.
The Gardener project maintains release branches for the three most recent 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, plus additional urgent releases when required.
For more information, see the Releases document.
Supported Version Skew
Technically, we follow the same policy as the Kubernetes project.
However, given that our release cadence is much more frequent compared to Kubernetes (every 14d
vs. every 120d
), in many cases it might be possible to skip versions, though we do not test these upgrade paths.
Consequently, in general it might not work, and to be on the safe side, it is highly recommended to follow the described policy.
🚨 Note that downgrading Gardener versions is generally not tested during development and should be considered unsupported.
gardener-apiserver
In multi-instance setups of Gardener, the newest and oldest gardener-apiserver
instances must be within one minor version.
Example:
- newest
gardener-apiserver
is at 1.37 - other
gardener-apiserver
instances are supported at 1.37 and 1.36
gardener-controller-manager, gardener-scheduler, gardener-admission-controller
gardener-controller-manager
, gardener-scheduler
, and gardener-admission-controller
must not be newer than the gardener-apiserver
instances they communicate with.
They are expected to match the gardener-apiserver
minor version, but may be up to one minor version older (to allow live upgrades).
Example:
gardener-apiserver
is at 1.37gardener-controller-manager
,gardener-scheduler
, andgardener-admission-controller
are supported at 1.37 and 1.36
gardenlet
gardenlet
must not be newer thangardener-apiserver
gardenlet
may be up to two minor versions older thangardener-apiserver
Example:
gardener-apiserver
is at 1.37gardenlet
is supported at 1.37, 1.36, and 1.35
gardener-operator
Since gardener-operator
manages the Gardener control plane components (gardener-apiserver
, gardener-controller-manager
, gardener-scheduler
, gardener-admission-controller
), it follows the same policy as for gardener-apiserver
.
It implements additional start-up checks to ensure adherence to this policy.
Concretely, gardener-operator
will crash when
- its gets downgraded.
- its version gets upgraded and skips at least one minor version.
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 Gardener installation from version 1.37 to version 1.38.
gardener-apiserver
Prerequisites:
- In a single-instance setup, the existing
gardener-apiserver
instance is 1.37. - In a multi-instance setup, all
gardener-apiserver
instances are at 1.37 or 1.38 (this ensures maximum skew of 1 minor version between the oldest and newestgardener-apiserver
instance). - The
gardener-controller-manager
,gardener-scheduler
, andgardener-admission-controller
instances that communicate with thisgardener-apiserver
are at version 1.37 (this ensures they are not newer than the existing API server version and are within 1 minor version of the new API server version). gardenlet
instances on all seeds are at version 1.37 or 1.36 (this ensures they are not newer than the existing API server version and are within 2 minor versions of the new API server version).
Actions:
- Upgrade
gardener-apiserver
to 1.38.
gardener-controller-manager, gardener-scheduler, gardener-admission-controller
Prerequisites:
- The
gardener-apiserver
instances these components communicate with are at 1.38 (in multi-instance setups in which these components can communicate with anygardener-apiserver
instance in the cluster, allgardener-apiserver
instances must be upgraded before upgrading these components).
Actions:
- Upgrade
gardener-controller-manager
,gardener-scheduler
, andgardener-admission-controller
to 1.38
gardenlet
Prerequisites:
- The
gardener-apiserver
instances thegardenlet
communicates with are at 1.38.
Actions:
- Optionally upgrade
gardenlet
instances to 1.38 (or they can be left at 1.37 or 1.36).
[!WARNING] Running a landscape with
gardenlet
instances that are persistently two minor versions behindgardener-apiserver
means they must be upgraded before the Gardener control plane can be upgraded.
gardener-operator
Prerequisites:
- All
gardener-operator
instances are at 1.37.
Actions:
- Upgrade
gardener-operator
to 1.38.
Supported Gardener Extension Versions
Extensions are maintained and released separately and independently of the gardener/gardener
repository.
Consequently, providing version constraints is not possible in this document.
Sometimes, the documentation of extensions contains compatibility information (e.g., “this extension version is only compatible with Gardener versions higher than 1.80”, see this example).
However, since all extensions typically make use of the extensions library (example), a general constraint is that no extension must depend on a version of the extensions library higher than the version of gardenlet
.
Example 1:
gardener-apiserver
and other Gardener control plane components are at 1.37.- All
gardenlet
s are at 1.37. - Only extensions are supported which depend on 1.37 or lower of the extensions library.
Example 2:
gardener-apiserver
and other Gardener control plane components are at 1.37.- Some
gardenlet
s are at 1.37, others are at 1.36. - Only extensions are supported which depend on 1.36 or lower of the extensions library.
Supported Kubernetes Versions
Please refer to Supported Kubernetes Versions.