1- # Gateway API Implementer's Guide
1+ # Implementer's Guide
22
33Everything you wanted to know about building a Gateway API implementation
44but were too afraid to ask.
@@ -57,23 +57,22 @@ the cluster, if any.
5757
5858[ versioning ] : /concepts/versioning
5959
60- ### Changes to the Gateway API CRDs are backwards compatible
60+ ### Changes to the Standard Channel CRDs are backwards compatible
6161
62- Part of the contract for Gateway API CRDs is that changes _ within an API version_
63- must be _ compatible_ .
62+ Part of the contract for Standard Channel CRDs is that changes _ within an API
63+ version_ must be _ compatible_ . Note that CRDs that are part of Experimental
64+ Channel do not provide any backwards compatibility guarantees.
6465
65- "Within an API Version" means changes to a CRD that occur while the same API version
66- (` v1alpha2 ` or ` v1 ` for example) is in use, and "compatible" means that any new
67- fields, values, or validation will be added to ensure that _ previous_
68- objects _ will still be valid objects_ after the change.
66+ Although the [ Gateway API versioning policy] ( /concepts/versioning ) largely
67+ aligns with upstream Kubernetes APIs, it does allow for "corrections to
68+ validation". For example, if the API spec stated that a value was invalid but
69+ the corresponding validation did not cover that, it's possible that a future
70+ release may add validation to prevent that invalid input.
6971
70- This means that once Gateway API objects move to the ` v1 ` API version, then _ all_
71- changes must be compatible.
72-
73- This contract also means that an implementation will not fail with a higher version
74- of the API than the version it was written with, because the newer schema being
75- stored by Kubernetes will definitely be able to be serialized into the older version
76- used in code by the implementation.
72+ This contract also means that an implementation will not fail with a higher
73+ version of the API than the version it was written with, because the newer
74+ schema being stored by Kubernetes will definitely be able to be serialized into
75+ the older version used in code by the implementation.
7776
7877Similarly, if an implementation was written with a _ higher_ version, the newer
7978values that it understands will simply _ never be used_ , as they are not present
@@ -83,92 +82,9 @@ in the older version.
8382
8483### CRD Management
8584
86- For a Gateway API implementation to work, the Gateway API CRDs must be installed
87- in the Kubernetes cluster the implementation is watching.
88-
89- Implementations have two possible options: installing CRDs themselves (implementation
90- controlled) or requiring installation by some other mechanism before working
91- (externally controlled). Both have tradeoffs, but implementation controlled has
92- significantly more, and so we DO NOT recommend using implementation controlled
93- methods at this time.
94-
95- Regardless, either way has certain things that SHOULD be true, however:
96-
97- Whatever method is used, infra and cluster admins SHOULD attempt to ensure that
98- the Bundle version of the CRDs is not _ downgraded_ . Although we ensure that
99- API changes are backwards compatible, changing CRD definitions can change the
100- storage version of the resource, which could have unforeseen effects. Most of the
101- time, things will probably work, but if it doesn't work, it will most likely
102- break in weird ways.
103-
104- Additionally, older versions of the API may be missing fields or features, which
105- could be very disruptive for users.
106-
107- Try your best to ensure that the bundle version doesn't roll backwards. It's safer.
108-
109- Implementations SHOULD also handle the Gateway API CRDs _ not_ being present in
110- the cluster without crashing or panicking. Exiting with a clear fatal error is
111- acceptable in this case, as is disabling Gateway API support even if enabled in
112- configuration.
113-
114- Practically, for implementations using tools like ` controller-runtime ` or
115- similar tooling, they may need to check for the _ presence_ of the CRDs by
116- getting the list of installed CRDs before attempting to watch those resources.
117- (Note that this will require the implementation to have ` read ` access to those
118- resources though.)
119-
120- #### Implementation-controlled CRD installation
121-
122- Implementation-controlled CRD installation also includes automatic installation
123- mechanisms such as Helm, if the CRDs are included in a Helm chart with the
124- implementation's installation.
125-
126- Because of significant caveats we DO NOT recommend doing implementation-controlled
127- CRD management at this time.
128-
129- However, if you really must, CRD definitions MAY be installed by implementations,
130- but if they do, they MUST have a way to ensure:
131-
132- - there are no other Gateway API CRDs installed in the cluster before starting, or
133- - that the CRD definitions are only installed if they are a higher bundle version
134- than any existing Gateway API CRDs. Note that even this may not be safe if there
135- are breaking changes in the experimental channel resources, so implementations
136- should be _ very_ careful with doing this.
137-
138- This avoids problems if another implementation is also installed in the cluster
139- and expects a higher version of the CRDs to be installed.
140-
141- The worst outcome here would be two implementations trying to do automatic install
142- of _ different_ CRD versions, resulting in the CRD versions flapping between
143- versions or channels. This would _ not_ produce good outcomes.
144-
145- The safer method for an automatic installation would require the implementation
146- to:
147-
148- - Check if there are any Gateway API CRDs installed in the cluster.
149- - If not, install its most compatible version of the CRDs.
150- - If so, only install its version of the CRDs if the bundle version is higher
151- than the existing one, and the mechanism will also need to check if there are
152- incompatible changes included in any versions as well.
153-
154- This is going to be _ very_ difficult to pull off in practice.
155-
156- It should also be noted that many infra and cluster admins manage CRDs using
157- externally controlled methods that will not be visible to a Gateway
158- implementation, so if you still proceed with automatic installation, it MUST be
159- able to be disabled by the installation owner (whether that is the infra or cluster
160- admin).
161-
162- Because of all these caveats, we DO NOT recommend doing automatic CRD management
163- at this time.
164-
165- #### Externally controlled CRD installation
166-
167- Because of all of the complexities mentioned in the "Implementation controlled"
168- section of this document, we recommend that implementations supply documentation
169- on how to check if CRDs are installed and upgrade versions if required.
170-
171- Additions to this document to add suggested commands here are welcomed.
85+ For information on how to manage Gateway API CRDs, including when it is
86+ acceptable to bundle CRD installation with your implementation, refer to our
87+ [ CRD Management Guide] ( /guides/crd-management.md ) .
17288
17389### Conformance and Version compatibility
17490
@@ -270,7 +186,7 @@ Implementations MAY choose only one GatewayClass out of the pool of otherwise
270186acceptable GatewayClasses if they can only reconcile one, or, if they are capable
271187of reconciling multiple GatewayClasses, they may also choose as many as they like.
272188
273- If something in the GatewayClass renders it incompatibie (at the time of writing,
189+ If something in the GatewayClass renders it incompatible (at the time of writing,
274190the only possible reason for this is that there is a pointer to a ` paramsRef `
275191object that is not supported by the implementation), then the implementation
276192SHOULD mark the incompatible GatewayClass as not ` Accepted ` .
0 commit comments