Query Parameter Matching

When configuring the matcher on a route, you may want to specify one or more Query Parameter Matcher to require query parameters with matching values be present on the request. Each query parameter 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


Now let’s create a virtual service with a query parameter match. 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-query-parameter
  namespace: gloo-system
      - 'foo'
      - matcher:
            - name: param1
              value: value1
            - name: param2
            - name: param3
              regex: true
              value: "[a-z]{1}"
          prefix: /
              name: json-upstream
              namespace: gloo-system

We’ve created a virtual service that will match if the request contains a query param called param1 with an exact value of value1. The request must also have a query parameter param2 with any value, and param3 set to a single lowercase letter.

To test we can run the following command. Note that the URL must have quotes around it for curl to accept query parameters.

curl -v -H "Host: foo" "$GATEWAY_URL/posts?param1=value1&param2=value2&param3=v"

This should return a large json response. We can set an incorrect value for query param 1, and see the curl command return a 404:

curl -v -H "Host: foo" "$GATEWAY_URL/posts?param1=othervalue&param2=value2&param3=v"

If we set a different value for query param 2, the command should work:

curl -v -H "Host: foo" "$GATEWAY_URL/posts?param1=value1&param2=othervalue&param3=v"

Finally, if we set an invalid value for query param 3, the command will return a 404:

curl -v -H "Host: foo" "$GATEWAY_URL/posts?param1=value1&param2=value2&param3=vv"


In this guide, we created a virtual service that utilized query parameter matching and showed how to match on an exact value, any value, and a regex.

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

kubectl delete vs -n gloo-system test-query-parameter
kubectl delete upstream -n gloo-system json-upstream

glooctl delete vs test-query-parameter
glooctl delete upstream json-upstream