Skip to main content
In this guide, we’ll cover how to leverage Consul Prepared Queries for metadata-driven traffic routing. You’ll learn to create, inspect, and update prepared queries to shift traffic seamlessly between service versions.

​
Consul Cluster Overview

Start by verifying your cluster members on a server node:
Sample output:
For clarity, here’s the same data in a table: Each client hosts an Apache-based e-commerce front end, registering the front-end-eCommerce service with version tags.

​
Service Registration in the Consul UI

In the Consul web interface, you’ll see two instances of front-end-eCommerce. One is tagged v7.05 and the other v8, both in the production environment.
The image shows a web interface for managing services, specifically displaying two web servers under "front-end-eCommerce," with all service checks passing.

​
Creating a Prepared Query

  1. Save this JSON as prepared-query.json:
  2. Register the query via Consul’s HTTP API:
    Response:
  3. Inspect the full query definition:
Set "OnlyPassing": true in your query definition to ensure only healthy service instances are returned.

​
Querying via DNS

Consul exposes prepared queries under the *.query.consul DNS domain. Run:
You should see the IP of the v7.05 instance:

​
Updating the Prepared Query to v8

When it’s time to shift traffic to version v8, update prepared-query.json:
Apply the update with a PUT request (replace the ID):
Then verify with DNS again:
Always replace the query ID in your API URL when inspecting or updating prepared queries.

​
Conclusion

Consul Prepared Queries enable you to route client requests based on service metadata without touching client configurations. By updating the query payload, you can perform zero-downtime version rollouts and A/B testing with ease.

Watch Video

Practice Lab