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
false(default) - will match if
valueexactly matches query parameter value
valuefield as a regular expression
- If no value is specified, then the presence of the query parameter in the request with any value will match
- If present, the
valuefield will be interpreted based on the value of
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 Edge, you can start by following the directions contained within the guide Installing Gloo Edge on Kubernetes.
This guide also assumes that you are running Gloo Edge 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.
- addr: jsonplaceholder.typicode.com
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.
- name: param1
- name: param2
- name: param3
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.
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¶m2=value2¶m3=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¶m2=value2¶m3=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¶m2=othervalue¶m3=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¶m2=value2¶m3=vv"
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
Query parameter matching rules are not the only rules available for routing decisions. We recommend checking out any of the following guides next: