Our Kubernetes version compatibility is following a similar strategy to the one employed by client-go and can interoperate under a wide range of Kubernetes versions. We define by a soft minimum (MK8SV) based on the current latest available Kubernetes version in the generated source.
Minimum Kubernetes Version Policy
The Minimum Supported Kubernetes Version (MK8SV) is 5 releases less than the latest Kubernetes version.
The minimum indicates the lower bound of our testing range, and the latest is the maximum Kubernetes version selectable as a target version. The minimum has evolved like this:
|kube version||MK8SV||Latest||Generated Source|
kube version, you may choose a target Kubernetes version from the available features in the generated source that is used by that kube version.
firstname.lastname@example.org, the generated source is
email@example.com, which exports the following version features. The
latest supported version feature is here aliased to
v1_28, our minimum tested version is
latest feature as your target version is a good default choice, even when running against older clusters.
Consider pinning to a specific cluster version if you are programming explicitly against deprecated or alpha apis.
See the version skew outcomes if you are unsure whether you need to pin a version.
How kube version skew interacts with clusters is largely determined by how Kubernetes deprecates api versions upstream.
Consider the following outcomes when picking target versions based on your cluster version:
target version == cluster version(cluster in sync with kube), then:
- kube has api parity with cluster
- Rust structs are all queryable via kube
target version > cluster version(cluster behind kube), then:
- kube has more recent api features than the cluster supports
- recent Rust api structs might not work with the cluster version yet
- deprecated/alpha apis might have been removed from Rust structs ⚡
target version < cluster version(cluster ahead of kube), then:
- kube has less recent api features than the cluster supports
- recent Kubernetes resources might not have Rust struct counterparts
- deprecated/alpha apis might have been removed from the cluster ⚡
Kubernetes takes a long time to remove deprecated apis (unless they alpha or beta apis), so the acceptable distance from your cluster version depends on what apis you target.
In particular, when using stable (or your own custom) api resources, exceeding the range will have little impact.
If you are targeting deprecated/alpha apis on the other hand, then you should pick a target version in sync with your cluster, as alpha apis may vanish or change significantly in a single release, and is not covered by any guarantees.
Relying on alpha apis will make the amount of upgrades required to an application more frequent. To alleviate this; consider using api discovery to match on available api versions rather than writing code against each Kubernetes version.
Outside The Range#
We recommend developers stay within the supported version range for the best experience, but it is technically possible to operate outside the bounds of this range (by picking older features from
k8s-openapi, or by running against older clusters).
Untested Version Combinations
While exceeding the supported version range is likely to work for most api resources: we do not test kube's functionality outside this version range.
In minor skews, kube and Kubernetes will share a large functioning API surface, while relying on deprecated apis to fill the gap. However, the further you stray from the range you are more likely to encounter Rust structs that doesn't work against your cluster, or miss support for resources entirely.
For a small number of api resources, kube provides abstractions that are not managed along with the generated sources. For these cases we track the source and remove when Kubernetes removes them (to avoid double dipping on deprecation time).
This affects a small number of special resources such as
CustomResourceDefinition resource at
v1beta1 was removed in Kubernetes
The apiextensions.k8s.io/v1beta1 API version of CustomResourceDefinition is no longer served as of v1.22.
Their replacement; in
v1 was released in Kubernetes
Kube had special support for both versions of
0.26.0 up until
0.72.0 when kube supported structs from Kubernetes >= 1.22.