For more information, see the Header manipulation API.

Before you begin

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

  2. 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.

  1. 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

  2. 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:

       * 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"
   ]
  }
}
...

  3. 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.

  1. 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

  2. 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/v1
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
    SettingDescription
    spec.parentRefsThe 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.typeThe type of filter that you want to apply to incoming requests. In this example, the ExternsionRef filter is used.
    spec.rules.filters.extenstionRefThe reference to the RouteOption resource that you created earlier.
    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.

  3. 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:

       * 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"
    ],
...

  4. 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.

  1. 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

  2. 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

  3. 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:

       * 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"
     ]
   }
}
...

  4. 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.

  1. 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

  2. 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:
        - headerSecretRef:
            name: my-headers
            namespace: httpbin
EOF

  3. 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/v1
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

  4. 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:

       * 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"
     ]
   }
}
...

  5. 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.

  1. 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:

       ...
{
  "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"
    ]
  }
}

  2. 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

  3. 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"
    ]
  }
}

  4. 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.

  1. 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:

       ...
{
  "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"
    ]
  }
}

  2. 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

  3. 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/v1
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

  4. 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"
    ]
  }
}

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

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