From c37121af102add732a5649beb25d90dd16f3359b Mon Sep 17 00:00:00 2001 From: Saloni Date: Wed, 1 May 2024 09:30:14 -0600 Subject: [PATCH] add docs for http filters --- examples/http-header-filter/README.md | 14 +- examples/http-header-filter/echo-route.yaml | 12 ++ .../request-and-response-headers.md | 158 ++++++++++++++++++ 3 files changed, 182 insertions(+), 2 deletions(-) create mode 100644 site/content/how-to/traffic-management/request-and-response-headers.md diff --git a/examples/http-header-filter/README.md b/examples/http-header-filter/README.md index fcb8ea1e6f..cee0e3af04 100644 --- a/examples/http-header-filter/README.md +++ b/examples/http-header-filter/README.md @@ -57,11 +57,14 @@ headers to the request. ## 4. Test the Application -To access the application, we will use `curl` to send requests to the `headers` Service, including sending headers with -our request. +To access the application, we will use `curl` to send requests to the `headers` Service, including sending headers with our request. Notice our configured header values can be seen in the `requestHeaders` section below, and that the `User-Agent` header is absent. + +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 +is absent. + ```shell 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" ``` @@ -76,3 +79,10 @@ Headers: header 'Connection' is 'close' header 'Accept' is '*/*' ``` + + +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 +is absent. + + +// TODO diff --git a/examples/http-header-filter/echo-route.yaml b/examples/http-header-filter/echo-route.yaml index 43ed5d52db..a339e800c0 100644 --- a/examples/http-header-filter/echo-route.yaml +++ b/examples/http-header-filter/echo-route.yaml @@ -26,6 +26,18 @@ spec: value: this-is-an-appended-value remove: - User-Agent + - type: ResponseHeaderModifier + responseHeaderModifier: + set: + - name: My-Overwrite-Header-Response + value: this-is-the-only-value-response + add: + - name: Accept-Encoding-Response + value: compress-response + - name: My-cool-header-Response + value: this-is-an-appended-value-response + remove: + - Accept backendRefs: - name: headers port: 80 diff --git a/site/content/how-to/traffic-management/request-and-response-headers.md b/site/content/how-to/traffic-management/request-and-response-headers.md new file mode 100644 index 0000000000..f333537bbe --- /dev/null +++ b/site/content/how-to/traffic-management/request-and-response-headers.md @@ -0,0 +1,158 @@ +--- +title: "HTTP Request and Response Headers" +description: "Learn how to modify request and response headers for your HTTP Route using NGINX Gateway Fabric." +weight: 700 +toc: true +docs: "" +--- + +[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. + +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. +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. + + +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. + + +## Prerequisites + +- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric. +- [Expose NGINX Gateway Fabric]({{< relref "installation/expose-nginx-gateway-fabric.md" >}}) and save the public IP + address and port of NGINX Gateway Fabric into shell variables: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` + +{{< 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 >}} + +## Echo Application + +### Deploy the Headers Application + +Begin by deploying the `headers` application: + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.2.0/examples/http-header-filter/headers.yaml +``` + +### Deploy the Gateway API Resources for the Headers Applications + +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: + +```yaml +kubectl apply -f - <}}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 >}} + +### Send Traffic to Headers + +To access the application, we will use `curl` to send requests to the `headers` Service, including sending headers with our request. + +{{< 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 >}} + + +1. Send traffic to headers to modify request headers. + +```shell +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" +``` + +```text +Headers: + header 'Accept-Encoding' is 'compress' + header 'My-cool-header' is 'my-client-value, this-is-an-appended-value' + header 'My-Overwrite-Header' is 'this-is-the-only-value' + header 'Host' is 'echo.example.com:$GW_PORT' + header 'X-Forwarded-For' is '$GW_IP' + header 'Connection' is 'close' + header 'Accept' is '*/*' +``` + +```shell +curl -v --resolve echo.example.com:$GW_PORT:$GW_IP http://echo.example.com:$GW_PORT/headers +``` + + +1. Send traffic to headers to modify response headers. + + +// TODO