Skip to content

Commit e78777a

Browse files
robscottrobscott
committed
Adding missing guides for HTTPRoute features
1 parent ff6fb68 commit e78777a

File tree

6 files changed

+364
-8
lines changed

6 files changed

+364
-8
lines changed

‎nav.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ nav:
3232
- HTTP header modifier: guides/http-header-modifier.md
3333
- HTTP traffic splitting: guides/traffic-splitting.md
3434
- HTTP request mirroring: guides/http-request-mirroring.md
35+
- HTTP query parameter matching: guides/http-query-param-matching.md
36+
- HTTP method matching: guides/http-method-matching.md
37+
- HTTP timeouts: guides/http-timeouts.md
38+
- HTTP CORS: guides/http-cors.md
3539
- Cross-Namespace routing: guides/multiple-ns.md
3640
- TLS: guides/tls.md
3741
- TCP routing: guides/tcp.md

‎site-src/guides/http-cors.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Cross-Origin Resource Sharing (CORS)
2+
3+
???+ info "Experimental Channel Feature: HTTPRouteCORS"
4+
This feature is in the `experimental` channel. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md).
5+
6+
The [HTTPRoute resource](../api-types/httproute.md) can be used to configure
7+
Cross-Origin Resource Sharing (CORS). CORS is a security feature that allows
8+
or denies web applications running at one domain to make requests for resources
9+
from a different domain.
10+
11+
The `CORS` filter in an `HTTPRouteRule` can be used to specify the CORS policy.
12+
13+
## Allowing requests from a specific origin
14+
15+
The following `HTTPRoute` allows requests from `https://app.example`:
16+
17+
```yaml
18+
apiVersion: gateway.networking.k8s.io/v1
19+
kind: HTTPRoute
20+
metadata:
21+
name: cors-allow-credentials
22+
namespace: gateway-conformance-infra
23+
spec:
24+
parentRefs:
25+
- name: same-namespace
26+
rules:
27+
- matches:
28+
- path:
29+
type: PathPrefix
30+
value: /cors-behavior-creds-false
31+
backendRefs:
32+
- name: infra-backend-v1
33+
port: 8080
34+
filters:
35+
- cors:
36+
allowOrigins:
37+
- https://app.example
38+
allowCredentials: false
39+
type: CORS
40+
```
41+
42+
## Allowing credentials
43+
44+
The `allowCredentials` field specifies whether the browser should include
45+
credentials (such as cookies and HTTP authentication) in the CORS request.
46+
47+
The following rule allows requests from `https://app.example` with
48+
credentials:
49+
50+
```yaml
51+
- matches:
52+
- path:
53+
type: PathPrefix
54+
value: /cors-behavior-creds-true
55+
backendRefs:
56+
- name: infra-backend-v1
57+
port: 8080
58+
filters:
59+
- cors:
60+
allowOrigins:
61+
- https://app.example
62+
allowCredentials: true
63+
type: CORS
64+
```
65+
66+
## Other CORS options
67+
68+
The `CORS` filter also allows you to specify other CORS options, such as:
69+
70+
- `allowMethods`: The HTTP methods that are allowed for CORS requests.
71+
- `allowHeaders`: The HTTP headers that are allowed for CORS requests.
72+
- `exposeHeaders`: The HTTP headers that are exposed to the client.
73+
- `maxAge`: The maximum time that the browser should cache the preflight
74+
response.

‎site-src/guides/http-method-matching.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# HTTP method matching
2+
3+
???+ info "Extended Support Feature: HTTPRouteMethodMatching"
4+
This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md).
5+
6+
The [HTTPRoute resource](../api-types/httproute.md) can be used to match
7+
requests based on the HTTP method. This guide shows how to use this
8+
functionality.
9+
10+
## Matching requests based on the HTTP method
11+
12+
The following `HTTPRoute` splits traffic between two backends based on the
13+
HTTP method of the request:
14+
15+
```yaml
16+
apiVersion: gateway.networking.k8s.io/v1
17+
kind: HTTPRoute
18+
metadata:
19+
name: method-matching
20+
namespace: gateway-conformance-infra
21+
spec:
22+
parentRefs:
23+
- name: same-namespace
24+
rules:
25+
- matches:
26+
- method: POST
27+
backendRefs:
28+
- name: infra-backend-v1
29+
port: 8080
30+
- matches:
31+
- method: GET
32+
backendRefs:
33+
- name: infra-backend-v2
34+
port: 8080
35+
```
36+
37+
- A `POST` request to `/` will be routed to `infra-backend-v1`.
38+
- A `GET` request to `/` will be routed to `infra-backend-v2`.
39+
40+
## Combining with other match types
41+
42+
Method matching can be combined with other match types like path and header
43+
matching. The following rules demonstrate this:
44+
45+
```yaml
46+
# Combinations with core match types.
47+
- matches:
48+
- path:
49+
type: PathPrefix
50+
value: /path1
51+
method: GET
52+
backendRefs:
53+
- name: infra-backend-v1
54+
port: 8080
55+
- matches:
56+
- headers:
57+
- name: version
58+
value: one
59+
method: PUT
60+
backendRefs:
61+
- name: infra-backend-v2
62+
port: 8080
63+
- matches:
64+
- path:
65+
type: PathPrefix
66+
value: /path2
67+
headers:
68+
- name: version
69+
value: two
70+
method: POST
71+
backendRefs:
72+
- name: infra-backend-v3
73+
port: 8080
74+
```
75+
76+
## ORing matches
77+
78+
If a rule has multiple `matches`, a request will be routed if it satisfies any
79+
of them. The following rule routes traffic to `infra-backend-v1` if:
80+
81+
- The request is a `PATCH` to `/path3`.
82+
- OR the request is a `DELETE` to `/path4` with the `version: three` header.
83+
84+
```yaml
85+
# Match of the form (cond1 AND cond2) OR (cond3 AND cond4 AND cond5)
86+
- matches:
87+
- path:
88+
type: PathPrefix
89+
value: /path3
90+
method: PATCH
91+
- path:
92+
type: PathPrefix
93+
value: /path4
94+
headers:
95+
- name: version
96+
value: three
97+
method: DELETE
98+
backendRefs:
99+
- name: infra-backend-v1
100+
port: 8080
101+
```

‎site-src/guides/http-query-param-matching.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# HTTP query parameter matching
2+
3+
???+ info "Extended Support Feature: HTTPRouteQueryParamMatching"
4+
This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md).
5+
6+
The [HTTPRoute resource](../api-types/httproute.md) can be used to match
7+
requests based on query parameters. This guide shows how to use this
8+
functionality.
9+
10+
## Matching requests based on a single query parameter
11+
12+
The following `HTTPRoute` splits traffic between two backends based on the
13+
value of the `animal` query parameter:
14+
15+
```yaml
16+
apiVersion: gateway.networking.k.io/v1
17+
kind: HTTPRoute
18+
metadata:
19+
name: query-param-matching
20+
namespace: gateway-conformance-infra
21+
spec:
22+
parentRefs:
23+
- name: same-namespace
24+
rules:
25+
- matches:
26+
- queryParams:
27+
- name: animal
28+
value: whale
29+
backendRefs:
30+
- name: infra-backend-v1
31+
port: 8080
32+
- matches:
33+
- queryParams:
34+
- name: animal
35+
value: dolphin
36+
backendRefs:
37+
- name: infra-backend-v2
38+
port: 8080
39+
```
40+
41+
- A request to `/` with the query parameter `animal=whale` will be routed to `infra-backend-v1`.
42+
- A request to `/` with the query parameter `animal=dolphin` will be routed to `infra-backend-v2`.
43+
44+
## Matching requests based on multiple query parameters
45+
46+
A rule can also match on multiple query parameters. The following rule routes
47+
traffic to `infra-backend-v3` if the query parameters `animal=dolphin` AND
48+
`color=blue` are present:
49+
50+
```yaml
51+
- matches:
52+
- queryParams:
53+
- name: animal
54+
value: dolphin
55+
- name: color
56+
value: blue
57+
backendRefs:
58+
- name: infra-backend-v3
59+
port: 8080
60+
```
61+
62+
## ORing matches
63+
64+
If a rule has multiple `matches`, a request will be routed if it satisfies any
65+
of them. The following rule routes traffic to `infra-backend-v3` if:
66+
67+
- The query parameters `animal=dolphin` AND `color=blue` are present.
68+
- OR the query parameter `ANIMAL=Whale` is present.
69+
70+
```yaml
71+
- matches:
72+
- queryParams:
73+
- name: animal
74+
value: dolphin
75+
- name: color
76+
value: blue
77+
- queryParams:
78+
- name: ANIMAL
79+
value: Whale
80+
backendRefs:
81+
- name: infra-backend-v3
82+
port: 8080
83+
```
84+
85+
## Combining with other match types
86+
87+
Query parameter matching can be combined with other match types like path and
88+
header matching. The following rules demonstrate this:
89+
90+
```yaml
91+
- matches:
92+
- path:
93+
type: PathPrefix
94+
value: /path1
95+
queryParams:
96+
- name: animal
97+
value: whale
98+
backendRefs:
99+
- name: infra-backend-v1
100+
port: 8080
101+
- matches:
102+
- headers:
103+
- name: version
104+
value: one
105+
queryParams:
106+
- name: animal
107+
value: whale
108+
backendRefs:
109+
- name: infra-backend-v2
110+
port: 8080
111+
- matches:
112+
- path:
113+
type: PathPrefix
114+
value: /path2
115+
headers:
116+
- name: version
117+
value: two
118+
queryParams:
119+
- name: animal
120+
value: whale
121+
backendRefs:
122+
- name: infra-backend-v3
123+
port: 8080
124+
```

‎site-src/guides/http-request-mirroring.md‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
11
# HTTP request mirroring
22

3-
??? example "Extended Support Feature"
3+
???+ info "Extended Support Feature: HTTPRouteRequestMirror"
4+
This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md).
45

5-
As of v1.0.0, the Request Mirroring feature is an Extended feature, and
6-
requires implementations to support the `HTTPRouteRequestMirror` feature.
7-
8-
The [HTTPRoute resource](../api-types/httproute.md) allows you to mirror HTTP
9-
requests to another backend using
10-
[filters](../api-types/httproute.md#filters-optional). This guide shows how to use
11-
this feature.
6+
The [HTTPRoute resource](../api-types/httproute.md) can be used to mirror
7+
requests to multiple backends. This is useful for testing new services with
8+
production traffic.
129

1310
Mirrored requests will must only be sent to one single destination endpoint
1411
within this backendRef, and responses from this backend MUST be ignored by

‎site-src/guides/http-timeouts.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# HTTP timeouts
2+
3+
???+ info "Extended Support Feature: HTTPRouteRequestTimeout"
4+
This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md).
5+
6+
The [HTTPRoute resource](../api-types/httproute.md) can be used to configure
7+
timeouts for HTTP requests. This is useful for preventing long-running requests
8+
from consuming resources and for providing a better user experience.
9+
10+
The `timeouts` field in an `HTTPRouteRule` can be used to specify a request
11+
timeout.
12+
13+
## Setting a request timeout
14+
15+
The following `HTTPRoute` sets a request timeout of 500 milliseconds for all
16+
requests with a path prefix of `/request-timeout`:
17+
18+
```yaml
19+
apiVersion: gateway.networking.k8s.io/v1
20+
kind: HTTPRoute
21+
metadata:
22+
name: request-timeout
23+
namespace: gateway-conformance-infra
24+
spec:
25+
parentRefs:
26+
- name: same-namespace
27+
rules:
28+
- matches:
29+
- path:
30+
type: PathPrefix
31+
value: /request-timeout
32+
backendRefs:
33+
- name: infra-backend-v1
34+
port: 8080
35+
timeouts:
36+
request: 500ms
37+
```
38+
39+
If a request to this path takes longer than 500 milliseconds, the gateway will
40+
return a timeout error.
41+
42+
## Disabling the request timeout
43+
44+
To disable the request timeout, set the `request` field to `"0s"`:
45+
46+
```yaml
47+
- matches:
48+
- path:
49+
type: PathPrefix
50+
value: /disable-request-timeout
51+
backendRefs:
52+
- name: infra-backend-v1
53+
port: 8080
54+
timeouts:
55+
request: "0s"
56+
```

0 commit comments

Comments
 (0)