Service discovery catalog

Once services have been registered into the catalog with their respective health checks, application consumers can dynamically discover results to dial these services directly. As services scale up or down, the service catalog becomes the source of truth for finding healthy service instances using DNS.

DNS discovery

Once you have configured DNS forwarding following the recommendations in the initial configuration section, you can discover services and dial them directly using Consul’s domain and query syntax, as shown below.

[<tag>.]<service>.service[.<namespace>.ns][.<partition>.ap].<domain>

• The TLD part <domain> is configured as .consul by default.
• The tag, namespace, and partition segments are optional.
• By default, all service lookups use the default namespace within the partition of the Consul agent that received the DNS query.

Consul server agents reside in the default partition. If your DNS queries target Consul server agents via DNS forwarding, you must explicitly specify the partition of the target service when querying for services in partitions other than “default”.

For more information on performing DNS queries against the service catalog, refer to the documentation.

Prepared queries

To perform more advanced dynamic queries, application developers should leverage prepared queries. Prepared queries enable you to register a service query that provides more complex filtering than you could achieve using a DNS query.

Some restrictions apply to prepared queries:

• they can be defined only via Terraform or the API,
• they can be defined only in the default partition of a Consul datacenter.

You can not create prepared queries outside of the default partition. But, you can target services or service sameness groups located within other partitions.

When creating prepared queries that target services located in different local partitions within the same Consul datacenter, you do not need to export these services to the default partition as you would for services that exist in remote peers as long as your consumer Consul token has service:read permission across the partitions.

Prepared queries provide a rich set of lookup features. You can create queries that filter by including or excluding multiple tags, filter by service meta values, or filter services running on nodes based on node metadata defined inside the Consul client configuration.

Another important consideration is that you can define a TTL within your prepared query definition to reduce the load on Consul servers and anything in the DNS forwarding path. Prepared queries also offer rich failover capabilities, covered in the Standardizing Consul HVD Operating Guide, which covers running Consul Enterprise across multiple regions.

This is an example of a prepared query:

{
    "Name": "my-query",
    "Service": {
        "Service": "redis",
        "Near": "node1",
        "OnlyPassing": true,
        "Tags": ["primary", "!experimental"],
        "NodeMeta": { "instance_type": "m3.large" },
        "ServiceMeta": { "environment": "production" }
    },
    "DNS": {
        "TTL": "10s"
    }
}

Below is an example DNS query to discover services leveraging the above-prepared query.

my-query.query.<domain>

For detailed information on creating and reading the configuration of existing prepared queries, see here.