GAMMA v1 Standard is under-specified #3804
Description
What happened:
The API specification for GAMMA is missing sufficient explanation of how it aligns with Gateway API v1 Standards when it doesn't require using most of the Gateway API components. For example, in https://gateway-api.sigs.k8s.io/mesh/:
The most significant change that GAMMA has introduced to date is that, when configuring a service mesh, individual route resources (such as HTTPRoute) are associated directly with Service resources.
This makes it seem like there is identical functionality for service networking in these two cases, when there is not.
the Gateway and GatewayClass resources are not used when working with a mesh.
No explanation for how to reproduce features provided by xRoute, Gateway, or GatewayClass is provided.
GAMMA has also found it critical to formally define the Service frontend and backend facets. In brief:
- The Service frontend is its name and cluster IP, and
- The Service backend is its collection of endpoint IPs.
This makes it seem as if Gateway API provides API components called frontend/backend, especially in the continued explanation:
This distinction helps the Gateway API to be exact about how routing within a mesh functions, without requiring new resources that largely duplicate the Service.
GAMMA specifies that individual Route resources attach directly to a Service, representing configuration meant to be applied to any traffic directed to the Service.
This is either not true or not sufficiently specified. If the xRoute resource attaches directly to a Service, then in most cases it is unspecified as to what Listener configuration may apply to it. For example, what does allowedRoutes on a Listener mean when a Route can attach directly to a Service?
When one or more Routes are attached to a Service, requests that do not match at least one of the Routes will be rejected. If no Routes are attached to a Service, requests to the Service simply proceed per the mesh's default behavior (usually resulting in the request being forwarded as if the mesh were not present).
This implies that mesh is always present and enabled. Also, in most cases it is unspecified as to what back end Policy configuration may apply to it if there is no backendRef specified. See #3554.
Which Routes attach to a given Service is controlled by the Routes themselves (working with Kubernetes RBAC): the Route simply specifies a parentRef that is a Service, rather than a Gateway.
This is under-specified. A Route can have a backendRef that is a Service and a parentRef that is a Service? Where does the traffic end up in that case? Is backendRef invalid for service mesh?
The relationship between the Route's Namespace and the Service's Namespace is important
The constructs producer route and consumer route in this section are not a part of the API so these type of claims made here are probably irrelevant. It is also currently under-specifed because there is no way for a user to find out whether a Route is a producer or consumer route, and a Route could be both.
Secondly, the text in https://gateway-api.sigs.k8s.io/mesh/service-facets/ implies that the frontend/backend service facets is in active development in Gateway API and it does not seem to be. The explanation of service facets has nothing to do with Gateway API so far, and detracts from a good understanding of the features it supports.
What you expected to happen:
Clarifications in the GAMMA documentation.