Query Parameter Matching

The route rules in a Virtual Service can use query parameter matching rules to match requests to routes based on the values stored in parameters submitted with the request. 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:

• name - the name of the query parameter
• regex - boolean (true|false) defaults to false. Indicates how to interpret the value attribute:
  • false (default) - will match if value exactly matches query parameter value
  • true - treat value field as a regular expression
• value
  • If no value is specified, then the presence of the query parameter in the request with any value will match
  • If present, the value field will be interpreted based on the value of regex field

Setup

Before you begin, this guide assumes that you have the following setup.

1. Install Gloo Gateway in the gloo-system namespace.
2. Enable discovery mode for Gloo Gateway. If not, make sure that you created any Upstream resources with the appropriate functions.
3. Install the glooctl command line tool.
4. Identify the URL of the gateway proxy that you want to use for this guide, such as with the glooctl proxy command. Note that if you are testing in a local cluster such as Kind, you must use the custom localhost port that you configured instead of glooctl proxy, such as http://localhost:31500.

If you have not yet deployed Gloo Gateway, you can start by following the directions contained within the guide Installing Gloo Gateway on Kubernetes.

This guide also assumes that you are running Gloo Gateway in a Kubernetes cluster. Each example can be adapted to alternative deployments, such as using the HashiCorp stack of Nomad, Consul, and Vault.

Create an Upstream

First we are going to create a simple Upstream for testing called json-upstream, that routes to a static site.

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

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

The site referenced in the Upstream is JSONPlaceholder - an online REST API for testing and prototyping.

Query parameter matching

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
metadata:
  name: test-query-parameter
  namespace: gloo-system
spec:
  virtualHost:
    domains:
      - 'foo'
    routes:
      - matchers:
         - queryParameters:
            - name: param1
              value: value1
            - name: param2
            - name: param3
              regex: true
              value: "[a-z]{1}"
           prefix: /
        routeAction:
          single:
            upstream:
              name: json-upstream
              namespace: gloo-system
        options:
          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 several curl commands with different parameter combinations. Note that the URL must have quotes around it for curl to accept query parameters.

Correct parameters

In the first request, we will set the parameters to the expected values in our Virtual Service. The response will be a list of blog posts from the Upstream.

curl -v -H "Host: foo" "$(glooctl proxy url)/posts?param1=value1&param2=value2&param3=v"

Testing the first parameter

For our next request, we will set an incorrect value for query param1. The response will be a 404 from the Virtual Service since it has no valid route for the request.

curl -v -H "Host: foo" "$(glooctl proxy url)/posts?param1=othervalue&param2=value2&param3=v"

Testing the second parameter

The second parameter (param2) does not have a required value specified. If we set a different value for query param2, the response will be successfully sourced from the Upstream.

curl -v -H "Host: foo" "$(glooctl proxy url)/posts?param1=value1&param2=othervalue&param3=v"

Testing the third parameter

The third parameter (param3) is expecting a single lower case letter. If we set it to more than one character, the request will return a 404 response.

curl -v -H "Host: foo" "$(glooctl proxy url)/posts?param1=value1&param2=value2&param3=vv"

Summary

In this tutorial, we created a static Upstream and Virtual Service that utilized query parameter matching. We saw how the route rules matched 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

Next Steps

Query parameter matching rules are not the only rules available for routing decisions. We recommend checking out any of the following guides next:

• Path Matching
• Header Matching
• HTTP Method Matching