diff --git a/examples/http-request-header-filter/README.md b/examples/http-request-header-filter/README.md index 87312de8af..0dc7e36a76 100644 --- a/examples/http-request-header-filter/README.md +++ b/examples/http-request-header-filter/README.md @@ -1,78 +1,3 @@ -# Example +# HTTP request headers example -In this example we will deploy NGINX Gateway Fabric and configure traffic routing for a simple echo server. -We will use HTTPRoute resources to route traffic to the echo server, using the `RequestHeaderModifier` filter to modify -headers to the request. - -## Running the Example - -## 1. Deploy NGINX Gateway Fabric - -1. Follow the [installation instructions](https://docs.nginx.com/nginx-gateway-fabric/installation/) to deploy NGINX Gateway Fabric. - -1. Save the public IP address of NGINX Gateway Fabric into a shell variable: - - ```text - GW_IP=XXX.YYY.ZZZ.III - ``` - -1. Save the port of NGINX Gateway Fabric: - - ```text - GW_PORT= - ``` - -## 2. Deploy the Headers Application - -1. Create the headers Deployment and Service: - - ```shell - kubectl apply -f headers.yaml - ``` - -1. Check that the Pod is running in the `default` Namespace: - - ```shell - kubectl -n default get pods - ``` - - ```text - NAME READY STATUS RESTARTS AGE - headers-6f4b79b975-2sb28 1/1 Running 0 12s - ``` - -## 3. Configure Routing - -1. Create the Gateway: - - ```shell - kubectl apply -f gateway.yaml - ``` - -1. Create the HTTPRoute resources: - - ```shell - kubectl apply -f echo-route.yaml - ``` - -## 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. -Notice our configured header values can be seen in the `requestHeaders` section below, and that the `User-Agent` 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" -``` - -```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 '*/*' -``` +This directory contains the YAML files used in the [Modify HTTP request and response headers](https://docs.nginx.com/nginx-gateway-fabric/how-to/traffic-management/request-response-headers/) guide. diff --git a/examples/http-response-header-filter/README.md b/examples/http-response-header-filter/README.md index 0bb6e89f94..ba59ed221f 100644 --- a/examples/http-response-header-filter/README.md +++ b/examples/http-response-header-filter/README.md @@ -1,3 +1,3 @@ -# HTTP Response Headers +# HTTP response headers example -This directory contains the YAML files used in the [HTTP Response Headers](https://docs.nginx.com/nginx-gateway-fabric/how-to/traffic-management/response-headers/) guide. +This directory contains the YAML files used in the [Modify HTTP request and response headers](https://docs.nginx.com/nginx-gateway-fabric/how-to/traffic-management/request-response-headers/) guide. diff --git a/site/content/how-to/data-plane-configuration.md b/site/content/how-to/data-plane-configuration.md index f2d6c14931..1db8f26632 100644 --- a/site/content/how-to/data-plane-configuration.md +++ b/site/content/how-to/data-plane-configuration.md @@ -160,7 +160,7 @@ as arguments and add `/bin/sh` as the command. The deployment manifest should lo ## Configure PROXY protocol and RewriteClientIP settings -When the request is passed through multiple proxies or load balancers, the client IP is set to the IP address of the server that last handled the request. To preserve the original client IP address, you can configure `RewriteClientIP` settings in the `NginxProxy` resource. `RewriteClientIP` has the fields: _mode_, _trustedAddresses_ and _setIPRecursively_. +When a request is passed through multiple proxies or load balancers, the client IP is set to the IP address of the server that last handled the request. To preserve the original client IP address, you can configure `RewriteClientIP` settings in the `NginxProxy` resource. `RewriteClientIP` has the fields: _mode_, _trustedAddresses_ and _setIPRecursively_. **Mode** determines how the original client IP is passed through multiple proxies and the way the load balancer is set to receive it. It can have two values: @@ -173,7 +173,7 @@ The choice of mode depends on how the load balancer fronting NGINX Gateway Fabri **SetIPRecursively** is a boolean field used to enable recursive search when selecting the client's address from a multi-value header. It is applicable in cases where we have a multi-value header containing client IPs to select from, i.e., when using `XForwardedFor` mode. -The following command creates an `NginxProxy` resource with `RewriteClientIP` settings that set the mode to XForwardedFor, enables recursive search for finding the client IP and sets a CIDR, IPAddress and Hostname in the list of trusted addresses to find the original client IP address. +The following command creates an `NginxProxy` resource with `RewriteClientIP` settings that set the mode to ProxyProtocol and sets a CIDR in the list of trusted addresses to find the original client IP address. ```yaml kubectl apply -f - <}}). +For the full configuration API, see the `NginxProxy spec` in the [API reference]({{< relref "reference/api.md" >}}). -{{< note >}} When sending curl requests to a server expecting proxy information, use the flag `--harproxy-protocol` to avoid broken header errors. {{< /note >}} +{{< note >}} When sending curl requests to a server expecting proxy information, use the flag `--haproxy-protocol` to avoid broken header errors. {{< /note >}} diff --git a/site/content/how-to/traffic-management/request-response-headers.md b/site/content/how-to/traffic-management/request-response-headers.md new file mode 100644 index 0000000000..b57f90ef22 --- /dev/null +++ b/site/content/how-to/traffic-management/request-response-headers.md @@ -0,0 +1,347 @@ +--- +title: "Modify HTTP request and response headers" +weight: 500 +toc: true +--- + +Learn how to modify the request and response headers of your application using NGINX Gateway Fabric. + +## Overview + +[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 during the request-response lifecycle. The [RequestHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/#http-request-header-modifier) is used to alter headers in a request sent by client and [ResponseHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/#http-response-header-modifier) is used to alter headers in a response to the client. + +This guide describes how to configure the headers application to modify the headers in the request. Another version of the headers application is then used to modify response headers when client requests are made. 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. + +--- + +## Before you begin + +- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric. +- 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 >}} + +--- + +## HTTP Header Modifiers examples + +We will configure a common gateway for the `RequestHeaderModifier` and `ResponseHeaderModifier` examples mentioned below. + +--- + +### Deploy the Gateway API resources for the Header application + +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). This Gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames. To deploy the Gateway: + +```yaml +kubectl apply -f - < 80/TCP 23s +``` + +--- + +### Configure the HTTPRoute with RequestHeaderModifier filter + +Create a HTTPRoute that exposes the header application outside the cluster using the listener created in the previous section. Use the following command: + +```yaml +kubectl apply -f - < 80/TCP 95s +``` + +### Configure the basic HTTPRoute + +Create a HTTPRoute that exposes the header application outside the cluster using the listener created in the previous section. You can do this with the following command: + +```yaml +kubectl apply -f - <}}) first. - -We'll begin by configuring an app with custom headers and a straightforward HTTPRoute. We'll then observe the server response in relation to header responses. Next, we'll delve into modifying some of those headers using an HTTPRoute with filters to modify *response* headers. Our aim will be to verify whether the server responds with the modified headers. - -## Before you begin - -- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric. -- 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 >}} - -### Deploy the Headers application - -Begin by deploying the example application `headers`. It is a simple application that adds response headers which we'll later tweak and customize. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.4.0/examples/http-response-header-filter/headers.yaml -``` - -This will create the headers Service and a Deployment with one Pod. Run the following command to verify the resources were created: - -```shell -kubectl get pods,svc -``` - -```text -NAME READY STATUS RESTARTS AGE -pod/headers-6f854c478-hd2jr 1/1 Running 0 95s - -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -service/headers ClusterIP 10.96.15.12 80/TCP 95s -``` - -### Deploy the Gateway API Resources for the Header Application - -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). This Gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames. To deploy the Gateway: - -```yaml -kubectl apply -f - <