Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Service Discovery

Forwarding DNS to Consul (systemd-resolved, dnsmasq, CoreDNS)

Make every program resolve .consul names by forwarding that domain from the system resolver to the Consul agent on port 8600, with systemd-resolved, dnsmasq, BIND or CoreDNS.

Consul's DNS server listens on port 8600, but programs ask their system resolver on port 53 and have no way to say "use port 8600 for this one domain". The fix is DNS forwarding: configure the machine's resolver so that anything ending in .consul is sent to the local Consul agent, while every other name goes to your normal upstream DNS. After that, curl http://web.service.consul:8080 just works.

This lesson shows four common forwarding setups. The configuration is read-only (it needs a real resolver and a Consul agent); the stand-ins model how a resolver chooses an upstream and generate config text.

The idea

flowchart LR
  App["Application"] --> R["System resolver (port 53)"]
  R -->|"*.consul"| C["Consul agent (127.0.0.1:8600)"]
  R -->|"everything else"| U["Upstream DNS (company or ISP)"]

One rule, "the suffix .consul goes to the agent", is all that is needed.

Because forwarding happens in the resolver, applications need no change and no Consul library.

Option 1: systemd-resolved

On modern Linux distributions that use systemd-resolved, create a drop-in file, for example /etc/systemd/resolved.conf.d/consul.conf:

INI
[Resolve]
DNS=127.0.0.1:8600
DNSSEC=false
Domains=~consul

The ~ in Domains=~consul is a routing-only domain: queries for consul names go to the listed DNS server, and nothing else is affected. Restart the service:

Terminal
$ sudo systemctl restart systemd-resolved
$ resolvectl query web.service.consul

Specifying a port in DNS= needs a reasonably recent systemd (v246 or newer). On older systems use the dnsmasq approach, or have Consul listen on a different local address and use iptables redirection.

Option 2: dnsmasq

dnsmasq is a small forwarding resolver. One line in /etc/dnsmasq.d/10-consul routes the domain:

TEXT
server=/consul/127.0.0.1#8600

Note the # before the port. Add server= lines for your normal upstreams in the main file, then sudo systemctl restart dnsmasq. The machine's /etc/resolv.conf must point at dnsmasq (127.0.0.1).

Option 3: BIND

For organizations that already run BIND, add a forward zone to named.conf:

TEXT
zone "consul" IN {
  type forward;
  forward only;
  forwarders { 10.0.0.11 port 8600; 10.0.0.12 port 8600; };
};

List several Consul agents or servers as forwarders so the zone keeps resolving when one is down. If DNSSEC validation is on, set dnssec-validation no; (or a negative trust anchor) for the consul zone, as Consul does not sign its answers.

Option 4: CoreDNS

CoreDNS (the default DNS in Kubernetes) uses a Corefile block:

TEXT
consul:53 {
    errors
    cache 10
    forward . 127.0.0.1:8600
}
.:53 {
    forward . 8.8.8.8
}

The cache 10 line keeps answers for ten seconds. Keep it shorter than your health-check tolerance, or clients will be told about dead instances for too long.

Letting Consul do the forwarding the other way

Consul can also forward names it does not own. The setting recursors lists upstream DNS servers for non-.consul queries, so you can point applications at the Consul agent as their only resolver:

HCL
recursors = ["10.0.0.2"]

This is simple but makes the agent a critical dependency for all name resolution, which is why many teams prefer forwarding in the system resolver and keeping Consul out of the path for other domains.

Using port 53 directly

You can run the agent's DNS on port 53 with ports { dns = 53 }, but ports below 1024 normally need root. Safer choices are Linux capabilities (CAP_NET_BIND_SERVICE on the binary), or an iptables/nftables redirect from port 53 to 8600. The resolver-forwarding options above avoid running a privileged agent at all.

Stand-in 1: pick an upstream

Resolvers choose by the longest matching domain suffix. This stand-in implements that rule with three entries: consul, a company domain and the default upstream.

Python Stand-in: route a name to an upstream

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: generate forwarding snippets

Generating the config from one source of truth avoids copy-paste mistakes. This model prints the dnsmasq, systemd-resolved and CoreDNS snippets for a given agent address and port.

Python Stand-in: generate resolver config

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.

Testing and troubleshooting

  1. Query the agent directly: dig @127.0.0.1 -p 8600 web.service.consul. If this fails, the problem is Consul or the service registration.
  2. Query through the resolver: dig web.service.consul (no @). If only this fails, forwarding is misconfigured.
  3. Check that applications use the system resolver. Containers often have their own /etc/resolv.conf; point them at a resolver that knows the forwarding rule.
  4. Watch for search domains, which can turn web into web.something.local. Use fully qualified names ending in .consul.
  5. Remember caching: browsers, JVMs and some libraries cache DNS answers on their own.

Do not forward the whole DNS namespace through the Consul agent unless you have set recursors and treat the agent as critical infrastructure. If Consul is down, a global setup takes name resolution for everything with it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Domains=~consul do in systemd-resolved?

    A ~ prefix defines a routing-only domain, so only matching names use that server.
  2. 2. In dnsmasq, how do you specify a non-standard port in a server line?

    dnsmasq syntax is server=/consul/127.0.0.1#8600.
  3. 3. Your dig against port 8600 works but a plain dig fails. Where is the problem?

    The agent answers correctly, so the system resolver is not sending .consul queries to it.
  4. 4. Why prefer resolver forwarding over making the Consul agent the only resolver?

    Keeping Consul out of the path for other domains limits the blast radius of an agent failure.

Summary

  • Programs resolve names through the system resolver on port 53, so forward .consul to the agent on 8600.
  • systemd-resolved (Domains=~consul), dnsmasq (server=/consul/ip#8600), BIND forward zones and CoreDNS all support this.
  • Test the agent directly first, then through the resolver.
  • Mind caching in resolvers, runtimes and containers.
  • Avoid routing all DNS through Consul unless you have configured recursors and accept the dependency.

Next: The Catalog and Health HTTP APIs