Enable dynamic DNS queries

This topic describes how to dynamically query the Consul catalog using prepared queries. Prepared queries are configurations that enable you to register a complex service query and execute it on demand. For information about how to perform standard node and service lookups, refer to Perform Static DNS Queries.

Introduction

Prepared queries provide a rich set of lookup features, such as filtering by multiple tags and automatically failing over to look for services in remote datacenters if no healthy nodes are available in the local datacenter. You can also create prepared query templates that match names using a prefix match, allowing a single template to apply to potentially many services. Refer to Query Consul Nodes and Services Overview for additional information about DNS query behaviors.

Requirements

Consul 0.6.4 or later is required to create prepared query templates.

ACLs

If ACLs are enabled, the querying service must present a token linked to permissions that enable read access for query, service, and node resources. Refer to the following documentation for information about creating policies to enable read access to the necessary resources:

Create prepared queries

Refer to the prepared query reference for usage information.

  1. Specify the prepared query options in JSON format. The following prepared query targets all instances of the redis service in dc1 and dc2:

    1. {
    2.   "Name": "my-query",
    3.   "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
    4.   "Token": "",
    5.     "Service": {
    6.       "Service": "redis",
    7.       "Failover": {
    8.         "NearestN": 3,
    9.         "Datacenters": ["dc1", "dc2"]
    10.       },
    11.       "Near": "node1",
    12.       "OnlyPassing": false,
    13.       "Tags": ["primary", "!experimental"],
    14.       "NodeMeta": {
    15.         "instance_type": "m3.large"
    16.       },
    17.       "ServiceMeta": {
    18.         "environment": "production"
    19.       }
    20.     },
    21.     "DNS": {
    22.       "TTL": "10s"
    23.     }
    24. }

    Refer to the prepared query configuration reference for information about all available options.

  2. Send the query in a POST request to the /query API endpoint. If the request is successful, Consul prints an ID for the prepared query.

    In the following example, the prepared query configuration is stored in the payload.json file:

    1. $ curl --request POST --data @payload.json http://127.0.0.1:8500/v1/query
    2. {"ID":"014af5ff-29e6-e972-dcf8-6ee602137127"}%

  3. To run the query, send a GET request to the endpoint and specify the ID returned from the POST call.

    1. $ curl http://127.0.0.1:8500/v1/query/14af5ff-29e6-e972-dcf8-6ee602137127/execute\?near\=_agent

Execute prepared queries

You can execute a prepared query using the standard lookup format or the strict RFC 2782 SRV lookup.

Standard lookup

Use the following format to execute a prepared query using the standard lookup format:

  1. <query name or id>.query[.<datacenter>].<domain>

Refer Standard lookups for additional information about the standard lookup format in Consul.

RFC 2782 SRV lookup

Use the following format to execute a prepared query using the RFC 2782 lookup format:

  1. _<query name or id>._tcp.query[.<datacenter>].<domain>

For additional information about following the RFC 2782 SRV lookup format in Consul, refer to RFC 2782 Lookup. For general information about the RFC 2782 specification, refer to A DNS RR for specifying the location of services (DNS SRV).

Lookup options

The datacenter subdomain is optional. By default, the lookup queries the datacenter of this Consul agent.

The query name or id subdomain is the name or ID of an existing prepared query.

Results

To allow for simple load balancing, Consul returns the set of nodes in random order for each query. Prepared queries support A and SRV records. SRV records provide the port that a service is registered. Consul only serves SRV records if the client specifically requests them.