Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Service Discovery

The Consul DNS Interface

Resolve services with Consul DNS on port 8600: the name formats for services, nodes, tags and datacenters, A versus SRV records, only_passing, TTLs and truncation.

The most universal way to use Consul needs no client library at all: DNS. Every operating system and programming language can resolve a name, so an application that connects to web.service.consul is already a Consul user. The agent answers DNS queries on port 8600 (not 53) under the domain .consul.

The commands here are read-only because the site has no Consul agent. A name parser and a response simulator are runnable stand-ins.

Asking the agent

With a dev agent running, dig can query it directly:

Terminal
$ dig @127.0.0.1 -p 8600 web.service.consul
$ dig @127.0.0.1 -p 8600 web.service.consul SRV

An A record answer holds the instance addresses. An SRV record answer adds the port and the weight, plus additional records that map the target host names to IP addresses. Since SRV carries the port, it is the right query when instances listen on different ports (typical with containers). A plain A lookup tells you nothing about ports, so clients using A must agree on a fixed port.

Name formats

All names end in .consul (the domain is configurable with domain in the agent config). The pieces in between:

Name pattern Meaning
<service>.service.consul Healthy instances of a service
<tag>.<service>.service.consul Only instances carrying the tag
<service>.service.<dc>.consul Instances in another datacenter
<node>.node.consul Address of a node
<node>.node.<dc>.consul A node in another datacenter
<name>.query.consul A prepared query (see prepared queries)
_<service>._<tag>.service.consul RFC 2782 SRV style; use _tcp as the tag for any

Example: v2.web.service.dc2.consul is "web instances tagged v2 in datacenter dc2".

What the answer contains

Consul only returns instances that are not critical. By default instances in the warning state are still returned; set only_passing = true in dns_config to hide them as well:

HCL
dns_config {
  only_passing = true      # hide instances with warning checks
  service_ttl {
    "*" = "5s"             # let clients cache answers for 5 seconds
    "web" = "10s"
  }
  node_ttl = "30s"
}

Other behaviors worth knowing:

  • Shuffling. The order of A records is randomized on every response, so naive clients that use the first address spread load across instances without extra work.
  • TTL. The default TTL is 0 seconds, which means every connection triggers a lookup. That is correct for health freshness but chatty; a TTL of a few seconds is a good trade for busy systems. Remember that a cached answer can name an instance that has since failed.
  • Truncation. Over UDP, Consul limits the number of records in a reply (udp_answer_limit). If the answer is cut short, clients retry over TCP. Large services (dozens of instances) should be queried with SRV over TCP or through the HTTP API.
  • Case. DNS names are case-insensitive; Consul service names are normally lowercase.

Making the rest of the system use it

Port 8600 is awkward for applications, which expect port 53. You will forward the .consul domain from the system resolver to the agent in a later lesson. Until then, scripts can use dig, and code can use a DNS library that lets you specify a server and port.

Stand-in 1: parse Consul names

A parser that classifies a Consul DNS name into its meaning. This is a model written for teaching, following the table above.

Python Stand-in: decode a Consul DNS name

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: what an answer looks like

A simulation of how the agent builds an answer from instance states: drop critical, optionally drop warning, shuffle, cap the UDP answer. The data is invented and the seed fixed.

Python Stand-in: build a DNS answer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical tips

  • Use SRV (or the API) when ports vary; use A when every instance uses the same port.
  • Keep application-side DNS caches short. Some runtimes cache lookups forever by default; set their TTL explicitly or you will keep connecting to dead instances.
  • Prefer tag prefixes for version pinning instead of putting the version in the service name.
  • DNS answers carry no ACL token by default. When ACLs deny anonymous reads, give the DNS agent a default token with read access to the services you intend to expose.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. On which port does the Consul agent answer DNS by default?

    DNS is on 8600; applications normally reach it through a resolver that forwards .consul to that port.
  2. 2. Which query returns the port numbers of instances as well as their addresses?

    SRV records contain the port and weight; A records only contain addresses.
  3. 3. What does only_passing = true change?

    By default only critical instances are dropped; only_passing also drops warnings.
  4. 4. How do you ask for web instances in datacenter dc2?

    The datacenter goes after the service keyword: web.service.dc2.consul.

Summary

  • Consul DNS listens on 8600 under .consul; every language can use it.
  • Names: <service>.service.consul, tag prefixes, <dc> after service, <node>.node.consul, <query>.query.consul.
  • A gives addresses; SRV adds ports and weights.
  • Critical instances are always hidden; only_passing also hides warnings.
  • TTL, UDP truncation and client-side caching affect freshness.

Next: Forwarding DNS to Consul