Gateway API for Service Mesh¶

Standard Channel since v1.1.0

The GAMMA initiative work for supporting service mesh use cases has been part of the Standard Channel since v1.1.0 and is considered GA. For more information refer to our versioning guide.

The "GAMMA initiative" refers to the group that is defining how Gateway API can be used for Service Mesh. To date, this group has been able to define service mesh support in the Gateway API with relatively small changes. 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 is primarily because there will typically only be one mesh active in the cluster, so the Gateway and GatewayClass resources are not used when working with a mesh. In turn, this leaves the Service resource as the most universal binding point for routing information.

Since the Service resource is unfortunately complex, with several overloaded or underspecified aspects, 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 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.

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).

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.

kind: HTTPRoute
metadata:
  name: smiley-route
  namespace: faces
spec:
  parentRefs:
    - name: smiley
      kind: Service
      group: core
      port: 80
  rules:
    ...

Work in Progress

There is ongoing work around the relationship between producer routes and consumer routes.

The relationship between the Route's Namespace and the Service's Namespace is important:

Same Namespace

A Route in the same Namespace as its Service is called a producer route, since it is typically created by the creator of the workload in order to define acceptable usage of the workload (for example, Ana would deploy both the workload and the Route). All requests from any client of the workload, from any Namespace, will be affected by this Route.

The Route shown above is a producer route.
Different Namespaces

A Route in a different Namespace than its Service is called a consumer route. Typically, this is a Route meant to refine how a consumer of a given workload makes request of that workload (for example, configuring custom timeouts for that consumer's use of the workload). This Route will only affect requests from workloads in the same Namespace as the Route.

For example, this HTTPRoute would cause all clients of the smiley workload in the fast-clients Namespace to have a 100ms timeout:
```
kind: HTTPRoute
metadata:
  name: smiley-route
  namespace: fast-clients
spec:
  parentRefs:
  - name: smiley
    namespace: faces
    kind: Service
    group: core
    port: 80
  rules:
    ...
    timeouts:
      request: 100ms
```

One important note about Routes bound to Services is that multiple Routes for the same Service in a single Namespace - whether producer routes or consumer routes - will be combined according to the Gateway API Route merging rules. As such, it is not currently possible to define distinct consumer routes for multiple consumers in the same Namespace.

For example, if the blender workload and the mixer workload both live in the foodprep Namespace, and both call the oven workload using the same Service, it is not currently possible for blender and mixer to use HTTPRoutes to set different timeouts for their calls to the oven workload. blender and mixer would need to be moved into separate Namespaces to allow this.

Request Flow¶

A typical east/west API request flow when a GAMMA-compliant mesh is in use looks like:

A client workload makes a request to http://foo.ns.service.cluster.local.
The mesh data plane intercepts the request and identifies it as traffic for the Service foo in Namespace ns.
The data plane locates Routes associated with the foo Service, then:

a. If there are no associated Routes, the request is always allowed, and the foo workload itself is considered the destination workload.

b. If there are associated Routes and the request matches at least one of them, the backendRefs of the highest-priority matching Route are used to select the destination workload.

c. If there are associated Routes, but the request matches none of them, the request is rejected.
The data plane routes the request on to the destination workload (most likely using endpoint routing, but it is allowed to use Service routing).