DNS and the embedded resolver · Docker & Containers

Container DNS is not host DNS. For containers attached to a custom network, Docker runs an embedded DNS server at 127.0.0.11 inside the container’s network namespace. It resolves container names and network aliases from the daemon’s own registry, and forwards everything else to the resolvers the host uses.

For containers on the default bridge network, none of that happens.

The single most common Docker DNS incident

Read-only / Safesame command, two networks— Identical command. The only difference is which network the containers are on.

$ # Default bridge — no --network flag
docker run -d --name db-a  alpine:3.20 sleep 600
docker run --rm --name app-a alpine:3.20 getent hosts db-a

echo '=== user-defined network ==='
docker network create appnet
docker run -d --name db-b --network appnet alpine:3.20 sleep 600
docker run --rm --network appnet alpine:3.20 getent hosts db-b

(no output, exit status 2)

=== user-defined network ===
172.18.0.2        db-b

Illustrative output

The default bridge has no service discovery

A container attached to the default bridge network does not get the embedded resolver. Upstream draws the line explicitly: containers on the default bridge “receive a copy” of the host’s /etc/resolv.conf, while containers attached to a custom network “use Docker’s embedded DNS server”.

So on the default bridge, db resolves only if your upstream DNS knows about a host called db. Container names are not in it. The lookup does not fail loudly — it goes to your corporate resolver, gets NXDOMAIN, and the application reports that it cannot reach the database.

This single fact accounts for a large share of “it worked in Compose and broke when I ran it by hand”. Compose creates a user-defined network for every project. A bare docker run with no --network does not.

The fix is one command, and it is not a DNS change:

docker network create appnet — then attach both containers to it.

Nothing else about the default bridge is worth working around. It has no service discovery, its ICC rules are host-wide rather than per-network, and --link is the legacy mechanism it was given instead. Treat “attached to the default bridge” as a configuration defect in its own right.

What the embedded resolver does with a query

sequenceDiagram
  participant App as Application
  participant Res as libc resolver
  participant DNS as Embedded DNS<br/>127.0.0.11
  participant Up as Upstream<br/>(host resolv.conf)
  App->>Res: getaddrinfo("db")
  Res->>Res: check /etc/hosts first
  Res->>DNS: A? db
  alt db is a container or alias on one of this container's networks
    DNS-->>Res: 172.18.0.2
  else not known to the daemon
    DNS->>Up: forward the query, servers tried in order
    Up-->>DNS: answer, or NXDOMAIN
    DNS-->>Res: same
  end
  Res-->>App: address, or EAI_NONAME

Two details in that diagram earn their place:

/etc/hosts is consulted before DNS, per nsswitch.conf. An entry there — including one you added with --add-host — wins over anything the embedded resolver would have said, and no DNS debugging will show it.
Upstream servers are tried in order, and the embedded server “stops after a successful response or an NXDOMAIN response”. A first resolver that answers NXDOMAIN authoritatively ends the search; the second one is never asked. That is standard resolver behaviour and it surprises people who list a public resolver second as a “backup”.

Why the resolver is at 127.0.0.11 and what is really listening

127.0.0.11 is inside the container’s own network namespace, on lo. It is not routable and it is not the same address in two containers — each namespace has its own.

What listens there is not a full DNS server. It is a resolver process the daemon runs, with a set of iptables rules inside the container’s namespace that redirect traffic for 127.0.0.11:53 to an ephemeral port the daemon holds. You can see them:

docker exec "$CONTAINER" iptables -t nat -S 2>/dev/null

The address was chosen inside 127.0.0.0/8 precisely because that block is loopback-only: no packet destined there can leave the namespace, so the resolver cannot be reached from another container or from the host, and the container cannot be tricked into sending its queries somewhere else by a routing change.

There is no IPv6 equivalent. Upstream is explicit that the IPv4 address works even in IPv6-only containers, and that an application needing an explicit resolver address should use 127.0.0.11.

Configuring DNS

There are exactly three places to set this, and it is worth being precise about them because invented options are common in this area.

Per container

Configuration changerun flags— --dns replaces the upstream servers the embedded resolver forwards to. It does not replace 127.0.0.11 in resolv.conf on a custom network.

docker run -d --name app \
--network appnet \
--dns 192.0.2.53 \
--dns 198.51.100.53 \
--dns-search example.com \
--dns-opt ndots:1 \
--dns-opt timeout:2 \
--dns-opt attempts:2 \
myapp:1.0.0

In Compose

services:
  app:
    image: myapp:1.0.0
    dns:
      - 192.0.2.53
      - 198.51.100.53
    dns_search:
      - example.com
    dns_opt:
      - timeout:2
      - attempts:2

The keys are dns, dns_search and dns_opt. Note the singular dns_opt, not dns_options.

Daemon-wide

Service impact possibledaemon.json— Applies to every container the daemon creates. Requires a daemon restart.

# /etc/docker/daemon.json
{
"dns": ["192.0.2.53", "198.51.100.53"],
"dns-search": ["example.com"],
"dns-opts": ["timeout:2", "attempts:2"]
}

There is no per-network DNS driver option

A pattern that circulates widely — and that this lesson previously carried — is setting DNS per network with driver options such as --opt com.docker.network.bridge.dns_servers. No such option exists.

The bridge driver’s documented options are the bridge name, IP masquerade, ICC, host binding address, MTU, container interface prefix, gateway mode, host SNAT addresses and IPv4 inhibition. None of them concern DNS.

Driver options that Docker does not recognise are not rejected. They are stored on the network object and ignored, so docker network create succeeds, docker network inspect shows your setting in the Options map, and resolution behaves exactly as it did before. Everything looks configured and nothing is.

Set DNS on the container (--dns, Compose dns:) or on the daemon (daemon.json). If you need per-network behaviour, that is what the choice of upstream resolver per service is for.

Diagnosing a resolution failure

Read-only / Safethe four questions— In order. Each one eliminates a layer; do not skip to the last.

CONTAINER=app

# 1. Which network is it on? Anything showing "bridge" has no service discovery.
docker inspect --format \
'{{range $n, $c := .NetworkSettings.Networks}}{{$n}} {{end}}' "$CONTAINER"

# 2. What does the resolver config say?
docker exec "$CONTAINER" cat /etc/resolv.conf

# 3. Is there a static entry shadowing DNS entirely?
docker exec "$CONTAINER" cat /etc/hosts

# 4. Does resolution work, using the same path the application uses?
docker exec "$CONTAINER" getent hosts db
docker exec "$CONTAINER" getent hosts example.com

nslookup and dig do not use the resolver your application uses

getent hosts goes through getaddrinfo, nsswitch.conf and /etc/hosts — the same path a normal application takes. nslookup and dig are DNS diagnostic tools: they speak DNS directly to a server and deliberately bypass /etc/hosts and NSS.

Two failures follow from confusing them, and they point in opposite directions:

nslookup db fails, the application works. A /etc/hosts entry is answering. Common with --add-host, with Compose extra_hosts, and on the default bridge where legacy --link writes hosts entries.
nslookup db succeeds, the application fails. DNS is fine and something else is not — the resolver’s search-domain handling, an Alpine image where musl behaves differently from glibc, a connection refused after a perfectly good resolution, or an application resolving at start-up and caching the answer.

Diagnose with getent hosts. Reach for dig only once you have decided the question really is about DNS, and then use dig @127.0.0.11 db so you are querying the resolver the container actually has.

What if the container cannot resolve external names?

Symptom: curl: (6) Could not resolve host: example.com inside the container, while container-to-container names resolve fine. That combination is informative — the embedded resolver is working; its forwarding is not.

Work down the layers:

Is the host’s DNS working? getent hosts example.com on the host. If that fails, this was never a container problem.
Is the host resolver a loopback stub? systemd-resolved puts 127.0.0.53 in the host’s /etc/resolv.conf. That address means something different inside a container namespace, and the embedded resolver cannot forward to it. This is common enough that docker-dns-resolv-conf-sources in the DNS part covers it in full; the short version is to point Docker at the real upstream servers with "dns" in daemon.json.
Is the upstream reachable from the container? docker exec "$CONTAINER" nc -zvu 192.0.2.53 53 — outbound UDP/53 blocked by an egress rule produces exactly this symptom.
Does the container have any outbound path at all? docker exec "$CONTAINER" ping -c1 192.0.2.1. If the gateway is unreachable, DNS is a symptom and not the problem.

Put every service on a user-defined network. In Compose this is automatic; with docker run it is the --network flag. This alone resolves most name-resolution reports.
Decide what should resolve internally: container names and network aliases, scoped per network.
Decide what should resolve externally, and point the daemon at real upstream resolvers rather than a loopback stub such as 127.0.0.53.
Test both from inside a container, using getent hosts rather than nslookup, so you exercise the same path the application takes.
Give critical services a health check that exercises resolution, so a DNS failure is reported as unhealthy rather than as a pile of application errors.

Sanity check

No production container is on the default bridge network.
docker exec "$CONTAINER" cat /etc/resolv.conf shows nameserver 127.0.0.11 for every container you expect service discovery on.
getent hosts <peer-name> from inside a container returns an address.
getent hosts example.com from inside the same container also returns one, proving forwarding works and not just the registry.