Kubernetes Gateway API v1.1 Released: New Standard Features and Experimental Enhancements

The Kubernetes SIG Network announced version 1.1 of Gateway API. This update sees several key features moving to the Standard Channel (GA), including support for service mesh and GRPCRoute. Additionally, new experimental features such as session persistence and client certificate verification have been introduced.

The v1.1 release marks the transition of four highly anticipated features from experimental to Standard. This signifies confidence in the API's stability and provides backward compatibility guarantees. Standard Channel features will continue to evolve with backwards-compatible enhancements.

Gateway API now supports service mesh, enabling users to manage both ingress and mesh traffic with a unified API. Routes like HTTPRoute can now reference a Service as a parentRef, allowing precise traffic control for specific services. To learn more about this feature, check out the Gateway API documentation.

A possible implementation of canary deployment with HTTPRoute is the following:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: color-canary
  namespace: faces
spec:
  parentRefs:
    - name: color
      kind: Service
      group: ""
      port: 80
  rules:
  - backendRefs:
    - name: color
      port: 80
      weight: 50
    - name: color2
      port: 80
      weight: 50

This configuration splits traffic 50/50 between the original color Service and the color2 Service in the faces namespace.

GRPCRoute has been part of the Standard Channel since v1.1.0. For users of the experimental channel, it is recommended to wait for controller updates before upgrading to the standard channel version. Meanwhile, the experimental channel version in v1.1 includes both v1alpha2 and v1 API versions.

HTTPRoute is a Gateway API type for specifying the routing behavior of HTTP requests. Each Route provides a method to reference the parent resources it intends to attach to. Typically, this will be Gateways, but implementations have the flexibility to support other types of parent resources as well. The port field has been added to ParentReference, allowing resources to be attached to Gateway Listeners, Services, or other parent resources by specifying the port. This enables attachment to multiple Listeners simultaneously.

Example of attaching an HTTPRoute to specific Gateway Listeners by port:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: httproute-example
spec:
  parentRefs:
  - name: acme-lb
    port: 8080

Note that the target Gateway needs to allow HTTPRoutes from the route's namespace to be attached for the attachment to be successful, and binding to a port also allows attaching to multiple listeners at once

The conformance report API now includes the mode field and gatewayAPIChannel (standard or experimental). The gatewayAPIVersion and gatewayAPIChannel are automatically populated, and the reports are better structured, allowing implementations to include testing details and reproduction steps.

A new addition to the experimental channel is focused on Gateways. In particular, it is now possible to configure client certificate verification for each Gateway Listener using the new frontendValidation field within TLS. This field allows the configuration of CA Certificates to validate client certificates.

An example of configuration is the following:

apiVersion: gateway.networking.k8s.io/v1
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

Another new addition to the experimental channel is Session persistence. It is introduced via a new policy (BackendLBPolicy) for Service-level configuration and as fields within HTTPRoute and GRPCRoute for route-level configuration. These settings include session timeouts, session name, session type, and cookie lifetime.

An Example of BackendLBPolicy configuration for cookie-based session persistence is the following:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendLBPolicy
metadata:
  name: lb-policy
  namespace: foo-ns
spec:
  targetRefs:
  - group: core
    kind: service
    name: foo
  sessionPersistence:
    sessionName: foo-session
    absoluteTimeout: 1h
    idleTimeout: 30m
    type: Cookie
    cookieConfig:
      lifetimeType: Session

To ensure consistent TLS terminology, breaking changes have been made to BackendTLSPolicy, resulting in a new API version (v1alpha3). Implementations must handle this version upgrade by updating references and configurations accordingly.

Other notable changes:

• targetRef becomes targetRefs
• tls becomes validation
• tls.caCertRefs becomes validation.caCertificateRefs
• tls.wellKnownCACerts becomes validation.wellKnownCACertificates

Unlike other Kubernetes APIs, upgrading to the latest Kubernetes version isn't necessary to use the newest Gateway API. As long the cluster is on Kubernetes 1.26 or later, it is possible to start using the latest Gateway API immediately.