Header Matching

When configuring the matcher on a route, you may want to specify one or more Header Matchers to require headers with matching values be present on the request. Each header matcher has three attributes:


This guide assumes you’ve installed Gloo into the gloo-system namespace, and glooctl is installed to your machine. Let’s also make sure $GATEWAY_URL is set in your terminal:

export GATEWAY_URL=$(glooctl proxy url)

Let’s create a simple upstream for testing called json-upstream, that routes to a static site:

apiVersion: gloo.solo.io/v1
kind: Upstream
  name: json-upstream
  namespace: gloo-system
        - addr: jsonplaceholder.typicode.com
          port: 80

glooctl create upstream static --static-hosts jsonplaceholder.typicode.com:80 --name json-upstream


Let’s create a virtual service with several header match rules. For simplicity, we’ll set the path matcher to prefix on / to match all request paths:

apiVersion: gateway.solo.io/v1
kind: VirtualService
  name: test-header
  namespace: gloo-system
      - 'foo'
      - matcher:
            - name: header1
              value: value1
            - name: header2
            - name: header3
              regex: true
              value: "[a-z]{1}"
          prefix: /
              name: json-upstream
              namespace: gloo-system

glooctl create vs --name test-header --namespace gloo-system --domains foo 
glooctl add route --name test-header --header "header1=value1" --header "header2=" --header "header3=[a-z]{1}" --path-prefix / --dest-name json-upstream

We can now make a curl request to the new virtual services, and set valid values for each header. In this case, header1 must equal value1, header2 can equal any value, and header3 can equal any value that is a single lowercase letter.

curl -v -H "Host: foo" -H "header1: value1" -H "header2: value2" -H "header3: v"  $GATEWAY_URL/posts

This returns a json list of posts.

If we use an incorrect value for header1, we’ll see a 404:

curl -v -H "Host: foo" -H "header1: othervalue" -H "header2: value2" -H "header3: v"  $GATEWAY_URL/posts

If we use a different value for header2, we’ll see all the posts:

curl -v -H "Host: foo" -H "header1: value1" -H "header2: othervalue" -H "header3: v"  $GATEWAY_URL/posts

And if we use an invalid value for header3, we’ll get a 404:

curl -v -H "Host: foo" -H "header1: value1" -H "header2: value2" -H "header3: value3"  $GATEWAY_URL/posts


In this example, we added header matchers to a virtual service route. We used exact match and regex matchers for a header value, and also showed how to match on a header without any specific value.

Let’s cleanup the virtual service and upstream we used:

kubectl delete vs -n gloo-system test-header
kubectl delete upstream -n gloo-system json-upstream

glooctl delete vs test-header
glooctl delete upstream json-upstream