Early request header modification

Early request header modification allows you to add, set, or remove HTTP request headers at the listener level, before route selection and other request processing occurs.

This capability is especially useful for security and sanitization use cases, where you want to ensure that sensitive headers cannot be faked by downstream clients and are only set by trusted components such as external authentication services.

Early request header modification is configured on a ListenerPolicy using the earlyRequestHeaderModifier field. This policy is attached directly to a Gateway and applies header mutations before route selection.

The configuration uses the standard Gateway API HTTPHeaderFilter format and supports the following operations:

  • add
  • set
  • remove

Before you begin

  1. Follow the Get started guide to install kgateway.

  2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. Get the external address of the gateway and save it in an environment variable. 

    export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS  
    kubectl port-forward deployment/http -n kgateway-system 8080:8080

Remove a reserved header

Remove a header that is reserved for use by another service, such as an external authentication service.

  1. Send a test request to the sample httpbin app with a reserved header, such as x-user-id.

    curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080" -H "x-user-id: reserved-user"
    curl -i localhost:8080/headers -H "host: www.example.com" -H "x-user-id: reserved-user"

    Example output: Note that the X-User-Id header is present in the request.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

    {
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "www.example.com"
    ],
    "User-Agent": [
      "curl/8.7.1"
    ],
    "X-Envoy-Expected-Rq-Timeout-Ms": [
      "15000"
    ],
    "X-Envoy-External-Address": [
      "127.0.0.1"
    ],
    "X-Forwarded-For": [
      "10.244.0.7"
    ],
    "X-Forwarded-Proto": [
      "http"
    ],
    "X-Request-Id": [
      "d2076b1d-2e3e-49fb-a24f-703dbcd80665"
    ],
    "X-User-Id": [
      "reserved-user"
    ]
  }
}

  2. Create a ListenerPolicy to remove the x-user-id header.

    kubectl apply -f- <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: ListenerPolicy
metadata:
  name: remove-header
  namespace: kgateway-system
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: http
  default:
    httpSettings:
      earlyRequestHeaderModifier:
        remove:
          - x-user-id
EOF

    Review the following table to understand this configuration. For more information about the available fields, see the API reference.

    Setting Description
    targetRefs References the Gateway resources this policy applies to.
    earlyRequestHeaderModifier Header mutations applied before route selection.

  3. Repeat the test request to the sample httpbin app. The x-user-id header is no longer present in the response.

    curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080" -H "x-user-id: reserved-user"
    curl -i localhost:8080/headers -H "host: www.example.com" -H "x-user-id: reserved-user"

    Example output: Note that the x-user-id header is now removed.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

    {
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "www.example.com"
    ],
    "User-Agent": [
      "curl/8.7.1"
    ],
    "X-Envoy-Expected-Rq-Timeout-Ms": [
      "15000"
    ],
    "X-Envoy-External-Address": [
      "127.0.0.1"
    ],
    "X-Forwarded-For": [
      "10.244.0.7"
    ],
    "X-Forwarded-Proto": [
      "http"
    ],
    "X-Request-Id": [
      "f4dcc321-d682-4874-b02f-b700854e2f6b"
    ]
  }
}

Cleanup

You can remove the resources that you created in this guide. 
kubectl delete listenerpolicy remove-header -n kgateway-system
Response headers