Docker's Built-in DNS

In a large office building, there’s an internal phone directory. It knows:

• “Sales Department” → Extension 201
• “Engineering” → Extension 305
• “HR” → Extension 150

When you dial “Sales Department” from any phone in the building, the internal system looks it up and connects you to extension 201.

If the Sales Department moves to a new office and gets a new extension number, the directory is updated. You still just dial “Sales Department.”

Docker’s embedded DNS is this internal directory. It knows:

• “database” → 172.18.0.2
• “api” → 172.18.0.3
• “frontend” → 172.18.0.4

When a container queries “database,” Docker’s DNS returns the current IP.

Docker runs a DNS server at 127.0.0.11

Inside every container on a custom network, Docker sets up DNS resolution to point to 127.0.0.11.

Check /etc/resolv.conf:

docker exec api cat /etc/resolv.conf

You’ll see:

nameserver 127.0.0.11
options ndots:0

127.0.0.11 is Docker’s embedded DNS server.

DNS resolution flow:

1. Container tries to resolve “database”
2. DNS query is sent to 127.0.0.11 (Docker’s DNS)
3. Docker’s DNS checks:
   • Is “database” a container on the same network? → Yes, return its IP
   • Is it an alias? → Check aliases
   • No match? → Forward query to external DNS (like 8.8.8.8)
4. IP is returned to the container

Network-scoped DNS:

DNS only resolves names for containers on the same network.

If you have:

• api on frontend-net
• database on backend-net

Then from api, querying “database” will fail—they’re not on the same network.

You can give containers additional DNS names using --network-alias.

Example:

docker run -d \
  --name mysql-primary \
  --network app-net \
  --network-alias mysql \
  --network-alias db \
  mysql:8

Now this container can be reached by:

• mysql-primary (its container name)
• mysql (alias)
• db (alias)

All three names resolve to the same IP.

Use case: You have multiple database replicas. You can give them all the same alias, and Docker’s DNS will do round-robin load balancing.

docker run -d --name db1 --network app-net --network-alias database mysql:8
docker run -d --name db2 --network app-net --network-alias database mysql:8

Now when you query “database,” Docker’s DNS alternates between db1 and db2.

What if a container needs to resolve google.com?

1. Container queries 127.0.0.11 for “google.com”
2. Docker’s DNS doesn’t know about “google.com” (it’s not a container)
3. Docker forwards the query to external DNS servers (configured in /etc/resolv.conf on the host)
4. External DNS resolves “google.com” → 142.250.185.46
5. IP is returned to the container

Configure custom DNS servers:

You can tell Docker to use specific DNS servers when forwarding external queries.

In /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

Or per-container:

docker run --dns 8.8.8.8 my-image

---