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: vault.service.consul. 0 IN A 22.214.171.124
(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
/usr/local/etc/dnsmasq.conf as root and add following line at the end:
# redirect .consul domain queries to consul server server=/consul/126.96.36.199#8600
Make sure to use IP address of the consul server instead of
brew services restart dnsmasq
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:
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.
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.