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