Request headers

Documentation

Request headers

Use the K8sGateway VirtualHostOption or RouteOption resources to add, append, overwrite, or remove request headers for a specific route or all requests that the gateway serves.

For more information, see the Header manipulation API.

Before you begin

Follow the Get started guide to install K8sGateway, set up a gateway resource, and deploy the httpbin sample app.

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

export INGRESS_GW_ADDRESS=$(kubectl get svc -n gloo-system gloo-proxy-http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS

kubectl port-forward deployment/gloo-proxy-http -n gloo-system 8080:8080

Add request headers

Add request headers to incoming requests.

Use a VirtualHostOption resource to add request headers to all requests that the gateway serves.

Create a VirtualHostOption custom resource to specify your header manipulation rules. In the following example, the my-header: gloo-gateway header is added to each request.

kubectl apply -n gloo-system -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: VirtualHostOption
metadata:
  name: header-manipulation
  namespace: gloo-system
spec:
  options:
    headerManipulation:
      requestHeadersToAdd: 
        - header:
            key: "my-header"
            value: "gloo-gateway"
  targetRefs:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: http
    namespace: gloo-system
EOF

Send a request to the httpbin app. Verify that you get back a 200 HTTP response code and that you see the added request header.

LoadBalancer IP address or hostname:

 curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"

Port-forward for local testing:

curl -vik localhost:8080/headers -H "host: www.example.com:8080"
curl -vik 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
21
22
23
24
25
26
27
28
29
30


* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
HTTP/1.1 200 OK
...
{
 "headers": {
   "Accept": [
     "*/*"
   ],
   "Host": [
     "www.example.com:8080"
   ],
   "My-Header": [
     "gloo-gateway"
   ],
   "User-Agent": [
     "curl/7.77.0"
   ],
   "X-Envoy-Expected-Rq-Timeout-Ms": [
     "15000"
   ],
   "X-Forwarded-Proto": [
     "http"
   ],
   "X-Request-Id": [
     "0338830c-4e0a-4821-9a08-48c5a7b44091"
   ]
  }
}
...

Optional: Remove the resources that you created.

kubectl delete virtualhostoption header-manipulation -n gloo-system

Use a RouteOption resource to add request headers for incoming requests to a specific route.

Create a RouteOption custom resource to specify your header manipulation rules. In the following example, the myheader: gloo-gateway header is added to each request. If this header is already present in the request, the value is overwritten with gloo-gateway (append: false).

kubectl apply -n httpbin -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: RouteOption
metadata:
  name: header-manipulation
  namespace: httpbin
spec:
  options:
    headerManipulation:
      requestHeadersToAdd:
        - header:
            key: "my-header"
            value: "gloo-gateway"
          append: false
EOF

Create an HTTPRoute resource for the httpbin app that references the RouteOption resource that you created.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: httpbin-headers
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: gloo-system
  hostnames:
    - headers.example
  rules:
    - filters:
        - type: ExtensionRef
          extensionRef:
            group: gateway.solo.io
            kind: RouteOption
            name: header-manipulation
      backendRefs:
        - name: httpbin
          port: 8000
EOF

Setting	Description
`spec.parentRefs`	The name and namespace of the gateway that services this HTTP route. In this example, you use the HTTP gateway that was created as part of the get started guide.
`spec.rules.filters.type`	The type of filter that you want to apply to incoming requests. In this example, the `ExternsionRef` filter is used.
`spec.rules.filters.extenstionRef`	The reference to the RouteOption resource that you created earlier.
`spec.rules.backendRefs`	The 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.

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

LoadBalancer IP address or hostname

curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: headers.example:8080"

Port-forward for local testing

curl -vik 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


* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
HTTP/1.1 200 OK
...
{
  "headers": {
    "Accept": [
      "*/*"
   ],
    "Host": [
      "headers.example:8080"
    ],
    "My-Header": [
      "gloo-gateway"
    ],
   "User-Agent": [
      "curl/7.77.0"
    ],
...

Optional: Remove the resources that you created.

kubectl delete httproute httpbin-headers -n httpbin
kubectl delete routeoption header-manipulation -n httpbin

Add headers from a secret

Instead of specifying the headers in your VirtualHostOption or RouteOption resource directly, you can save them to a Kubernetes secret.

Add headers from a Kubernetes secret to each request that the gateway serves.

Create a Kubernetes secret of type gloo.solo.io/header or Opaque that contains the headers that you want to add to a request. The following command creates a Kubernetes secret of type gloo.solo.io/header with two headers x-header-1: one and x-header-2: two.
```
glooctl create secret header my-headers --headers x-header-1=one,x-header-2=two -n gloo-system
```

ℹ️

Make sure that the secret is created in the same namespace that your gateway is deployed to.

Create a VirtualHostOption custom resource to specify your header manipulation rules. In the following example, the myheader: gloo-gateway header is added to each request.

kubectl apply -n gloo-system -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: VirtualHostOption
metadata:
  name: header-manipulation
  namespace: gloo-system
spec:
  options:
    headerManipulation:
      requestHeadersToAdd: 
        - headerSecretRef:
            name: my-headers
            namespace: gloo-system
  targetRefs:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: http
    namespace: gloo-system
EOF

Send a request to the httpbin app. Verify that you get back a 200 HTTP response code and that you see the added request header.

LoadBalancer IP address or hostname

curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"

Port-forward for local testing

curl -vik localhost:8080/headers -H "host: www.example.com:8080"
curl -vik 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
21
22
23
24
25
26
27
28
29
30
31
32
33


* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
HTTP/1.1 200 OK
..
{
   "headers": {
     "Accept": [
       "*/*"
     ],
     "Host": [
       "headers.example:8080"
     ],
     "User-Agent": [
       "curl/7.77.0"
     ],
     "X-Envoy-Expected-Rq-Timeout-Ms": [
       "15000"
     ],
     "X-Forwarded-Proto": [
       "http"
     ],
     "X-Header-1": [
       "one"
     ],
     "X-Header-2": [
       "two"
     ],
     "X-Request-Id": [
       "a7b891d2-93a2-4029-bd98-cd46dd414d03"
     ]
   }
}
...

Optional: Remove the resources that you created.

kubectl delete virtualhostoption header-manipulation -n gloo-system
kubectl delete secret my-headers -n gloo-system

Add headers from a Kubernetes secret for requests to a specific route.

Create a Kubernetes secret of type gloo.solo.io/header or Opaque that contains the headers that you want to add to a request. The following command creates a Kubernetes secret of type gloo.solo.io/header with two headers x-header-1: one and x-header-2: two.
```
glooctl create secret header my-headers --headers x-header-1=one,x-header-2=two -n httpbin
```

ℹ️

Make sure that the secret is created in the same namespace that your gateway is deployed to.

kubectl apply -n httpbin -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: RouteOption
metadata:
  name: header-manipulation
  namespace: httpbin
spec:
  options:
    headerManipulation:
      requestHeadersToAdd:
        - headerSecretRef:
            name: my-headers
            namespace: httpbin
EOF

Create an HTTPRoute resource for the httpbin app that references the RouteOption resource that you created.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: httpbin-headers
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: gloo-system
  hostnames:
    - headers.example
  rules:
    - filters:
        - type: ExtensionRef
          extensionRef:
            group: gateway.solo.io
            kind: RouteOption
            name: header-manipulation
      backendRefs:
        - name: httpbin
          port: 8000
EOF

Send a request to the httpbin app on the headers.example domain and verify that you get back a 200 HTTP response code and the headers that you added to the secret.

LoadBalancer IP address or hostname

curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: headers.example:8080"

Port-forward for local testing

curl -vik 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
21
22
23
24
25
26
27
28
29
30
31
32
33


* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
HTTP/1.1 200 OK
..
{
   "headers": {
     "Accept": [
       "*/*"
     ],
     "Host": [
       "headers.example:8080"
     ],
     "User-Agent": [
       "curl/7.77.0"
     ],
     "X-Envoy-Expected-Rq-Timeout-Ms": [
       "15000"
     ],
     "X-Forwarded-Proto": [
       "http"
     ],
     "X-Header-1": [
       "one"
     ],
     "X-Header-2": [
       "two"
     ],
     "X-Request-Id": [
       "a7b891d2-93a2-4029-bd98-cd46dd414d03"
     ]
   }
}
...

Optional: Remove the resources that you created.

kubectl delete httproute httpbin-headers -n httpbin
kubectl delete routeoption header-manipulation -n httpbin
kubectl delete secret my-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.

Remove specific headers from all requests to the routes that the gateway serves.

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

LoadBalancer IP address or hostname

curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"

Port-forward for local testing

curl -vik localhost:8080/headers -H "host: www.example.com"

Example output:

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


...
{
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "www.example.com:8080"
    ],
    "User-Agent": [
      "curl/7.77.0"
    ],
    "X-Envoy-Expected-Rq-Timeout-Ms": [
      "15000"
    ],
    "X-Forwarded-Proto": [
      "http"
    ],
    "X-Request-Id": [
      "5b14c790-3870-4f73-a12e-4cba9a7eccd7"
    ]
  }
}

Create a VirtualHostOption custom resource to specify your header manipulation rules. In the following example, the User-Agent header is removed from each request.

kubectl apply -n gloo-system -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: VirtualHostOption
metadata:
  name: header-manipulation
  namespace: gloo-system
spec:
  options:
    headerManipulation:
      requestHeadersToRemove: ["User-Agent"] 
  targetRefs:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: http
    namespace: gloo-system
EOF

Send a request to the httpbin app and verify that the User-Agent header is now removed.

LoadBalancer IP address or hostname

curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"

Port-forward for local testing

curl -vik localhost:8080/headers -H "host: www.example.com"

Example output:

{
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "headers.example:8080"
    ],
    "X-Envoy-Expected-Rq-Timeout-Ms": [
      "15000"
    ],
    "X-Forwarded-Proto": [
      "http"
    ],
    "X-Request-Id": [
      "f83bb750-67f7-47dc-8c79-4a582892034c"
    ]
  }
}

Optional: Clean up the resources that you created.

kubectl delete virtualhostoption header-manipulation -n gloo-system

Remove specific headers from requests to a specific route.

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

LoadBalancer IP address or hostname

curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"

Port-forward for local testing

curl -vik localhost:8080/headers -H "host: www.example.com"

Example output:

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


...
{
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "www.example.com:8080"
    ],
    "User-Agent": [
      "curl/7.77.0"
    ],
    "X-Envoy-Expected-Rq-Timeout-Ms": [
      "15000"
    ],
    "X-Forwarded-Proto": [
      "http"
    ],
    "X-Request-Id": [
      "5b14c790-3870-4f73-a12e-4cba9a7eccd7"
    ]
  }
}

Create a RouteOption custom resource to specify your header manipulation rules. In the following example, the User-Agent header is removed from the request.

kubectl apply -n httpbin -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: RouteOption
metadata:
  name: header-manipulation
  namespace: httpbin
spec:
  options:
    headerManipulation:
      requestHeadersToRemove:
        - User-Agent
EOF

Create the HTTPRoute resource for the httpbin app that removes the User-Agent header when requests are sent to the headers.example domain.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: httpbin-headers
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: gloo-system
  hostnames:
    - headers.example
  rules:
    - filters:
        - type: ExtensionRef
          extensionRef:
            group: gateway.solo.io
            kind: RouteOption
            name: header-manipulation
      backendRefs:
        - name: httpbin
          port: 8000
EOF

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

LoadBalancer IP address or hostname

curl -vik http://$INGRESS_GW_ADDRESS:8080/headers -H "host: headers.example:8080"

Port-forward for local testing

curl -vik localhost:8080/headers -H "host: headers.example"

Example output:

{
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "headers.example:8080"
    ],
    "X-Envoy-Expected-Rq-Timeout-Ms": [
      "15000"
    ],
    "X-Forwarded-Proto": [
      "http"
    ],
    "X-Request-Id": [
      "f83bb750-67f7-47dc-8c79-4a582892034c"
    ]
  }
}

Optional: Clean up the resources that you created.

kubectl delete httproute httpbin-headers -n httpbin
kubectl delete routeoption header-manipulation -n httpbin

Response headers