Skip to content

Commit c37121a

Browse files
salonichf5salonichf5
committed
add docs for http filters
1 parent 801ac2d commit c37121a

File tree

3 files changed

+182
-2
lines changed

3 files changed

+182
-2
lines changed

‎examples/http-header-filter/README.md

+12-2
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,14 @@ headers to the request.
5757

5858
## 4. Test the Application
5959

60-
To access the application, we will use `curl` to send requests to the `headers` Service, including sending headers with
61-
our request.
60+
To access the application, we will use `curl` to send requests to the `headers` Service, including sending headers with our request.
6261
Notice our configured header values can be seen in the `requestHeaders` section below, and that the `User-Agent` header
6362
is absent.
6463

64+
65+
1. We will send the curl request to modify request headers. Notice our configured request header values can be seen in the `requestHeaders` section below, and that the `Accept` header
66+
is absent.
67+
6568
```shell
6669
curl -s --resolve echo.example.com:$GW_PORT:$GW_IP http://echo.example.com:$GW_PORT/headers -H "My-Cool-Header:my-client-value" -H "My-Overwrite-Header:dont-see-this"
6770
```
@@ -76,3 +79,10 @@ Headers:
7679
header 'Connection' is 'close'
7780
header 'Accept' is '*/*'
7881
```
82+
83+
84+
1. We will send the curl request to modify response headers. Notice our configured response header values can be seen in the `responseHeaders` section below, and that the `User-Agent` header
85+
is absent.
86+
87+
88+
// TODO

‎examples/http-header-filter/echo-route.yaml

+12
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,18 @@ spec:
2626
value: this-is-an-appended-value
2727
remove:
2828
- User-Agent
29+
- type: ResponseHeaderModifier
30+
responseHeaderModifier:
31+
set:
32+
- name: My-Overwrite-Header-Response
33+
value: this-is-the-only-value-response
34+
add:
35+
- name: Accept-Encoding-Response
36+
value: compress-response
37+
- name: My-cool-header-Response
38+
value: this-is-an-appended-value-response
39+
remove:
40+
- Accept
2941
backendRefs:
3042
- name: headers
3143
port: 80

‎site/content/how-to/traffic-management/request-and-response-headers.md

+158
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: "HTTP Request and Response Headers"
3+
description: "Learn how to modify request and response headers for your HTTP Route using NGINX Gateway Fabric."
4+
weight: 700
5+
toc: true
6+
docs: ""
7+
---
8+
9+
[HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) filters can modify the headers during the request-response lifecycle. [HTTP Header Modifiers](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/?h=request#http-header-modifiers) can be used to add, modify or remove headers in incoming requests. We have two types of [filter](https://gateway-api.sigs.k8s.io/api-types/httproute/#filters-optional) that can be used to instruct the Gateway for desired behaviour.
10+
11+
1. [RequestHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/?h=request#http-request-header-modifier) to alter headers in request before forwarding the request upstream.
12+
1. [ResponseHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/?h=request#http-response-header-modifier) to alter headers in response before responding to the downstream.
13+
14+
15+
In this guide we will modify the headers of HTTP request and HTTP responses from clients. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< relref "/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first.
16+
17+
18+
## Prerequisites
19+
20+
- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric.
21+
- [Expose NGINX Gateway Fabric]({{< relref "installation/expose-nginx-gateway-fabric.md" >}}) and save the public IP
22+
address and port of NGINX Gateway Fabric into shell variables:
23+
24+
```text
25+
GW_IP=XXX.YYY.ZZZ.III
26+
GW_PORT=<port number>
27+
```
28+
29+
{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}}
30+
31+
## Echo Application
32+
33+
### Deploy the Headers Application
34+
35+
Begin by deploying the `headers` application:
36+
37+
```shell
38+
kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.2.0/examples/http-header-filter/headers.yaml
39+
```
40+
41+
### Deploy the Gateway API Resources for the Headers Applications
42+
43+
The [gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [cluster operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the gateway:
44+
45+
```yaml
46+
kubectl apply -f - <<EOF
47+
apiVersion: gateway.networking.k8s.io/v1
48+
kind: Gateway
49+
metadata:
50+
name: echo
51+
spec:
52+
gatewayClassName: nginx
53+
listeners:
54+
- name: http
55+
port: 80
56+
protocol: HTTP
57+
EOF
58+
```
59+
60+
This gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames.
61+
62+
The [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) is typically deployed by the [application developer](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the `headers` HTTPRoute:
63+
64+
65+
```yaml
66+
kubectl apply -f - <<EOF
67+
apiVersion: gateway.networking.k8s.io/v1
68+
kind: HTTPRoute
69+
metadata:
70+
name: headers
71+
spec:
72+
parentRefs:
73+
- name: gateway
74+
sectionName: http
75+
hostnames:
76+
- "echo.example.com"
77+
rules:
78+
- matches:
79+
- path:
80+
type: PathPrefix
81+
value: /headers
82+
filters:
83+
- type: RequestHeaderModifier
84+
requestHeaderModifier:
85+
set:
86+
- name: My-Overwrite-Header
87+
value: this-is-the-only-value
88+
add:
89+
- name: Accept-Encoding
90+
value: compress
91+
- name: My-cool-header
92+
value: this-is-an-appended-value
93+
remove:
94+
- User-Agent
95+
- type: ResponseHeaderModifier
96+
responseHeaderModifier:
97+
set:
98+
- name: My-Overwrite-Header-Response
99+
value: this-is-the-only-value-response
100+
add:
101+
- name: Accept-Encoding-Response
102+
value: compress-response
103+
- name: My-cool-header-Response
104+
value: this-is-an-appended-value-response
105+
remove:
106+
- Accept
107+
backendRefs:
108+
- name: headers
109+
port: 80
110+
EOF
111+
```
112+
113+
This HTTPRoute has a few important properties:
114+
115+
- The `parentRefs` references the gateway resource that we created, and specifically defines the `http` listener to attach to, via the `sectionName` field.
116+
- `echo.example.com` is the hostname that is matched for all requests to the backends defined in this HTTPRoute.
117+
- The `match` rule defines that all requests with the path prefix `/headers` are sent to the `headers` Service.
118+
- There are two filters defined for the path prefix `/headers`
119+
120+
1. `RequestHeaderModifier` filter sets the value of header `My-Overwrite-Header` to `this-is-the-only-value`, adds headers `Accept-Encoding` and `My-cool-header` and removes `User-Agent`.
121+
1. `ResponseHeaderModifier` filter sets the value of header `My-Overwrite-Header-Response` to `this-is-the-only-value-Response`, adds headers `Accept-Encoding-Response` and `My-cool-header-Response` and removes `Accept`.
122+
123+
124+
{{< note >}}If the request does not have the header configured by the filter, then that header will be added to the request. If the request already has the header configured by the filter, then the value of the header in the filter will be appended to the value of the header in the request.{{< /note >}}
125+
126+
### Send Traffic to Headers
127+
128+
To access the application, we will use `curl` to send requests to the `headers` Service, including sending headers with our request.
129+
130+
{{< note >}}If you have a DNS record allocated for `echo.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}}
131+
132+
133+
1. Send traffic to headers to modify request headers.
134+
135+
```shell
136+
curl -s --resolve echo.example.com:$GW_PORT:$GW_IP http://echo.example.com:$GW_PORT/headers -H "My-Cool-Header:my-client-value" -H "My-Overwrite-Header:dont-see-this"
137+
```
138+
139+
```text
140+
Headers:
141+
header 'Accept-Encoding' is 'compress'
142+
header 'My-cool-header' is 'my-client-value, this-is-an-appended-value'
143+
header 'My-Overwrite-Header' is 'this-is-the-only-value'
144+
header 'Host' is 'echo.example.com:$GW_PORT'
145+
header 'X-Forwarded-For' is '$GW_IP'
146+
header 'Connection' is 'close'
147+
header 'Accept' is '*/*'
148+
```
149+
150+
```shell
151+
curl -v --resolve echo.example.com:$GW_PORT:$GW_IP http://echo.example.com:$GW_PORT/headers
152+
```
153+
154+
155+
1. Send traffic to headers to modify response headers.
156+
157+
158+
// TODO

0 commit comments

Comments
 (0)