Query Parameter Matching

When configuring the matcher on a route, you may want to specify one or more gloo.solo.io.QueryParameterMatcher to require query parameters with matching values be present on the request. Each query parameter matcher has three attributes:


This guide assumes that you have deployed Gloo to the gloo-system namespace and that the glooctl command line utility is installed on your machine. glooctl provides several convenient functions to view, manipulate, and debug Gloo resources; in particular, it is worth mentioning the following command, which we will use each time we need to retrieve the URL of the Gloo Gateway that is running inside your cluster:

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'
      - matchers:
         - queryParameters:
            - name: param1
              value: value1
            - name: param2
            - name: param3
              regex: true
              value: "[a-z]{1}"
           prefix: /
              name: json-upstream
              namespace: gloo-system
          autoHostRewrite: true

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" "$(glooctl proxy 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" "$(glooctl proxy 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" "$(glooctl proxy 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" "$(glooctl proxy 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