-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update kubernetes version table and tweak wording a bit
Signed-off-by: clux <[email protected]>
- Loading branch information
Showing
1 changed file
with
27 additions
and
24 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,15 +4,14 @@ Our Kubernetes version compatibility is similar to the strategy employed by [cli | |
|
|
||
| | kube version | MK8SV | Latest | Generated Source | | ||
| | -------------- | ------- | ------- | ----------------- | | ||
| | `0.86.0` | `1.23` | [`1.28`](https://kubernetes.io/blog/2023/08/15/kubernetes-v1-28-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0200-2023-09-07) | | ||
| | `0.85.0` | `1.22` | [`1.27`](https://kubernetes.io/blog/2023/04/11/kubernetes-v1-27-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0190-2023-08-05) | | ||
| | `0.78.0` | `1.21` | [`1.26`](https://kubernetes.io/blog/2022/12/09/kubernetes-v1-26-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0170-2023-01-04) | | ||
| | `0.75.0` | `1.20` | [`1.25`](https://kubernetes.io/blog/2022/08/23/kubernetes-v1-25-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0160-2022-09-15) | | ||
| | `0.73.0` | `1.19` | [`1.24`](https://kubernetes.io/blog/2022/05/03/kubernetes-1-24-release-announcement/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0150-2022-05-22) | | ||
| | `0.67.0` | `1.18` | [`1.23`](https://kubernetes.io/blog/2021/12/07/kubernetes-1-23-release-announcement/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0140-2022-01-23) | | ||
| | `0.66.0` | `1.17` | [`1.22`](https://kubernetes.io/blog/2021/08/04/kubernetes-1-22-release-announcement/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0131-2021-10-08) | | ||
| | `0.57.0` | `1.16` | [`1.21`](https://kubernetes.io/blog/2021/04/08/kubernetes-1-21-release-announcement/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0120-2021-06-15) | | ||
| | `0.48.0` | `1.15` | [`1.20`](https://kubernetes.io/blog/2020/12/08/kubernetes-1-20-release-announcement/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/blob/master/CHANGELOG.md#v0110-2021-01-23) | | ||
| | [0.86.0](https://github.com/kube-rs/kube/releases/tag/0.86.0) | `1.23` | [`1.28`](https://kubernetes.io/blog/2023/08/15/kubernetes-v1-28-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.20.0) | | ||
| | [0.85.0](https://github.com/kube-rs/kube/releases/tag/0.85.0) | `1.22` | [`1.27`](https://kubernetes.io/blog/2023/04/11/kubernetes-v1-27-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.19.0) | | ||
| | [0.78.0](https://github.com/kube-rs/kube/releases/tag/0.78.0) | `1.21` | [`1.26`](https://kubernetes.io/blog/2022/12/09/kubernetes-v1-26-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.17.0) | | ||
| | [0.75.0](https://github.com/kube-rs/kube/releases/tag/0.75.0) | `1.20` | [`1.25`](https://kubernetes.io/blog/2022/08/23/kubernetes-v1-25-release/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.16.0) | | ||
| | [0.73.0](https://github.com/kube-rs/kube/releases/tag/0.73.0) | `1.19` | [`1.24`](https://kubernetes.io/blog/2022/05/03/kubernetes-1-24-release-announcement/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.15.0) | | ||
| | [0.67.0](https://github.com/kube-rs/kube/releases/tag/0.67.0) | `1.18` | [`1.23`](https://kubernetes.io/blog/2021/12/07/kubernetes-1-23-release-announcement/) | [[email protected]](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.14.0) | | ||
|
|
||
| <!-- NB: k8s-openapi 0.18 did not introduce a new Kubernetes version: https://github.com/Arnavion/k8s-openapi/releases/tag/v0.18.0 so its bump is not listed --> | ||
|
|
||
| The MK8SV is listed in our README as a badge: | ||
|
|
||
|
|
@@ -25,21 +24,25 @@ The **minimum** indicates the lower bound of our testing range, and the **latest | |
| The Minimum Supported Kubernetes Version (MK8SV) is set as **5 releases below** the **latest** Kubernetes version. | ||
|
|
||
| This policy is intended to match **stable channel support** within **major cloud providers**. | ||
| Compare with: [EKS](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [AKS](https://docs.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [GKE](https://cloud.google.com/kubernetes-engine/docs/release-notes-stable), [upstream Kubernetes](https://endoflife.date/google-kubernetes-engine). | ||
| Compare with: [EKS](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [AKS](https://docs.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [GKE](https://cloud.google.com/kubernetes-engine/docs/release-schedule), [upstream Kubernetes](https://endoflife.date/google-kubernetes-engine). | ||
|
|
||
| ## Picking Versions | ||
|
|
||
| Given a `kube` versions, you must pick a **target Kubernetes version** from the available ones in the generated source that is used by that kube version. | ||
| Given a `kube` version, you may choose a **target Kubernetes version** from the [available features in the generated source](https://docs.rs/crate/k8s-openapi/latest/features) that is used by that kube version. | ||
|
|
||
| E.g. if using [`[email protected]`](https://docs.rs/kube/0.73.0/kube/), we see its generated source is [`[email protected]`](https://docs.rs/k8s-openapi/0.15.0/k8s_openapi/), which exports the [following version features](https://docs.rs/crate/k8s-openapi/0.15.0/features). | ||
| ### Example | ||
|
|
||
| You can find the latest supported from this feature list and pick this as your target. In this case the latest supported version feature is `v1_24`. | ||
| When using [`[email protected]`](https://github.com/kube-rs/kube/releases/tag/0.86.0), the generated source is [`[email protected]`](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.20.0), which exports the [following version features](https://docs.rs/crate/k8s-openapi/0.20.0/features). I.e. the `latest` supported version feature is _here_ aliased to `v1_28`, and the `earliest` is aliased to `v1_22`. | ||
|
|
||
| By default; you **SHOULD** pick the latest as your target version even when running against older clusters. The **exception** is if you are programming explicitly against apis that have been removed in newer versions. | ||
| ### Guideline | ||
|
|
||
| With [k8s-pb], we plan on [doing this automatically](https://github.com/kube-rs/k8s-pb/issues/10). | ||
| What Kubernetes version you pick is up to you, but the consequences are often insignificant (see [details below](#version-skew)). Thus, we recommend: | ||
|
|
||
| See below for details on a skew between your cluster and your target version. | ||
| > Pick `latest` as your target version (even when running against older clusters). Consider **pinning** to a version matching your cluster **if** you are programming explicitly against deprecated or alpha apis. | ||
| <!-- | ||
| With [k8s-pb], we plan on [doing this automatically](https://github.com/kube-rs/k8s-pb/issues/10). | ||
| --> | ||
|
|
||
| ## Version Skew | ||
|
|
||
|
|
@@ -59,13 +62,13 @@ Consider the following outcomes when picking **target versions** based on your * | |
| * 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](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) (unless they alpha or beta apis), so the **acceptable distance** from your **cluster** version actually **depends** on what **apis you target**. | ||
| [Kubernetes takes a long time to remove deprecated apis](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) (unless they alpha or beta apis), so the **acceptable distance** from your **cluster** version **depends** on what **apis you target**. | ||
|
|
||
| In particular, when using your own **custom** or **stable official** api resources - where exceeding the range will have **little impact**. | ||
| 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**. Note that alpha apis may vanish or change significantly in a single release, and is not covered by any guarantees. | ||
| **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. | ||
|
|
||
| As a result; 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. | ||
| 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 | ||
|
|
||
|
|
@@ -75,13 +78,13 @@ We recommend developers stay within the supported version range for the best exp | |
|
|
||
| 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 **increasingly likely** to encounter Rust structs that doesn't work against your cluster, or miss support for resources entirely. | ||
| 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. | ||
|
|
||
| ## Special Abstractions | ||
| ## Abstractions | ||
|
|
||
| For a small number of api resources, kube provides abstractions that are not managed along with the generated sources. For these cases we currently __track the source__ and remove when Kubernetes removes them. | ||
| 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 only affects a small number of special resources such as `CustomResourceDefinition`, `Event`, `Lease`, `AdmissionReview`. | ||
| This affects a small number of special resources such as `CustomResourceDefinition`, `Event`, `Lease`, `AdmissionReview`. | ||
|
|
||
| ### Example | ||
|
|
||
|
|
||