This is a guide how to use Consul’s DNS service from your local macOS machine.

Test resolution by hand

Run this command to see if you can communicate with consul correctly and it resolves domain names for you:

dig vault.service.consul @$CONSUL_IP -p 8600

As response you should get the A record that will look similar to this (look for ANSWER SECTION):

;; ANSWER SECTION:
vault.service.consul.	0	IN	A	123.123.123.123

(the IP address will be different in your case)

If you have any issues here you have to resolve them before going forward, in case you are getting timeouts or other errors this might mean that for example your consul service isn’t accessible from outside the cluster, you have some firewall rules in place or other issues.

After verifying that everything works by hand we can start plugging the pieces together to make it all work automatically.

Install and run dnsmasq

brew install dnsmasq

Setup auto start at system launch

sudo brew services start dnsmasq

If you are asked about permissions to launch services at system start time, you have to approve it.

Configure dnsmasq to queries to consul

Edit file /usr/local/etc/dnsmasq.conf as root and add following line at the end:

# redirect .consul domain queries to consul server
server=/consul/1.2.3.4#8600

Make sure to use IP address of the consul server instead of 1.2.3.4

Restart dnsmasq

brew services restart dnsmasq

Test dnsmasq

Run this

dig vault.service.consul @127.0.0.1

The command above verifies the DNS resolution and uses locally running dnsmasq explicitly, you should receive the A record as in the previous output.

Setup macOS-wide DNS

In order to do this I have modified my DNS entries via “Network Preferences” in macOS:

I have added 127.0.0.1 at the top which points to the dnsmasq running on my machine.

Verify that it works

After completing the steps above you can try the dig command once more:

dig vault.service.consul

See that now we don’t have explicitly choose DNS server, the DNS servers are taken in order from the system-wide settings.

If you inspect the bottom of the dig output you should see the information which server was used:

;; Query time: 24 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Wed Mar 20 10:29:27 CET 2019
;; MSG SIZE  rcvd: 139

Which confirms that everything works OK.

Summary

In this guide, we have started dnsmasq on our local machine and configured it to forward all requests for .consul domain name to the consul DNS service. We have also updated our system-wide settings to always use this instance of dnsmasq as first priority DNS server.

By forwarding all .consul domain names to Consul DNS you can use all services resolved by Consul as if you were part of the cluster.