diff --git a/docs/kubernetes-version.md b/docs/kubernetes-version.md index edcf098c..65a06864 100644 --- a/docs/kubernetes-version.md +++ b/docs/kubernetes-version.md @@ -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/) | [k8s-openapi@0.20.0](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/) | [k8s-openapi@0.19.0](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/) | [k8s-openapi@0.17.0](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/) | [k8s-openapi@0.16.0](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/) | [k8s-openapi@0.15.0](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/) | [k8s-openapi@0.14.0](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/) | [k8s-openapi@0.13.0](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/) | [k8s-openapi@0.12.0](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/) | [k8s-openapi@0.11.0](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/) | [k8s-openapi@0.20.0](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/) | [k8s-openapi@0.19.0](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/) | [k8s-openapi@0.17.0](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/) | [k8s-openapi@0.16.0](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/) | [k8s-openapi@0.15.0](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/) | [k8s-openapi@0.14.0](https://github.com/Arnavion/k8s-openapi/releases/tag/v0.14.0) | + + 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 [`kube@0.73.0`](https://docs.rs/kube/0.73.0/kube/), we see its generated source is [`k8s-openapi@0.15.0`](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 [`kube@0.86.0`](https://github.com/kube-rs/kube/releases/tag/0.86.0), the generated source is [`k8s-openapi@0.20.0`](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. + + ## 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