SupportedFeatures graduation to standard

[LiorLieberman]

GEP-2162 is currently implemented by envoyproxy and istio. We received feedback from the community that we might want to add structure to it, to support future extension and better UX.

Previous discussions happened offline, during community meetings and on https://github.com/kubernetes-sigs/gateway-api/discussions/3128#discussioncomment-9655008.

This purpose of the issue is to get consensus on the structure, and decide to action item and timelines for implementing those before we graduate to standard.

Currently supported features is a flat list of strings. Here are a few suggested options:

1. To support future extensibility by changing it from a list of strings to a list of maps. Something like:

   supportedFeatures:
   - name: HTTPRouteHostRewrite
   description: <description>
   <some other field>: <value>
   - name: HTTPRouteMethodMatching
   ..

2. It can also be tiered, something like:

   supportedFeatures:
   - name: <> (flat exmaple)
   description: <string / URL>
   - profile (or featureGroup): (tiered example)
   name: TLSRoute
   description: <>
   features:
   - name: <>
    description: <> (optional)   

   This allows implementations to flatten featureLists.

   /cc @arkodg @dprotaso @shaneutt @robscott @youngnick @mlavacca @mikemorris I think I captured the main two proposals we came with - please review.

[mikemorris]

I like the idea of option 2️⃣ for bucketing to make human-readability a bit easier.

Putting too much longform descriptive text or URLs into each feature feels awkward, and may have some performance/storage overhead or link rot if any website things change.

Would this be a list of strongly-typed structs (and we would need to define fields now), or just generic maps and we'll standardize keys/values as a future step?

[arkodg]

+1 for 2. or a variant of it

• tiering
  • improves readability
  • reduces information overload
  • can reduce the total amount of text if we assume that an empty features field implies that all the features in the profile or featureGroup are supported
• an optional description / message field allows implementations to specify something implementation specific about the feature, to the user, for e.g.
  • caveats related to the feature e.g. feature only works for listener port 80 and 443
  • more information about how to use the feature

[shaneutt]

I lean towards number 2. Who were the personas of the people asking for the UX improvement from Istio/envoygateway, btw? Were these users of those projects using the feature or developers implementing the feature?

[mlavacca]

+1 for number 2 from my side as well.

[youngnick]

I'm +1 from number 2.

And at least one of the pieces of feedback was from me, wearing my "maintainer worrying about sizes of arrays" persona. We shouldn't have too much of a complexity problem here, since there's not nested layers of config like in Listeners or Routes like in other places, but I was worried about what SupportedFeatures would look like in the (reasonably likely) future where we have a lot of Extended features (say, > 100).

[LiorLieberman]

I lean towards number 2. Who were the personas of the people asking for the UX improvement from Istio/envoygateway, btw? Were these users of those projects using the feature or developers implementing the feature?

We discussed this during the community meeting but for posterity, feedback came from implementors mostly.

I have two concerns:

Would this be a list of strongly-typed structs (and we would need to define fields now), or just generic maps and we'll standardize keys/values as a future step?

This is first one, and we also discussed this during the meeting but we still need to follow up. I don't think we should go with "just generic maps", this could lead to a potential mess and unnecessary creativity from implementations to add things to this map. Also unification would be harder (unless we enforce the map's key names with conformance). OTOH, if we go with strongly-typed struct, we will likely need to re-open the GEP and reach consensus on the structure to avoid breaking changes, which the list of generic maps solution aimed to prevent.

My second concern is about the tiering, if we do that, it will be harder for automations/clis/whatever-machinery that is reading the supportedFeatures to understand what features under this tier/group. Again, this could be solved with yet other new standards.

This is a classic chicken-and-egg problem: to gather user feedback, we need to release it to standard(this is also when more implementations would actually start to implement that), but to do that, we need feedback on the design as this feature aims to enhance the user experience. So the big question, how do we execute on this iteratively, leaving us room for changes based on feedback from users, without making it too hard to deprecate/change parts of the structure.