From 6f4790a2508362aef311ac1ea650ba9bc291294c Mon Sep 17 00:00:00 2001 From: Rob Scott Date: Fri, 29 Oct 2021 11:44:05 -0700 Subject: [PATCH] Adding GEP 922: Adding Gateway API Versioning --- site-src/geps/gep-922.md | 178 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 site-src/geps/gep-922.md diff --git a/site-src/geps/gep-922.md b/site-src/geps/gep-922.md new file mode 100644 index 0000000000..27c94ec21c --- /dev/null +++ b/site-src/geps/gep-922.md @@ -0,0 +1,178 @@ +# GEP-922: Gateway API Versioning + +* Issue: [#922](https://github.com/kubernetes-sigs/gateway-api/issues/922) +* Status: Implementable + +## TLDR +Each Gateway API release will be represented by a bundle version that represents +that specific combination of CRDs, API versions, and validating webhook. To +enable experimental fields, future releases of the API will include stable and +experimental CRD tracks. Users will be able to access experimental features by +installing the experimental CRDs. A cluster can contain either an experimental +or stable CRD for any resource at a given time. + + +## Goals +Provide a path for implementations to support: + +* Users should have a predictable experience when interacting with Gateway API. +* The API should be able to continue to safely evolve, including: + * Loosening validation + * Transitioning required fields to optional + * Adding new fields at an experimental stability level + +## Introduction +This GEP details how we should approach future releases of Gateway API. This is +intended as another step towards building consensus. Once merged, it will be +considered implemented once this content is fully documented. + +## Version Terminology +Gateway API has two related but different versioning schemes: + +### 1. API Versions (ex: v1alpha2) +Each API version provides a unique way to interact with the API. Significant +changes such as removing or renaming fields will be represented here. + +### 2. Bundle Versions (ex: v0.4.0) +Bundle versions are broader in scope. They use semantic versioning and include +the following: + +* API Types/CRDs +* Validating Webhook + +Each bundle may include multiple API versions, potentially introducing new ones +and/or removing old ones as part of a new bundle. + +## Limitations of Webhook and CRD Validation +CRD and webhook validation is not the final validation i.e. webhook is “nice UX” +but not schema enforcement. This validation is intended to provide immediate +feedback to users when they provide an invalid configuration, but can not +completely be relied on because it: + +* Is not guaranteed to be present or up to date in all clusters. +* Will likely never be sufficient to cover all edge cases. +* May be loosened in future API releases. + +## Persona Requirements +When implementing or using Gateway API, each persona has a unique set of +responsibilities to ensure we're providing a consistent experience. + +### API Authors: +* MUST provide conversion between API versions (excluding experimental fields), + starting with v1alpha2. +* MAY include the following changes to an existing API version with a new bundle + **patch** version: + * Clarifications to godocs + * Loosening validation to fix a bug (not to enable a new feature) + * Fixes to typos +* MAY include the following changes to an existing API version with a new bundle + **minor** version: + * Everything that is valid in a patch release + * New experimental API fields or resources + * Loosened validation + * Making required fields optional + * Removal of experimental fields + * Removal of experimental resources + * Graduation of fields or resources from experimental to stable track +* MAY introduce a new **API version** with a new bundle minor version, which may + include: + * Everything that is valid in a minor release + * Renamed fields + * Anything else that is valid in a new Kubernetes API version + * Removal/tombstoning of beta fields +* MAY release a new major bundle version (v1.0) as part of graduating the API to + GA and releasing a new API version. + +Note that each new bundle version, no matter how small, may include updated +CRDs, webhook, or both. Implementations may read annotations on Gateway API CRDs +(defined below) to determine the version and channel of CRDs that have been +installed in the cluster. + +### Implementers: +* MUST handle fields with loosened validation without crashing +* MUST handle fields that have transitioned from required to optional without + crashing +* MUST NOT rely on webhook or CRD validation as a security mechanism. If field + values need to be escaped to secure an implementation, both webhook and CRD + validation can be bypassed and cannot be relied on. Instead, implementations + should implement their own escaping or validation as necessary. To avoid + duplicating work, Gateway API maintainers are considering adding a shared + validation package that implementations can use for this purpose. This is + tracked by [#926](https://github.com/kubernetes-sigs/gateway-api/issues/926). + +### Installers: +* MUST install a full Gateway API bundle, with matching CRD and webhook + versions. + +## Adding Experimental Fields +Over time, it will be useful to add experimental fields to the API. In upstream +Kubernetes, those would generally be guarded with feature gates. With Gateway +API we will accomplish by releasing experimental versions of our CRDs. + +With this approach, we achieve a similar result. Instead of using feature gates +and validation to prevent fields from being set, we just release separate CRDs. +Once the API reaches beta, each bundle release can include 2 sets of CRDs, +stable and experimental. + +New fields will be added to the experimental set of CRDs first, and may graduate +to stable APIs later. Experimental fields will be marked with the +`+experimental` annotation in Go type definitions. Gateway API CRD generation +will exclude these fields from stable CRDs. Experimental fields may be removed +from the API. Due to the experimental nature of these CRDs, they are not +recommended for production use. + +If experimental fields are removed or renamed, the original field name should be +removed from the go struct, with a tombstone comment ensuring the field name +will not be reused. + +Each CRD will be published with annotations that indicate their bundle version +and channel: + +``` +gateway.networking.k8s.io/bundle-version: v0.4.0 +gateway.networking.k8s.io/channel: stable|experimental +``` + +## Alternatives Considered +### 1. Use Webhook to Implement Feature Gates +This option would involve using the webhook to prevent experimental fields from +being set unless the corresponding feature gate was enabled. This would make use +of the existing Kubernetes feature gate tooling. + +This approach would be familiar to Kubernetes users, but would put a lot of +emphasis on the webhook. It would require webhook versioning to be precisely in +line with the CRDs, and edge cases during the upgrade process could get rather +messy. + +### 2: Reuse Alpha API versions +With this approach, we would only allow the use of these fields when using the +alpha API. + +To simplify conversion, new fields will be added to all versions of the API, +with some key exceptions: + +* New fields will be added with an `alpha` prefix to beta and GA API versions. +* Webhook validation would ensure that new fields will only be writable when + using alpha API versions. +* New fields may be removed without replacement while they are still considered + alpha. + +An alpha API field could graduate to beta in the subsequent minor release of the +API. That process would involve: + +* Loosening webhook validation to allow writes to the field with beta API + versions. +* Removing the alpha prefix from the field name in the beta API Changing the + alpha prefix to a beta prefix in the GA API. + +A beta API field could graduate to GA in the subsequent minor release of the +API. That process would involve: + +* Loosening webhook validation to allow writes to the field with GA API + versions. +* Removing the beta prefix from the field name in the GA API. + +This is potentially the most complex of all the options presented. It would +effectively require us to consistently maintain an alpha API version. Of all the +options presented, this is probably the most likely to confuse users and +implementers of the API. \ No newline at end of file