Skip to content

Commit 6c4c497

Browse files
robscottrobscott
committed
Adding GEP 922: Adding Gateway API Versioning
1 parent 2b383e1 commit 6c4c497

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎site-src/geps/gep-922.md

+163
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# GEP-922: Gateway API Versioning
2+
3+
* Issue: [#922](https://github.com/kubernetes-sigs/gateway-api/issues/922)
4+
* Status: Implementable
5+
6+
## TLDR
7+
Each Gateway API release will be represented by a bundle version that represents
8+
that specific combination of CRDs, API versions, and validating webhook. To
9+
enable experimental fields, a new experimental set of CRDs will be included with
10+
future releases.
11+
12+
## Goals
13+
Provide a path for implementations to support:
14+
15+
* Users should have a predictable experience when interacting with Gateway API.
16+
* The API should be able to continue to safely evolve, including:
17+
* Loosening validation
18+
* Transitioning required fields to optional
19+
* Adding new fields at an alpha stability level
20+
21+
## Introduction
22+
This GEP details how we should approach future releases of Gateway API. This is
23+
intended as another step towards building consensus. Once merged, it will be
24+
considered implemented once this content is fully documented.
25+
26+
## Version Terminology
27+
Gateway API has two related but different versioning schemes:
28+
29+
### 1. API Versions (ex: v1alpha2)
30+
Each API version provides a unique way to interact with the API. Significant
31+
changes such as removing or renaming fields will be represented here.
32+
33+
### 2. Bundle Versions (ex: v0.4.0)
34+
Bundle versions are broader in scope. They use semantic versioning and include
35+
the following:
36+
37+
* API Types/CRDs
38+
* Validating Webhook
39+
40+
Each bundle may include multiple API versions, potentially introducing new ones
41+
and/or removing old ones as part of a new bundle.
42+
43+
## Limitations of Webhook and CRD Validation
44+
CRD and webhook validation is not the final validation i.e. webhook is “nice UX”
45+
but not schema enforcement. This validation is intended to provide immediate
46+
feedback to users when they provide an invalid configuration, but can not
47+
completely be relied on because it:
48+
49+
* Is not guaranteed to be present or up to date in all clusters.
50+
* Will likely never be sufficient to cover all edge cases.
51+
* May be loosened in future API releases.
52+
53+
## Role Requirements
54+
When implementing or using Gateway API, each role has a unique set of
55+
requirements to ensure we're providing a consistent experience.
56+
57+
### API Authors:
58+
* MUST support API versions for at least 1 year, starting with v1alpha2.
59+
* MUST provide conversion between API versions, starting with v1alpha2.
60+
* MAY include the following changes to an existing API version with a new bundle
61+
**patch** version:
62+
* Clarifications to godocs
63+
* Loosening validation to fix a bug (not to enable a new feature)
64+
* Fixes to typos
65+
* MAY include the following changes to an existing API version with a new bundle
66+
**minor** version:
67+
* Everything that is valid in a patch release
68+
* New alpha API fields or resources
69+
* Loosened validation
70+
* Making required fields optional
71+
* Removal of experimental fields
72+
* Removal of experimental resources
73+
* Graduation of fields or resources (alpha->beta, beta->ga)
74+
* MAY introduce a new **API version** with a new bundle minor version, which may
75+
include:
76+
* Everything that is valid in a minor release
77+
* Renamed fields
78+
* Removal/tombstoning of beta fields
79+
80+
### Implementers:
81+
* MUST handle fields with loosened validation without crashing
82+
* MUST handle fields that have transitioned from required to optional without
83+
crashing
84+
* MUST NOT rely on webhook or CRD validation as a security mechanism. If field
85+
values need to be escaped to secure an implementation, both webhook and CRD
86+
validation can be bypassed and cannot be relied on. Instead, implementations
87+
should implement their own escaping or validation as necessary.
88+
89+
### Installers:
90+
* MUST install a full Gateway API bundle, with matching CRD and webhook
91+
versions.
92+
93+
## Adding Experimental Fields
94+
Over time, it will be useful to add experimental fields to the API. In upstream
95+
Kubernetes, those would generally be guarded with feature gates. With Gateway
96+
API we will accomplish by releasing experimental versions of our CRDs.
97+
98+
With this approach, we achieve a similar result. Instead of using feature gates
99+
and validation to prevent fields from being set, we just release separate CRDs.
100+
Once the API reaches beta, each bundle release can include 2 sets of CRDs,
101+
stable and experimental.
102+
103+
New fields will be added to the experimental set of CRDs first, and may graduate
104+
to stable APIs later. Experimental fields will be marked with the
105+
`+experimental` annotation in Go type definitions. Gateway API CRD generation
106+
will exclude these fields from stable CRDs. Experimental fields may be removed
107+
from the API.
108+
109+
If experimental fields are removed or renamed, the original field name should be
110+
removed from the go struct, with a tombstone comment ensuring the field name
111+
will not be reused.
112+
113+
Each CRD will be published with annotations that indicate their bundle version
114+
and channel:
115+
116+
```
117+
gateway.networking.k8s.io/bundle-version: v0.4.0
118+
gateway.networking.k8s.io/channel: stable|experimental
119+
```
120+
121+
## Alternatives Considered
122+
### 1. Use Webhook to Implement Feature Gates
123+
This option would involve using the webhook to prevent experimental fields from
124+
being set unless the corresponding feature gate was enabled. This would make use
125+
of the existing Kubernetes feature gate tooling.
126+
127+
This approach would be familiar to Kubernetes users, but would put a lot of
128+
emphasis on the webhook. It would require webhook versioning to be precisely in
129+
line with the CRDs, and edge cases during the upgrade process could get rather
130+
messy.
131+
132+
### 2: Reuse Alpha API versions
133+
With this approach, we would only allow the use of these fields when using the
134+
alpha API.
135+
136+
To simplify conversion, new fields will be added to all versions of the API,
137+
with some key exceptions:
138+
139+
* New fields will be added with an `alpha` prefix to beta and GA API versions.
140+
* Webhook validation would ensure that new fields will only be writable when
141+
using alpha API versions.
142+
* New fields may be removed without replacement while they are still considered
143+
alpha.
144+
145+
An alpha API field could graduate to beta in the subsequent minor release of the
146+
API. That process would involve:
147+
148+
* Loosening webhook validation to allow writes to the field with beta API
149+
versions.
150+
* Removing the alpha prefix from the field name in the beta API Changing the
151+
alpha prefix to a beta prefix in the GA API.
152+
153+
A beta API field could graduate to GA in the subsequent minor release of the
154+
API. That process would involve:
155+
156+
* Loosening webhook validation to allow writes to the field with GA API
157+
versions.
158+
* Removing the beta prefix from the field name in the GA API.
159+
160+
This is potentially the most complex of all the options presented. It would
161+
effectively require us to consistently maintain an alpha API version. Of all the
162+
options presented, this is probably the most likely to confuse users and
163+
implementers of the API.

0 commit comments

Comments
 (0)