Docs Standalone Kubernetes Tutorials Standalone Kubernetes Models Blog Enterprise Community Get Started GitHub

Request headers

Use the RequestHeaderModifier filter to add, append, overwrite, or remove request headers for a specific route.

For more information, see the HTTPHeaderFilter specification.

Before you begin

  1. Set up an agentgateway proxy.
  2. Install the httpbin sample app.

Add and append request headers

Add headers to incoming requests before they are forwarded to an upstream service. If the request already has the header set, the value of the header in the RequestHeaderModifier filter is appended to the value of the header in the request.

  1. Set up a header modifier that adds a my-header: hello request header for a Gateway API-native HTTPRoute.

    kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-headers
  namespace: httpbin
spec:
  parentRefs:
  - name: agentgateway-proxy
    namespace: agentgateway-system
  hostnames:
    - headers.example
  rules:
    - filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add: 
            - name: my-header
              value: hello
      backendRefs:
        - name: httpbin
          port: 8000
EOF
    SettingDescription
    spec.parentRefsThe name and namespace of the gateway that serves this HTTPRoute. In this example, you use the agentgateway-proxy Gateway that was created as part of the get started guide.
    spec.rules.filters.typeThe type of filter that you want to apply to incoming requests. In this example, the RequestHeaderModifier filter is used.
    spec.rules.filters.requestHeaderModifier.addThe name and value of the request header that you want to add.
    spec.rules.backendRefsThe backend destination you want to forward traffic to. In this example, all traffic is forwarded to the httpbin app that you set up as part of the get started guide.

  2. Send a request to the httpbin app on the headers.example domain and verify that you get back a 200 HTTP response code and that you see the my-header request header.

    curl -vi http://${INGRESS_GW_ADDRESS}:8080/headers -H "host: headers.example:8080"
    curl -vi localhost:8080/headers -H "host: headers.example"

    Example output:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

    < HTTP/1.1 200 OK
HTTP/1.1 200 OK
...
{
  "headers": {
    "Accept": [
      "*/*"
   ],
    "Host": [
      "headers.example"
    ],
    "My-Header": [
      "hello"
    ],
   "User-Agent": [
      "curl/7.77.0"
    ],
...
 }
}

  3. Send another request to the httpbin app. This time, you already include the my-header header in your request. Verify that you get back a 200 HTTP response code and that your my-header header value is appended with the value from the RequestHeaderModifier filter.

    curl -vi http://${INGRESS_GW_ADDRESS}:8080/headers -H "host: headers.example:8080" \
-H "my-header: foo"
    curl -vi localhost:8080/headers -H "host: headers.example" \
-H "my-header: foo"

    Example output:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

    < HTTP/1.1 200 OK
HTTP/1.1 200 OK
...
{
  "headers": {
     "Accept": [
      "*/*"
    ],
    "Host": [
      "headers.example"
    ],
    "My-Header": [
      "foo",
      "hello"
    ],
...
 }
}

  4. Optional: Remove the resources that you created.

    kubectl delete httproute httpbin-headers -n httpbin

Set request headers

Setting headers is similar to adding headers. If the request does not include the header, it is added by the RequestHeaderModifier filter. However, if the request already contains the header, its value is overwritten with the value from the RequestHeaderModifier filter.

  1. Set up a header modifier that sets a my-header: hello request header.

    kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-headers
  namespace: httpbin
spec:
  parentRefs:
  - name: agentgateway-proxy
    namespace: agentgateway-system
  hostnames:
    - headers.example
  rules:
    - filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            set: 
            - name: my-header
              value: hello
      backendRefs:
        - name: httpbin
          port: 8000
EOF
    SettingDescription
    spec.parentRefsThe name and namespace of the gateway that serves this HTTPRoute. In this example, you use the agentgateway-proxy Gateway that was created as part of the get started guide.
    spec.rules.filters.typeThe type of filter that you want to apply to incoming requests. In this example, the RequestHeaderModifier filter is used.
    spec.rules.filters.requestHeaderModifier.setThe name and value of the request header that you want to set.
    spec.rules.backendRefsThe Kubernetes service you want to forward traffic to. In this example, all traffic is forwarded to the httpbin app that you set up as part of the get started guide.

  2. Send a request to the httpbin app on the headers.example domain. Verify that you get back a 200 HTTP response code and that the my-header: hello header was added.

    curl -vi http://${INGRESS_GW_ADDRESS}:8080/headers -H "host: headers.example:8080"
    curl -vi localhost:8080/headers -H "host: headers.example"

    Example output:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

    < HTTP/1.1 200 OK
HTTP/1.1 200 OK
...
{
  "headers": {
    "Accept": [
      "*/*"
   ],
    "Host": [
      "headers.example"
    ],
    "My-Header": [
      "hello"
    ],
   "User-Agent": [
      "curl/7.77.0"
    ],
...

  3. Send another request to the httpbin app. This time, you already include the my-header header in your request. Verify that you get back a 200 HTTP response code and that your my-header header value is overwritten with the value from the RequestHeaderModifier filter.

    curl -vi http://${INGRESS_GW_ADDRESS}:8080/headers -H "host: headers.example:8080" \
-H "my-header: foo"
    curl -vi localhost:8080/headers -H "host: headers.example" \
-H "my-header: foo"

    Example output:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

    < HTTP/1.1 200 OK
HTTP/1.1 200 OK
...
{
  "headers": {
     "Accept": [
      "*/*"
    ],
    "Host": [
      "headers.example"
    ],
    "My-Header": [
      "hello"
    ],
...

  4. Optional: Remove the resources that you created.

    kubectl delete httproute httpbin-headers -n httpbin

Remove request headers

You can remove HTTP headers from a request before the request is forwarded to the target service in the cluster.

  1. Send a request to the httpbin app and find the User-Agent header.

    curl -vi http://${INGRESS_GW_ADDRESS}:8080/headers -H "host: www.example.com:8080"
    curl -vi localhost:8080/headers -H "host: www.example.com"

    Example output:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

    ...
{
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "www.example.com"
    ],
    "User-Agent": [
      "curl/8.7.1"
    ]
  }
}

  2. Set up a header modifier that removes the User-Agent header when requests are sent to the headers.example domain.

    kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-headers
  namespace: httpbin
spec:
  parentRefs:
  - name: agentgateway-proxy
    namespace: agentgateway-system
  hostnames:
    - headers.example
  rules:
    - filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            remove: 
              - User-Agent
      backendRefs:
        - name: httpbin
          port: 8000
EOF
    SettingDescription
    spec.parentRefsThe name and namespace of the gateway that serves this HTTPRoute. In this example, you use the agentgateway-proxy Gateway that was created as part of the get started guide.
    spec.rules.filters.typeThe type of filter that you want to apply to incoming requests. In this example, the RequestHeaderModifier filter is used.
    spec.rules.filters.requestHeaderModifier.removeThe name of the request header that you want to remove.
    spec.rules.backendRefsThe backend destination you want to forward traffic to. In this example, all traffic is forwarded to the httpbin app that you set up as part of the get started guide.

  3. Send a request to the httpbin app on the headers.example domain . Verify that the User-Agent request header is removed.

    curl -vi http://${INGRESS_GW_ADDRESS}:8080/headers -H "host: headers.example:8080"
    curl -vi localhost:8080/headers -H "host: headers.example"

    Example output:

    {
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "headers.example"
    ]
  }
}

  4. Optional: Clean up the resources that you created.

    kubectl delete httproute httpbin-headers -n httpbin
Response headers
Agentgateway assistant

Ask me anything about agentgateway configuration, features, or usage.

Note: AI-generated content might contain errors; please verify and test all returned information.

Tip: one topic per conversation gives the best results. Use the + button in the chat header to start a new conversation.

Switching topics? Starting a new conversation improves accuracy.
↑↓ navigate ↵ select esc dismiss

What could be improved?

Your feedback helps us improve assistant answers and identify docs gaps we should fix.

Need more help? Join us on Discord: https://discord.gg/y9efgEmppm

Want to use your own agent? Add the Solo MCP server to query our docs directly. Get started here: https://search.solo.io/.