Define standard conformance format for a GatewayClass to communicate what it supports to operators

[mark-church]

What would you like to be added: GatewayClasses encapsulate the capabilities that an implementation of Service APIs supports. However, for the platform operators or application operators who might deploy Gateways in a cluster may not know exactly what within the API a given GatewayClass supports. This issue proposes a standard way for all GatewayClasses to communicate to a user what it supports.

Let's say I have an acme-lb GatewayClass. The GatewayClass should be able to tell me the following:

kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: supported
spec:
  gatewayClassName: supported
  listeners:  
  - protocol: 
      http: supported
      tcp: unsupported
      udp: unsupported
    port: supported
    routes:
      kind: 
        HTTPRoute: supported
        TCPRoute: unsupported
        UDPRoute: unsupported
      selector:
        matchLabels: supported
...
---
HTTPRoute:
  spec:
    hostnames: supported
    rules:
    - matches:
      - path:
          type: 
            prefix: supported
            exact: supported
            regularexpression: unsupported
            implementationspecific: unsupported
        headers:
          type:
            exact: supported
            implementationspecific: 
              contains: supported # Will match traffic with any single header that contains this string
              doesnotcontain: supported # Will match traffic if no headers contain this string 
...

This is a terrible example of the format but you get the idea :) Perhaps OpenAPI has some kind of capability for this.

The goals this aims to achieve:

• Provide a standardized way for all GatewayClasses to communicate which aspects of the API they support.
• Core fields must be supported to achieve conformance, but since extended fields can be optional it will be very useful to understand which extended fields are implemented by a given GatewayClass.
• Custom fields (like annotations, ImplementationSpecific fields, or CRDs that can be referenced) should also be able to be communicated in some way so operators can understand how a GatewayClass has been extended with additional functionality.
• Provide a way for the provider to give additional context to describe implementation-specific aspects of a core, extended, or custom field. The example above with contains illustrates this.

How a GatewayClass provider communicates to the operator what its capabilities are can be done in many different ways:

• Perhaps conformance tests spits this out as a standardized output and providers can simply put this in their docs
• Perhaps comments or fields within a GatewayClass implementation can fill out these fields. This would give the opportunity for implementors to add special comments and context regarding support for specific fields. This might be the case where a field is supported but how it functions requires more context or explanation.

cc @robscott

[kundan2707]

/kind documentation

[fejta-bot]

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity. Mark the issue as fresh with /remove-lifecycle rotten. Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten

[robscott]

/remove-lifecycle rotten

[youngnick]

I think we talked about something like this a long time ago, having this sort of information be passed in the Status of the GatewayClass, so that you can look at a GatewayClass and undestand what features will work, before you start putting Routes into Gateways. It might make sense to have that information in the Gateway status as well though.

[fejta-bot]

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale

[jpeach]

/remove-lifecycle stale /lifecycle frozen

[shaneutt]

Despite this issue being quite old, we the maintainers are still pretty convinced that we want to have this functionality in a future release. This could be particularly useful for conformance test targeting, as well as generally useful for end-users. We are marking this help wanted as we're looking for contributors with strong use cases to help champion and drive this forward.

[youngnick]

tbh this is pretty similar to some of the ideas in #1804

[shaneutt]

Indeed, for anyone visiting this issue please consider it a duplicate of #1804 and follow up over there :+1: