Kubernetes Gateway API v1.1 Interpretation, do you understand it?

A few days ago, the K8s Network SIG released the Gateway API (gwapi) v1.1[1]. This version includes the GA (general availability) of many important features, as well as the introduction of some experimental features. These two parts were released through the standard channel and experimental channel respectively.

Release channels are used to indicate the stability of features within the Gateway API. All new features and resources start in the experimental release channel and may be promoted to the standard release channel or completely deprecated from the API during subsequent iterations.

The following figure gives you a clear understanding of gwapi's release channels.

picture

Among these updates, the most important one in my opinion is the GA support for service mesh, which means that the service mesh standard API has taken another step towards unification. Almost two years ago, I wrote about what the SMI and the GAMMA initiative for the Gateway API meant. When gwapi was almost 1.0, SMI was archived after a few months of stopping updates.

Standard release channels

GRP Route GA

The release of GRPCRoute API v1 indicates that it can be used stably in production environments and will be supported and maintained for a long time. At the same time, v1alpha2 is marked as deprecated and will be removed in future versions.

Service Mesh Support GA

gwapi has officially graduated its support for service mesh and entered the standard release channel. After implementing support for the mesh, the same API can be used to manage east-west (inter-service) traffic, so policies built on gwapi can be reused in the mesh. If you are interested, you can read last year's article Exploring the working mechanism of the Gateway API in Service Mesh, or refer to the official documentation [2].

Starting from v1.1, xRoute can attach to (parent resource) Gateway and Service. Specifically, parentRef.kind can be Gateway (default) and Service. For example:

HTTPRoute for Gateway: 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: ...

Profiles and reports for consistency checks GA

The Conformance Reporting API and corresponding test suite have been upgraded to GA v1.

About the Conformance Report:

A compliant implementation of the Gateway API specification is one that passes the conformance tests included in each gwapi bundle version release (e.g. gateway.networking.k8s.io/bundle-version: v1.1.0). All gwapi implementations must pass the conformance tests and may not skip any of the tests.

In version v1, the ConformanceReport API extends the two fields mode and gatewayAPIChannel. The former is used to specify the working mode of the implementation, and the latter identifies the release channel applicable to the report: standard release or experimental release.

Reports have also been reorganized in a more structured way, and implementations can now add information about how the tests were run and provide steps to reproduce the results.

ParentRef's Port field GA

Previously, when multiple listeners were configured on a Gateway, if you wanted to attach a route to a specific port,

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

You can use sectionName to specify the name of the listener, so you need to set a name for the listener using the name field.

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

This can now be done using the port field, which is also unique on the gateway, eliminating the need to use the name field.

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

Experimental Release Channel

Support session persistence through BackendLBPolicy

Introduced session persistence support via BackendLBPolicy, a feature from the Gateway Enhancement Proposal GEP-1619[3].

Session persistence means that client requests are directed to the same backend server for the duration of a "session".

When the client directly provides information (such as a cookie in a request header), the proxy uses 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 and go directly to the backend server with which the session was previously established.

See the official definition of session persistence [4].

The session persistence of gwapi can be applied to the service granularity or to a single route. The latter has a higher priority and will override the session persistence configuration at the service granularity.

Session persistence at the route granularity is configured via sessionPersistence in the route rule.

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

Service-level session persistence is configured via BackendLBPolicy.

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

Note: The type in the core API is Cookie, and the implementation can be extended to support any request header, the type is Header.

Client certificate verification

The Gateway Enhancement Proposal GEP-91[5] discusses how to verify the TLS certificate provided by the front-end client to the server during the TLS handshake protocol, which can be regarded as client authentication in mTLS.

In the official core API design, the CA certificate in the ConfigMap specified by the listener's tls.frontendValidation is used to authenticate the client. The core API only supports one ConfigMap, and the implementation is extensible 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[6] is a type in gwapi that specifies the TLS configuration for connections from the gateway to the backend Pod (or multiple Pods) through the Service API object. It is the opposite of client authentication and is an authentication of the backend service.

There are two types of authentication for backend services:

• The gateway authenticates the backend service, that is, the CA certificate used for authentication is configured on the gateway.
• There is client authentication, which is the passthrough mode of the gateway.

picture

Compared with v1alpha2 in v1.0, the major changes in v1alpha3 in v1.1 are:

• The targetRef field is now a list of targetRefs and these references no longer contain a 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 uses Envoy, and FSM Gateway uses Pipy. Different load balancers have different configurations, and gwapi cannot provide a common interface. Therefore, a configuration interface is provided on the GatewayClass API through the spec.parametersRef field.

However, the configuration of GatewayClass is global and applies to all Gateway instances. It cannot be configured for a specific Gateway instance, which makes it difficult to meet the needs. Then there is the Gateway Enhancement Proposal GEP-1867[7].

In a similar way to GatewayClass, the Gateway API in this proposal configures `LocalParametersReference`[8] through the infrastructure.parametersRef field, which is defined by each gwapi implementation.

Other updates

In addition to the functions of the two release channels, there are other updates that will not be introduced one by one.

1. gwctl:

The get command is extended to support gateways, gatewayclasses, and namespaces.

The describe command now supports describing policycrds and namespaces.

Added ability to filter resources using tags (via -l option).

Fixed an error that was not described when describing gatewayclasses.

2. Verification changes: It is no longer necessary to configure TLS on Gateway Listeners, allowing for more flexible TLS configuration.
3. Conformance Testing: The conformance profiles have been renamed and a new Mesh-GRPC profile has been added.
4. Dependency updates: Gateway API upgraded to Go v1.22 and Kubernetes v1.30.
5. Cleanup: Removed validation webhook, CEL validation is now built into CRDs instead of webhook.

For more information, please refer to the v1.1.0 update notes[9].

References

[1] v1.1 version: https://github.com/kubernetes-sigs/gateway-api/releases/tag/v1.1.0

[2] Official documentation: https://gateway-api.sigs.k8s.io/mesh/

[3] Gateway Enhancement Proposal GEP-1619: https://gateway-api.sigs.k8s.io/geps/gep-1619

[4] Session persistence definition: https://gateway-api.sigs.k8s.io/geps/gep-1619/?h=backendlbpolicy#defining-session-persistence

[5] Gateway Enhancement Proposal GEP-91: https://gateway-api.sigs.k8s.io/geps/gep-91/

[6] BackendTLSPolicy: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy

[7] Gateway Enhancement Proposal GEP-1867: https://gateway-api.sigs.k8s.io/geps/gep-1867

[8] LocalParametersReference: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.LocalParametersReference

[9] v1.1.0 update notes: https://github.com/kubernetes-sigs/gateway-api/releases/tag/v1.1.0