1# GEP-2162: Supported features in GatewayClass Status
2
3* Issue: [#2162](https://github.com/kubernetes-sigs/gateway-api/issues/2162)
4* Status: Provisional
5
6## TLDR
7
8This GEP proposes to enhance the [GatewayClassStatus](https://github.com/kubernetes-sigs/gateway-api/blob/f2cd9bb92b4ff392416c40d6148ff7f76b30e649/apis/v1beta1/gatewayclass_types.go#L185) to include a list of Gateway API features supported by the installed GatewayClass.
9
10## Goals
11
12* Improve UX by enabling users to easily see what features the implementation (GatewayClass) support.
13
14* Standardize features and conformance tests names.
15
16* Automatically run conformance tests based on the supported features populated in GatewayClass status.
17
18* Provide foundation for tools to block or warn when unsupported features are used.
19
20
21## Non-Goals
22
23* Validate correctness of supported features published by the implementation.
24 Meaning we don't intend to verify whether the supported features reported by
25 the implementation are indeed supported.
26
27 However, the supported features in the status of the GatewayClass should
28 make it very easy for any individual to run conformance tests against the
29 GatewayClass using our conformance tooling.
30
31## Introduction
32
33The current [GatewayClassStatus](https://github.com/kubernetes-sigs/gateway-api/blob/f2cd9bb92b4ff392416c40d6148ff7f76b30e649/apis/v1beta1/gatewayclass_types.go#L185 is only used to store conditions the controller publishes.
34
35Partnered with the [Conformance Profiles](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709.md) work, we want to:
36
371. Improve UX by enabling users to easily see what features the implementation(GatewayClass) support.
381. Standardize features and conformance tests names.
391. Automatically run conformance tests based on the supported features populated in GatewayClass status.
401. Potentially build tooling to block or warn when unsupported features are used (more under [Future Work](#future-work)).
41
42This doc proposes to enhance the GatewayClassStatus API so implementations could publish a list of features they support/don't support.
43
44Implementations **must** publish the supported features before Accepting the GatewayClass, or in the same operation.
45
46Implementations are free to decide how they manage this information. A common approach could be to maintain static lists of supported features or using predefined sets.
47
48Note: implementations must keep the published list sorted in ascending alphabetical order.
49
50## API
51
52This GEP proposes API changes describes as follow:
53
54* Update the `GatewayClassStatus` struct to include a string-represented list of `SupportedFeatures`.
55
56
57```go
58// GatewayClassStatus is the current status for the GatewayClass.
59type GatewayClassStatus struct {
60 // Conditions is the current status from the controller for
61 // this GatewayClass.
62 //
63 // Controllers should prefer to publish conditions using values
64 // of GatewayClassConditionType for the type of each Condition.
65 //
66 // +optional
67 // +listType=map
68 // +listMapKey=type
69 // +kubebuilder:validation:MaxItems=8
70 Conditions []metav1.Condition `json:"conditions,omitempty"`
71
72 // SupportedFeatures is the features the GatewayClass support.
73 // <gateway:experimental>
74 // +kubebuilder:validation:MaxItems=64
75 SupportedFeatures []string `json:"supportedFeatures,omitempty"`
76}
77```
78
79## Understanding SupportedFeatures field
80
81Its important to define how we read the list of `SupportedFeatures` we report.
82
83We have no supported features for core features. If an implementation reports a resource name e.g `HTTPRoute` as a supportedFeature it means it supports all its core features.
84In other words, supporting the resource's core features is a requirement for the implementation to say that it supports the resource.
85
86For Extended/Implementation-specific features we have the supported features names.
87
88An example of a GatewayClass Status with the SupportedFeatures reported would look like:
89
90```yaml
91apiVersion: gateway.networking.k8s.io/v1beta1
92kind: GatewayClass
93...
94status:
95 conditions:
96 - lastTransitionTime: "2022-11-16T10:33:06Z"
97 message: Handled by XXX controller
98 observedGeneration: 1
99 reason: Accepted
100 status: "True"
101 type: Accepted
102 supportedFeatures:
103 - HTTPRoute
104 - HTTPRouteHostRewrite
105 - HTTPRoutePortRedirect
106 - HTTPRouteQueryParamMatching
107
108```
109## Standardize features and conformance tests names
110
111Before we add the supported features into our API, it is necessary to establish standardized naming and formatting conventions.
112
113### Formatting Proposal
114
115#### Feature Names
116
117Every feature should:
118
1191. Start with the resource name. i.e HTTPRouteXXX
1202. Follow the PascalCase convention. Note that the resource name in the string should come as is and not be converted to PascalCase, i.e HTTPRoutePortRedirect and not HttpRoutePortRedirect.
1213. Not exceed 128 characters.
1224. Contain only letters and numbers
123
124#### Conformance test names
125
126Conformance tests file names should try to follow the the `pascal-case-name.go` format.
127For example for `HTTPRoutePortRedirect` - the test file would be `httproute-port-redirect.go`.
128
129We should treat this guidance as "best effort" because we might have test files that check the combination of several features and can't follow the same format.
130
131In any case, the conformance tests file names should be meaningful and easy to understand.
132
133
134## Followups
135
136Before we make the changes we need to;
137
1381. Change the names of the supported features and conformance tests that don't conform with the formatting rules.
139
140
141## Alternatives
142
143### Re-using ConformanceProfiles structs
144
145We could use the same structs as we do in conformance profile object, more specifically, the [ProfileReport](https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/apis/v1alpha1/profilereport.go#LL24C6-L24C19) struct.
146
147Though it would be nice to have only one place to update, these structs seems to include much more data relevant to the conformance report but not for our use case.
148
149That said, conformance profiles are still at experimental stage, we could explore the option to create a shared struct that will be used both for the conformance reports and for the GatewayClass status.
150
151### Instruct users to read from the future conformance profiles report
152
153The current plan for conformance profiles is to also include centralized reporting. (more info in [gep-1709](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709.md))
154We could wait for this to be implemented and instruct users to read from that source to determine what features their installed GatewayClass support.
155
156However, having the supported features published in the GatewayClass Status adds the following values:
157
158* We could build a mechanism or a tool to block or warn when unsupported features are used.
159* Users will be able to select the GatewayClass that suits their needs without having to refer to documentation or conformance reports.
160
161This does not cover a future piece of work we want to implement which is to warn/block users from applying a Gateway API object if the installed GWC doesn't support it. (originally suggested in [#1804](https://github.com/kubernetes-sigs/gateway-api/issues/1804)).
162
163
164## References
165
166[discussion #2108](https://github.com/kubernetes-sigs/gateway-api/discussions/2108)
167[#1804](https://github.com/kubernetes-sigs/gateway-api/issues/1804)
168
169## Future Work
170
171### Research the development of an unsupported feature warning/blocking mechanism
172Once the GatewayClass features support are is published into the status we could look into;
173
1741. Using the supported features in the webhook to validate or block attempts to apply manifests with unsupported features.
175
176 * Developing such mechanism looks like it would have to include cross-resource validation. (checking the GatewayClass while trying to apply a Route for example). This comes with a lot of caveats and we will need consider it carefully.
177
1782. Build tooling to check and warn when unsupported features are used.
179
1803. Add a table with feature name and description to document what each feature means.
181
182### Add Gateway API Version field to the GatewayClass Status
183
184We got some feedback that it will be useful to indicate what what Gateway API version the implementation supports. So when we have supported features published in the GatewayClass Status, users will also be able to understand that those are the supported features for a specific Gateway API version.
185
186This work is likely to require its own small GEP but ideally what this field would mean is that an implementation supports Max(vX.X).
187
188The value of it is to provide a better user experience and also more foundation for tools to be able to warn for example when a GatewayClass and CRDs have mismatched versions.
View as plain text