Configure Consul DNS behavior
This topic describes the default behavior of the Consul DNS functionality and how to customize how Consul performs queries.
The Consul DNS is the primary interface for querying records when Consul service mesh is disabled and your network runs in a non-Kubernetes environment. The DNS enables you to look up services and nodes registered with Consul using terminal commands instead of making HTTP API requests to Consul. Refer to the Discover Consul Nodes and Services Overview for additional information.
By default, the Consul DNS listens for queries at
127.0.0.1:8600 and uses the
consul domain. Specify the following parameters in the agent configuration to determine DNS behavior when querying services:
By default, Consul DNS queries return a node's local address, even when being queried from a remote datacenter. You can configure the DNS to reach a node from outside its datacenter by specifying the address in the following configuration fields in the Consul agent:
You can specify a list of addresses in the agent's
recursors field to provide upstream DNS servers that recursively resolve queries that are outside the service domain for Consul.
Nodes that query records outside the
consul. domain resolve to an upstream DNS. You can specify IP addresses or use
go-sockaddr templates. Consul resolves IP addresses in the specified order and ignores duplicates.
You enable non-Consul queries to be resolved by setting Consul as the DNS server for a node and providing a
You can forward all queries sent to the
consul. domain from the existing DNS server to a Consul agent. Refer to Forward DNS for Consul Service Discovery for instructions.
By default, Consul responds to DNS queries in the
consul domain, but you can set a specific domain for responding to DNS queries by configuring the
You can also specify an additional domain in the
alt_domain agent configuration option, which configures Consul to respond to queries in a secondary domain. Configuring an alternate domain may be useful during a DNS migration or to distinguish between internal and external queries, for example.
Consul's DNS response uses the same domain as the query.
In the following example, the
alt_domain parameter in the agent configuration is set to
test-domain, which enables operators to query the domain:
$ dig @127.0.0.1 -p 8600 consul.service.test-domain SRV ;; QUESTION SECTION: ;consul.service.test-domain. IN SRV ;; ANSWER SECTION: consul.service.test-domain. 0 IN SRV 1 1 8300 machine.node.dc1.test-domain. ;; ADDITIONAL SECTION: machine.node.dc1.test-domain. 0 IN A 127.0.0.1 machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment="
Responses to pointer record (PTR) queries, such as
<ip>.in-addr.arpa., always use the primary domain and not the alternative domain.
By default, DNS results served by Consul are not cached. Refer to the DNS Caching tutorial for instructions on how to enable caching.