Skip to content

Commit d5bd665

Browse files
howardjohnhowardjohn
authored
Add Gateway API recent features blog post (#43619)
* WIP: Add Gateway API recent features blog post * add two sections * New blog sections * Few tweaks * Add first paragraph * Fix image URL * Address Rob's comments * Remove duplicate line * Candace's comments * Candace's comments * Update 2023-11-1-Gateway-API-Future.md * Address comments * Push date
1 parent 58814a1 commit d5bd665

File tree

1 file changed

+259
-0
lines changed

1 file changed

+259
-0
lines changed

‎content/en/blog/_posts/2023-11-28-Gateway-API-Future.md

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
---
2+
layout: blog
3+
title: "New Experimental Features in Gateway API v1.0"
4+
date: 2023-11-28T10:00:00-08:00
5+
slug: gateway-api-ga
6+
---
7+
8+
***Authors:*** Candace Holman (Red Hat), Dave Protasowski (VMware), Gaurav K Ghildiyal (Google), John Howard (Google), Simone Rodigari (IBM)
9+
10+
Recently, the [Gateway API](https://gateway-api.sigs.k8s.io/) [announced its v1.0 GA release](/blog/2023/10/31/gateway-api-ga/), marking a huge milestone for the project.
11+
12+
Along with stabilizing some of the core functionality in the API, a number of exciting new *experimental* features have been added.
13+
14+
## Backend TLS Policy
15+
16+
`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.
17+
It is specified as a [Direct PolicyAttachment](https://gateway-api.sigs.k8s.io/geps/gep-713/#direct-policy-attachment) 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.
18+
All Gateway API Routes that point to a referenced Service should respect a configured `BackendTLSPolicy`.
19+
20+
While there were existing ways provided for [TLS to be configured for edge and passthrough termination](https://gateway-api.sigs.k8s.io/guides/tls/#tls-configuration), this new API object specifically addresses the configuration of TLS in order to convey HTTPS from the Gateway dataplane to the backend.
21+
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.
22+
23+
![Termination Types](https://gateway-api.sigs.k8s.io/geps/images/1897-TLStermtypes.png)
24+
25+
The specification of a `BackendTLSPolicy` consists of:
26+
- `targetRef` - Defines the targeted API object of the policy. Only Service is allowed.
27+
- `tls` - Defines the configuration for TLS, including `hostname`, `caCertRefs`, and `wellKnownCACerts`. Either `caCertRefs` or `wellKnownCACerts` may be specified, but not both.
28+
- `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.
29+
- `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.
30+
- `wellKnownCACerts` - Specifies whether or not system CA certificates may be used in the TLS handshake between the Gateway and backend.
31+
32+
### Examples
33+
34+
#### Using System Certificates
35+
36+
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 `dev.example.com`.
37+
38+
```yaml
39+
apiVersion: gateway.networking.k8s.io/v1alpha2
40+
kind: BackendTLSPolicy
41+
metadata:
42+
name: tls-upstream-dev
43+
spec:
44+
targetRef:
45+
kind: Service
46+
name: dev-service
47+
group: ""
48+
tls:
49+
wellKnownCACerts: "System"
50+
hostname: dev.example.com
51+
```
52+
53+
#### Using Explicit CA Certificates
54+
55+
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 `auth.example.com`.
56+
57+
```yaml
58+
apiVersion: gateway.networking.k8s.io/v1alpha2
59+
kind: BackendTLSPolicy
60+
metadata:
61+
name: tls-upstream-auth
62+
spec:
63+
targetRef:
64+
kind: Service
65+
name: auth-service
66+
group: ""
67+
tls:
68+
caCertRefs:
69+
- kind: ConfigMapReference
70+
name: auth-cert
71+
group: ""
72+
hostname: auth.example.com
73+
```
74+
75+
The following illustrates a BackendTLSPolicy that configures TLS for a Service serving a backend:
76+
77+
{{< mermaid >}}
78+
flowchart LR
79+
client(["client"])
80+
gateway["Gateway"]
81+
style gateway fill:#02f,color:#fff
82+
httproute["HTTP<BR>Route"]
83+
style httproute fill:#02f,color:#fff
84+
service["Service"]
85+
style service fill:#02f,color:#fff
86+
pod1["Pod"]
87+
style pod1 fill:#02f,color:#fff
88+
pod2["Pod"]
89+
style pod2 fill:#02f,color:#fff
90+
client -.->|HTTP <br> request| gateway
91+
gateway --> httproute
92+
httproute -.->|BackendTLSPolicy|service
93+
service --> pod1 & pod2
94+
{{</ mermaid >}}
95+
96+
For more information, refer to the [documentation for TLS](https://gateway-api.sigs.k8s.io/guides/tls).
97+
98+
## HTTPRoute Timeouts
99+
100+
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.
101+
102+
With Timeouts, developers can fine-tune their Gateway API's behavior in two fundamental ways:
103+
104+
1. **Request Timeout**:
105+
106+
The request timeout is the duration within which the Gateway API implementation must send a response to a client's HTTP request.
107+
It allows flexibility in specifying when this timeout starts, either before or after the entire client request stream is received, making it implementation-specific.
108+
This timeout efficiently covers the entire request-response transaction, enhancing the responsiveness of your services.
109+
110+
1. **Backend Request Timeout**:
111+
112+
The backendRequest timeout is a game-changer for those dealing with backends.
113+
It sets a timeout for a single request sent from the Gateway to a backend service.
114+
This timeout spans from the initiation of the request to the reception of the full response from the backend.
115+
This feature is particularly helpful in scenarios where the Gateway needs to retry connections to a backend, ensuring smooth communication under various conditions.
116+
117+
Notably, the `request` timeout encompasses the `backendRequest` timeout. Hence, the value of `backendRequest` should never exceed the value of the `request` timeout.
118+
119+
The ability to configure these timeouts adds a new layer of reliability to your Kubernetes services.
120+
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.
121+
122+
To get started, you can define timeouts in your HTTPRoute Rules using the Timeouts field, specifying their type as Duration.
123+
A zero-valued timeout (`0s`) disables the timeout, while a valid non-zero-valued timeout should be at least 1ms.
124+
125+
Here's an example of setting request and backendRequest timeouts in an HTTPRoute:
126+
127+
```yaml
128+
apiVersion: gateway.networking.k8s.io/v1
129+
kind: HTTPRoute
130+
metadata:
131+
name: timeout-example
132+
spec:
133+
parentRefs:
134+
- name: example-gateway
135+
rules:
136+
- matches:
137+
- path:
138+
type: PathPrefix
139+
value: /timeout
140+
timeouts:
141+
request: 10s
142+
backendRequest: 2s
143+
backendRefs:
144+
- name: timeout-svc
145+
port: 8080
146+
```
147+
148+
In this example, a `request` timeout of 10 seconds is defined, ensuring that client requests are processed within that timeframe.
149+
Additionally, a 2-second `backendRequest` timeout is set for individual requests from the Gateway to a backend service called timeout-svc.
150+
151+
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.
152+
For additional details and examples, refer to the [official timeouts API documentation](https://gateway-api.sigs.k8s.io/api-types/httproute/#timeouts-optional).
153+
154+
## Gateway Infrastructure Labels
155+
156+
While Gateway API providers a common API for different implementations, each implementation will have different resources created under-the-hood to apply users' intent.
157+
This could be configuring cloud load balancers, creating in-cluster Pods and Services, or more.
158+
159+
While the API has always provided an extension point -- `parametersRef` in `GatewayClass` -- to customize implementation specific things, there was no common core way to express common infrastructure customizations.
160+
161+
Gateway API v1.0 paves the way for this with a new `infrastructure` field on the `Gateway` object, allowing customization of the underlying infrastructure.
162+
For now, this starts small with two critical fields: labels and annotations.
163+
When these are set, any generated infrastructure will have the provided labels and annotations set on them.
164+
165+
For example, I may want to group all my resources for one application together:
166+
167+
```yaml
168+
apiVersion: gateway.networking.k8s.io/v1
169+
kind: Gateway
170+
metadata:
171+
name: hello-world
172+
spec:
173+
infrastructure:
174+
labels:
175+
app.kubernetes.io/name: hello-world
176+
```
177+
178+
In the future, we are looking into more common infrastructure configurations, such as resource sizing.
179+
180+
For more information, refer to the [documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GatewayInfrastructure) for this feature.
181+
182+
## Support for Websockets, HTTP/2 and more!
183+
184+
Not all implementations of Gateway API support automatic protocol selection.
185+
In some cases protocols are disabled without an explicit opt-in.
186+
187+
When a Route's backend references a Kubernetes Service, application developers can specify the protocol using `ServicePort` [`appProtocol`][appProtocol] field.
188+
189+
For example the following `store` Kubernetes Service is indicating the port `8080` supports HTTP/2 Prior Knowledge.
190+
191+
```yaml
192+
apiVersion: v1
193+
kind: Service
194+
metadata:
195+
name: store
196+
spec:
197+
selector:
198+
app: store
199+
ports:
200+
- protocol: TCP
201+
appProtocol: kubernetes.io/h2c
202+
port: 8080
203+
targetPort: 8080
204+
```
205+
206+
Currently, Gateway API has conformance testing for:
207+
208+
- `kubernetes.io/h2c` - HTTP/2 Prior Knowledge
209+
- `kubernetes.io/ws` - WebSocket over HTTP
210+
211+
For more information, refer to the documentation for [Backend Protocol Selection](https://gateway-api.sigs.k8s.io/guides/backend-protocol).
212+
213+
[appProtocol]: https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol
214+
215+
## `gwctl`, our new Gateway API command line tool
216+
217+
`gwctl` is a command line tool that aims to be a `kubectl` replacement for viewing Gateway API resources.
218+
219+
The initial release of `gwctl` that comes bundled with Gateway v1.0 release includes helpful features for managing Gateway API Policies.
220+
Gateway API Policies serve as powerful extension mechanisms for modifying the behavior of Gateway resources.
221+
One challenge with using policies is that it may be hard to discover which policies are affecting which Gateway resources.
222+
`gwctl` helps bridge this gap by answering questions like:
223+
224+
* Which policies are available for use in the Kubernetes cluster?
225+
* Which policies are attached to a particular Gateway, HTTPRoute, etc?
226+
* 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?)
227+
228+
`gwctl` is still in the very early phases of development and hence may be a bit rough around the edges.
229+
Follow the instructions in [the repository](https://github.com/kubernetes-sigs/gateway-api/tree/main/gwctl#try-it-out) to install and try out `gwctl`.
230+
231+
### Examples
232+
233+
Here are some examples of how `gwctl` can be used:
234+
235+
```bash
236+
# List all policies in the cluster. This will also give the resource they bind
237+
# to.
238+
gwctl get policies -A
239+
# List all available policy types.
240+
gwctl get policycrds
241+
# Describe all HTTPRoutes in namespace ns2. (Output includes effective policies)
242+
gwctl describe httproutes -n ns2
243+
# Describe a single HTTPRoute in the default namespace. (Output includes
244+
# effective policies)
245+
gwctl describe httproutes my-httproute-1
246+
# Describe all Gateways across all namespaces. (Output includes effective
247+
# policies)
248+
gwctl describe gateways -A
249+
# Describe a single GatewayClass. (Output includes effective policies)
250+
gwctl describe gatewayclasses foo-com-external-gateway-class
251+
```
252+
253+
## Get involved
254+
255+
These projects, and many more, continue to be improved in Gateway API.
256+
There are lots of opportunities to get involved and help define the future of Kubernetes routing APIs for both Ingress and Mesh.
257+
258+
If this is interesting to you, please [join us in the community](https://gateway-api.sigs.k8s.io/contributing/) and help us build the future of Gateway API together!
259+

0 commit comments

Comments
 (0)