☰
Navigation :

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:

Setup

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

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: