Guide How to Use Consul DNS Locally on macOS
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.