Embedded DNS — how service name resolution works · Docker & Containers

On a user-defined network, Docker runs an embedded DNS server at 127.0.0.11 inside each container’s network namespace. Container names and network aliases resolve to addresses on that network. On the default bridge network there is no embedded resolver and no service discovery at all.

The important thing about the embedded resolver is what it resolves from. It has no zone file and no cache of its own. Every answer comes from the daemon’s live model of which containers are attached to which networks under which names — which is why the answers are always current, and why “current” is not the same as “working”.

The lookup path

sequenceDiagram
  participant App as Application
  participant DNS as Embedded DNS<br/>127.0.0.11
  participant Reg as Daemon network registry
  participant Up as Upstream resolvers
  App->>DNS: A? api
  DNS->>Reg: is "api" a name or alias<br/>on a network this container is on?
  alt known
    Reg-->>DNS: 172.18.0.5
    DNS-->>App: 172.18.0.5
  else not known
    DNS->>Up: forward, servers tried in order
    Up-->>DNS: answer, or NXDOMAIN
    DNS-->>App: same
  end

Two rules govern the first branch, and both are about scope:

The registry is consulted only for networks this container is attached to. A container on frontend cannot resolve a container that exists only on backend, even though both are on the same host and the daemon knows about both.
A container attached to several networks can resolve names on all of them. It is the union, not an intersection, and it is why a shared “management” network makes previously invisible names resolvable everywhere.

Forwarding, the second branch, is a plain recursive-resolver relationship: the embedded server “queries upstream servers in order and stops after a successful response or an NXDOMAIN response”.

Asking the resolver directly

Read-only / Safequery the embedded server— Target 127.0.0.11 explicitly so you know which resolver answered. Requires dig or nslookup in the image; netshoot has both.

CONTAINER=app

# What does the resolver itself say?
docker exec "$CONTAINER" nslookup api 127.0.0.11

# The path the application actually takes: /etc/hosts, then NSS, then DNS
docker exec "$CONTAINER" getent hosts api

# If the image is minimal, borrow a toolbox in the same namespace
docker run --rm -it --network "container:$CONTAINER" \
nicolaka/netshoot dig @127.0.0.11 api

The last form is the one to remember. --network container:$CONTAINER puts the debug container in the same network namespace as the target, so 127.0.0.11 is the same resolver, on the same networks, with the same view. Running dig from a different container answers a different question.

Several containers, one name

Scale a service and more than one container carries the same alias. The resolver returns all of the matching addresses, and clients that use only the first get an even-ish spread as the order varies between answers.

Read-only / Safethree replicas, one alias— Same set, different order. That rotation is the whole of the load balancing.

$ docker compose up -d --scale worker=3
docker compose exec app getent hosts worker
echo '--- again ---'
docker compose exec app getent hosts worker

172.18.0.4        worker
172.18.0.5        worker
172.18.0.6        worker
--- again ---
172.18.0.5        worker
172.18.0.6        worker
172.18.0.4        worker

Illustrative output

The rotation is not health-aware

This is the correction worth carrying away from this lesson, because the opposite is widely believed and it is the difference between a partial outage and a full one.

The embedded resolver returns addresses from the daemon’s registry. Attached and running is the entire test. It does not consult the container’s HEALTHCHECK status, and it does not remove an address because connections to it are failing.

So with three replicas and one wedged, roughly a third of lookups put the broken address first. A client that takes the first answer fails one request in three, retries, and probably succeeds — producing an error rate that is high enough to page and low enough to be dismissed as flapping. Nothing in docker ps looks wrong; the container is up, it is just not answering.

DNS rotation is not load balancing and not failover. If you need either, put a real proxy in front — HAProxy, nginx, Traefik — and let it health-check the backends. docker-haproxy-load-balancing covers the pattern.

Swarm services are the exception: a Swarm service gets a virtual IP with load balancing that does track task state. Standalone Compose scaling does not, and the two look identical from inside the container.

When the registry changes, and what does not

The daemon updates the registry on network attach and detach — container start, docker network connect, docker network disconnect, container stop. The resolver reads it live, so there is no TTL to wait out and no propagation: the very next query returns the new state.

That property is genuinely better than external DNS, and it is also why caching elsewhere hurts so much more than people expect. Nothing in the Docker layer is stale, so every stale address in an incident came from a caller:

A connection pool holding an established socket to an address that has been reassigned.
A reverse proxy that resolved its upstream once at config-load time — nginx does exactly this for a plain proxy_pass to a hostname.
A JVM with networkaddress.cache.ttl=-1, which caches successful lookups for the life of the process.
Application-level memoisation of a resolved address.

Address reuse makes it worse rather than better. Docker’s IPAM allocates the lowest free address on the network, so a container that restarts after another one was created often gets an address that now belongs to a different service. The cached client does not get a connection error — it gets a successful connection to the wrong container, and the error surfaces as a protocol or authentication failure somewhere much further downstream.

docker-dns-names-aliases-renames and docker-dns-resolver-behaviour-timeouts go through the caching layers and the resolver options in detail.

Custom DNS servers

Setting dns: on a service replaces the upstream servers the embedded resolver forwards to. It does not replace the embedded resolver itself, and it does not disable service discovery.

services:
  app:
    image: myapp:1.0.0
    networks: [appnet]
    dns:
      - 192.0.2.53
      - 198.51.100.53
    dns_search:
      - example.com
      - internal.example.com

The container’s /etc/resolv.conf still reads nameserver 127.0.0.11. Container names still resolve from the registry. Only the forwarding target changed. An application configured to talk to 8.8.8.8 directly, bypassing resolv.conf entirely, is the case where service names genuinely stop working — and the fix is to make the application use the system resolver, not to change anything in Docker.

What happens if a container is on no user-defined network at all?

It has no embedded resolver. /etc/resolv.conf is a copy of the host’s, and container names resolve only if your upstream DNS happens to know them, which it does not.

This covers three cases that look different and behave identically:

The default bridge network, from a docker run with no --network.
--network host, where the container is in the host’s network namespace and uses the host’s resolver configuration directly.
--network none, where there is no route to the nameservers either, so the lookup times out rather than returning NXDOMAIN.

docker inspect --format '{{range $n, $c := .NetworkSettings.Networks}}{{$n}} {{end}}' "$CONTAINER" distinguishes them in one command, and should be the first thing you run for any report of the form “it cannot find the other container”.

What happens if two containers on different networks have the same name?

Nothing collides, because resolution is scoped to the querying container’s networks. A container on frontend asking for cache gets the cache on frontend; a container on backend gets the one on backend.

It stops being harmless the moment a container is attached to both. Then the name is ambiguous, the resolver returns addresses from both networks, and the client picks one — with no indication that it is now reaching a different service than it was yesterday.

A shared observability or management network is the usual way this arrives, because it is added to everything at once and long after the names were chosen. Prefer distinct service names across a whole Compose project even when the networks are separate; the isolation you are relying on is one docker network connect away from not existing.

Why this matters

DNS is the silent failure mode: containers start, report healthy, and cannot reach their dependencies. The diagnostic tree is short and it is worth running in order, because each step eliminates a layer:

Which networks is the container on? On the default bridge, host or none, service names have never resolved.
Does the resolver answer? getent hosts <name> from inside the container.
Does forwarding work? getent hosts example.com from the same place.
Is the answer useful? The resolver returning an address is not evidence that anything is listening on it.

Step 4 is the one this lesson exists for. The embedded resolver tells you where a container is. It does not tell you whether it works, and it will keep handing out the address of a wedged replica for as long as that replica is attached. Health belongs to a proxy or an orchestrator; DNS was never going to provide it.

Sanity check

docker exec "$CONTAINER" cat /etc/resolv.conf shows nameserver 127.0.0.11.
getent hosts from inside the container resolves both a peer service name and an external name.
For any name backed by more than one container, something with health checks sits in front of it — you can name what that something is.
No two services in the project share a name, even across separate networks.

The lookup path

Asking the resolver directly

Several containers, one name

Custom DNS servers

Sanity check

Knowledge check