New Experimental Features in Gateway API v1.0
Authors: Candace Holman (Red Hat), Dave Protasowski (VMware), Gaurav K Ghildiyal (Google), John Howard (Google), Simone Rodigari (IBM)
Along with stabilizing some of the core functionality in the API, a number of exciting new experimental features have been added.
Backend TLS Policy
BackendTLSPolicy is a new Gateway API type used for specifying the TLS configuration of the connection from the Gateway to backend Pods via the Service API object.
It is specified as a Direct PolicyAttachment without defaults or overrides, applied to a Service that accesses a backend, where the BackendTLSPolicy resides in the same namespace as the Service to which it is applied.
All Gateway API Routes that point to a referenced Service should respect a configured
While there were existing ways provided for TLS to be configured for edge and passthrough termination, this new API object specifically addresses the configuration of TLS in order to convey HTTPS from the Gateway dataplane to the backend. This is referred to as "backend TLS termination" and enables the Gateway to know how to connect to a backend Pod that has its own certificate.
The specification of a
BackendTLSPolicy consists of:
targetRef- Defines the targeted API object of the policy. Only Service is allowed.
tls- Defines the configuration for TLS, including
wellKnownCACertsmay be specified, but not both.
hostname- Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend. The certificate served by the backend must match this SNI.
caCertRefs- Defines one or more references to objects that contain PEM-encoded TLS certificates, which are used to establish a TLS handshake between the Gateway and backend.
wellKnownCACerts- Specifies whether or not system CA certificates may be used in the TLS handshake between the Gateway and backend.
Using System Certificates
In this example, the
BackendTLSPolicy is configured to use system certificates to connect with a TLS-encrypted upstream connection where Pods backing the
dev Service are expected to serve a valid certificate for
Using Explicit CA Certificates
In this example, the
BackendTLSPolicy is configured to use certificates defined in the configuration map
auth-cert to connect with a TLS-encrypted upstream connection where Pods backing the
auth Service are expected to serve a valid certificate for
- kind: ConfigMapReference
The following illustrates a BackendTLSPolicy that configures TLS for a Service serving a backend:
For more information, refer to the documentation for TLS.
A key enhancement in Gateway API's latest release (v1.0) is the introduction of the
timeouts field within HTTPRoute Rules. This feature offers a dynamic way to manage timeouts for incoming HTTP requests, adding precision and reliability to your gateway setups.
With Timeouts, developers can fine-tune their Gateway API's behavior in two fundamental ways:
The request timeout is the duration within which the Gateway API implementation must send a response to a client's HTTP request. It allows flexibility in specifying when this timeout starts, either before or after the entire client request stream is received, making it implementation-specific. This timeout efficiently covers the entire request-response transaction, enhancing the responsiveness of your services.
Backend Request Timeout:
The backendRequest timeout is a game-changer for those dealing with backends. It sets a timeout for a single request sent from the Gateway to a backend service. This timeout spans from the initiation of the request to the reception of the full response from the backend. This feature is particularly helpful in scenarios where the Gateway needs to retry connections to a backend, ensuring smooth communication under various conditions.
request timeout encompasses the
backendRequest timeout. Hence, the value of
backendRequest should never exceed the value of the
The ability to configure these timeouts adds a new layer of reliability to your Kubernetes services. Whether it's ensuring client requests are processed within a specified timeframe or managing backend service communications, Gateway API's Timeouts offer the control and predictability you need.
To get started, you can define timeouts in your HTTPRoute Rules using the Timeouts field, specifying their type as Duration.
A zero-valued timeout (
0s) disables the timeout, while a valid non-zero-valued timeout should be at least 1ms.
Here's an example of setting request and backendRequest timeouts in an HTTPRoute:
- name: example-gateway
- name: timeout-svc
In this example, a
request timeout of 10 seconds is defined, ensuring that client requests are processed within that timeframe.
Additionally, a 2-second
backendRequest timeout is set for individual requests from the Gateway to a backend service called timeout-svc.
These new HTTPRoute Timeouts provide Kubernetes users with more control and flexibility in managing network communications, helping ensure a smoother and more predictable experience for both clients and backends. For additional details and examples, refer to the official timeouts API documentation.
Gateway Infrastructure Labels
While Gateway API providers a common API for different implementations, each implementation will have different resources created under-the-hood to apply users' intent. This could be configuring cloud load balancers, creating in-cluster Pods and Services, or more.
While the API has always provided an extension point --
GatewayClass -- to customize implementation specific things, there was no common core way to express common infrastructure customizations.
Gateway API v1.0 paves the way for this with a new
infrastructure field on the
Gateway object, allowing customization of the underlying infrastructure.
For now, this starts small with two critical fields: labels and annotations.
When these are set, any generated infrastructure will have the provided labels and annotations set on them.
For example, I may want to group all my resources for one application together:
In the future, we are looking into more common infrastructure configurations, such as resource sizing.
For more information, refer to the documentation for this feature.
Support for Websockets, HTTP/2 and more!
Not all implementations of Gateway API support automatic protocol selection. In some cases protocols are disabled without an explicit opt-in.
When a Route's backend references a Kubernetes Service, application developers can specify the protocol using
For example the following
store Kubernetes Service is indicating the port
8080 supports HTTP/2 Prior Knowledge.
- protocol: TCP
Currently, Gateway API has conformance testing for:
kubernetes.io/h2c- HTTP/2 Prior Knowledge
kubernetes.io/ws- WebSocket over HTTP
For more information, refer to the documentation for Backend Protocol Selection.
gwctl, our new Gateway API command line tool
gwctl is a command line tool that aims to be a
kubectl replacement for viewing Gateway API resources.
The initial release of
gwctl that comes bundled with Gateway v1.0 release includes helpful features for managing Gateway API Policies.
Gateway API Policies serve as powerful extension mechanisms for modifying the behavior of Gateway resources.
One challenge with using policies is that it may be hard to discover which policies are affecting which Gateway resources.
gwctl helps bridge this gap by answering questions like:
- Which policies are available for use in the Kubernetes cluster?
- Which policies are attached to a particular Gateway, HTTPRoute, etc?
- If policies are applied to multiple resources in the Gateway resource hierarchy, what is the effective policy that is affecting a particular resource? (For example, if an HTTP request timeout policy is applied to both an HTTPRoute and its parent Gateway, what is the effective timeout for the HTTPRoute?)
gwctl is still in the very early phases of development and hence may be a bit rough around the edges.
Follow the instructions in the repository to install and try out
Here are some examples of how
gwctl can be used:
# List all policies in the cluster. This will also give the resource they bind
gwctl get policies -A
# List all available policy types.
gwctl get policycrds
# Describe all HTTPRoutes in namespace ns2. (Output includes effective policies)
gwctl describe httproutes -n ns2
# Describe a single HTTPRoute in the default namespace. (Output includes
# effective policies)
gwctl describe httproutes my-httproute-1
# Describe all Gateways across all namespaces. (Output includes effective
gwctl describe gateways -A
# Describe a single GatewayClass. (Output includes effective policies)
gwctl describe gatewayclasses foo-com-external-gateway-class
These projects, and many more, continue to be improved in Gateway API. There are lots of opportunities to get involved and help define the future of Kubernetes routing APIs for both Ingress and Mesh.
If this is interesting to you, please join us in the community and help us build the future of Gateway API together!