Getting Local Domains to Work with Kubernetes in Docker Desktop for Mac

In this guide, I will show you how to set up local DNS to work with Kubernetes in Docker Desktop for Mac. We’re going to send *.localhost domain traffic to your local Kubernetes cluster with the help of dnsmasq and some clever IP routing.

Configuring the Host Mac


Make a Loopback Alias

Make into a loopback alias that points at your Mac.

sudo ifconfig lo0 alias

You can turn this into a plist so that the configuration survives reboots. Make a file /Library/LaunchDaemons/localhost.docker.kubernetes.loopback.plist containing the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Configure dnsmasq

Install it via Brew.

brew install dnsmasq

Append the following line to dnsmasq.conf, which will tell dnsmasq to load additional *.conf configuration files from the dnsmasq.d directory.


Create a new file  /usr/local/etc/dnsmasq.d/localhost.conf that directs *.localhost domains to like this:


Restart the service.

sudo brew services restart dnsmasq


Make a new file /etc/resolver/localhost to tell your Mac to use its dnsmasq service to resolve *.localhost domains:


Configuring the Virtual Machine (VM)


Use iptables to tell the VM to forward to (its address for your Mac). The following command uses a minimal Docker image with nsenter(1) to punch through to the containing VM and run iptables there.

docker run -it --privileged --pid=host justincormack/nsenter1 /bin/bash -c "iptables -t nat -A OUTPUT -d -j DNAT --to-destination"

How Does it Work?

  • The VM sends traffic to your Mac.
  • Your Mac sends traffic to itself.
  • Both use dnsmasq to resolve *.localhost domains.
  • dnsmasq always answers with for *.localhost domains.
  • Therefore *.localhost domains, resolved from either your Mac or the VM, always indicate an IP address that routes traffic back to your Mac.

What’s the Deal With the IP Address?

A typical guide for using dnsmasq for local development would tell you to set *.localhost to resolve to That works for your Mac.

The problem with doing that is when your VM resolves  foo.localhost to On your VM, is the VM itself. We don’t want foo.localhost to go to the VM. We want it to go to the host Mac and let the host Mac handle the routing from there.

So we have foo.localhost resolve to, an arbitrary IP address from the private network block. And we separately configure both the host Mac and the VM to loop that traffic back to the host Mac.

Testing It Out

Make sure kubectl is pointed at the docker-desktop cluster:

kubectl config use-context docker-desktop

Install the nginx ingress controller like so:

kubectl apply --wait -f
kubectl apply --wait -f

Navigate to http://anything.localhost in your browser. If everything is working properly, you will see a generic 404 Not Found page.

Did it work for you? Let us know on Twitter!

From 0 to K8s in Hours, Not Months

Don’t waste time and resources on DevOps. Our team of Certified Kubernetes Admins manage and maintain Kubernetes clusters using AWS to host applications for ourselves and our partners.

Check out Revelry Managed Cloud.

You might also be interested in these articles:

More Posts by Joel Wietelmann: