Interpretation of Kubernetes Gateway API v1.1

A few days ago, the K8s Network SIG released version 1.1 of the Gateway API (abbreviated as gwapi), which includes several major features being promoted to General Availability (GA) and the introduction of some experimental features. These are released through standard and experimental channels, respectively.

The release channels indicate the stability of features within the Gateway API. All new features and resources start from the experimental release channel and may be upgraded to the standard release channel in subsequent iterations, or they might be completely removed from the API.

The following image provides a clear understanding of the gwapi release channels.

Among these updates, the most important in my view is the support for service meshes going GA, marking another step towards a unified standard API for service meshes. About two years ago, I wrote about What the SMI and Gateway API GAMMA initiative meant when gwapi was close to version 1.0, SMI was archived a few months after it stopped updating.

Standard Release Channel

GRPCRoute GA

The release of GRPCRoute API's v1 version signifies its stable usability in production environments, receiving long-term support and maintenance. Meanwhile, the v1alpha2 version has been marked as deprecated and will be removed in future releases.

Service Mesh Support GA

The support for service meshes by gwapi has officially graduated and entered the standard release channel. After implementing mesh support, the same API can manage traffic east-west (between services), and thus, strategies built on gwapi can be reused within the mesh. Those interested can review the piece I wrote last year on Explore the mechanics of the Gateway API within the Service Mesh and refer to the official documentation.

Starting from v1.1, xRoute can be attached to Gateway and Service as parent resources, specifically shown as parentRef.kind can be Gateway (default) or Service. For example:

HTTPRoute for Gateways: Omit kind: Gateway.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-app-1
spec:
  parentRefs:
    - name: my-gateway
  rules:
    ...

HTTPRoute for Service Mesh:

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

Conformance Profiles and Reports GA

The Conformance Report API and its corresponding test suite have been upgraded to GA v1 version.

Regarding Conformance Reports:

A Gateway API compliant implementation refers to those passing the conformance tests included in each gwapi bundle release, such as gateway.networking.k8s.io/bundle-version: v1.1.0. All gwapi implementations must pass the conformance tests without skipping any.

In the v1 version, the ConformanceReport API has expanded the mode and gatewayAPIChannel fields. The former is used to specify the operational mode of the implementation, and the latter indicates the release channel applicable to the report: standard release standard or experimental release experimental.

Reports are also reorganized in a more structured manner, allowing implementations to add information about how tests were conducted and provide reproduction steps.

ParentRef’s Port Field GA

Previously, when a Gateway had multiple listeners configured, to attach routes to a specific port,

listeners:
  - name: foo
    protocol: HTTP
    port: 8080
    ...
  - name: bar
    protocol: HTTP
    port: 8090
    ...
  - name: baz
    protocol: HTTP
    port: 8090
    ...

you could use sectionName to specify the name of the listener, therefore you needed to set a name for the listener via the name field.

spec:
  parentRefs:
  - name: acme-lb
    sectionName: foo

Now, you can achieve this through the port field, as ports are also unique on the gateway, eliminating the need for the name field.

spec:
  parentRefs:
  - name: acme-lb
    port: 8080

Experimental Release Channel

Session Persistence Supported through BackendLBPolicy

Session persistence support is introduced through BackendLBPolicy, originating from Gateway Enhancement Proposal GEP-1619.

Session persistence refers to directing client requests to the same backend server during the duration of a “session”.

When clients directly provide information (such as cookies in the request header), proxies use it as a reference to direct traffic to a specific server. Persistence is an exception to load balancing: persistent client requests bypass the proxy’s load balancing algorithm, reaching the backend server previously established for the session.

See the official definition of session persistence.

gwapi’s session persistence can apply at the service level or to individual routes, with the latter having higher priority and overriding the service-level session persistence configuration.

Session persistence at the route level is configured within the route rules under sessionPersistence.

kind: HTTPRoute
metadata:
  name: routeX
spec:
  rules:
  - matches:
    - path:
      value: /a
    backendRefs:
    - name: servicev1
    sessionPersistence:
      name: session-a

Service-level session persistence is configured through BackendLBPolicy.

kind: BackendLBPolicy
metadata:
  name: lbp
spec:
  targetRef:
    kind: Service
    Name: servicev1
  sessionPersistence:
    sessionName: service-cookie
    type: Cookie

Note: In the core API, the type is Cookie, but implementations can extend to support any request header with type Header.

Client Certificate Validation

Gateway Enhancement Proposal GEP-91 discusses how to validate the TLS certificates provided by frontend clients during the TLS handshake process, which can be considered client authentication in mTLS.

In the core API design, client authentication is specified using the CA certificates in the tls.frontendValidation ConfigMap specified for the listener. The core API only supports one ConfigMap, but implementations can extend to support multiple ConfigMaps or other types such as Service.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: client-validation-basic
spec:
  gatewayClassName: acme-lb
  listeners:
  - name: foo-https
    protocol: HTTPS
    port: 443
    hostname: foo.example.com
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: foo-example-com-cert
      frontendValidation:
        caCertificateRefs:
        - kind: ConfigMap
          group: ""
          name: foo-example-com-ca-cert

BackendTLSPolicy

BackendTLSPolicy is a type in gwapi for specifying the TLS configuration of connections from the gateway to backend Pods (or multiple Pods) through the Service API object. Opposite to client authentication, it is authentication of backend services.

There are two types of authentication for backend services:

• Authentication of backend services by the gateway, i.e., configuring the CA certificate for authentication at the gateway.
• Client authentication, also known as gateway passthrough mode.

Compared to v1alpha2 in v1.0, the significant changes in v1alpha3 of v1.1 include:

• The targetRef field has now been changed to a list of targetRefs, and these references no longer include the namespace field.
• The tls field has been renamed to validation
• The caCertRefs field has been renamed to caCertificateRefs
• The wellKnownCACerts field has been renamed to wellKnownCACertificates

apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: tls-upstream-auth
spec:
  targetRefs:
    - kind: Service
      name: auth
      group: ""
  validation:
    caCertificateRefs:
      - kind: ConfigMap
        name: auth-cert
        group: ""
        hostname: auth.example.com

Gateway Parameters

Different gwapi implementations use different load balancers, such as Envoy Gateway using Envoy, and FSM Gateway using Pipy. Different load balancers have their own unique configurations, and gwapi cannot provide a universal interface. Thus, the GatewayClass API offers a configuration interface through the spec.parametersRef field.

However, the configuration of GatewayClass is global, applicable to all Gateway instances, and cannot be configured for specific Gateway instances, making it difficult to meet specific needs. Then there is Gateway Enhancement Proposal GEP-1867.

Similar to GatewayClass, the Gateway API in this proposal configures LocalParametersReference through the infrastructure.parametersRef field, specifically defined by each gwapi implementation.

Other Updates

Besides the features of the two release channels, there are other updates that won’t be detailed one by one.

1. gwctl:

• The get command has been expanded to support gateways, gatewayclasses, and namespaces.
• The describe command now supports describing policycrds and namespaces.
• Added the capability to filter resources using labels (via the -l option).
• Fixed an error that was not described when describing gatewayclasses.

2. Validation Changes: It’s no longer necessary to configure TLS on Gateway Listeners, enabling more flexible TLS configurations.

3. Consistency Testing: The conformance configuration file has been renamed, and a new Mesh-GRPC configuration file has been added.

4. Dependency Updates: Gateway API has been upgraded to Go v1.22 and Kubernetes v1.30.

5. Cleanup: The validation webhook has been removed, with CEL validation now built into CRDs instead of the webhook.

For more details, refer to the v1.1.0 release notes.