Container Networking

Two containers on one host are either one virtual cable apart or completely unable to exchange a packet — and the only thing deciding which is a membership list. Watch one name resolve to two different addresses, attach a running container to a second network live, and confirm that publishing a port does nothing for container-to-container traffic.

Concept

Docker runs a private DNS server at 127.0.0.11 inside every container on a user-defined network, and it answers only for containers you share a network with. Alongside it, a set of iptables rules silently drops traffic between separate bridges. Neither is physical: both are derived from a membership list you can change on a running container. This exercise makes that boundary visible from both sides — the name-resolution side and the packet side — and keeps them strictly separate, because conflating them is what makes container networking feel like guesswork.

Provenance

Two pages of the Docker Engine networking documentation, and the exercise tests one sentence from each.

• Networking overview → “DNS services” is where the resolver's address is stated: “Containers that attach to the default bridge network receive a copy of this file. Containers that attach to a custom network use Docker's embedded DNS server. … The embedded DNS server address is 127.0.0.11.” Parts 1 and 2 are exactly this sentence, run.
• Bridge network driver → “Differences between user-defined bridges and the default bridge” supplies the two behavioural claims: “User-defined bridges provide automatic DNS resolution between containers.” versus “Containers on the default bridge network can only access each other by IP addresses, unless you use the --link option, which is considered legacy”; and “Containers can be attached and detached from user-defined networks on the fly. During a container's lifetime, you can connect or disconnect it from user-defined networks on the fly.” Part 4 is that second quote, run against a live container.

Prerequisites

The exercise's own prose covers most of what you need. Two things it leans on without deriving:

• Netfilter/iptables DROP vs REJECT — carries the whole of Part 3. A dropped packet produces silence and therefore a client-side timeout; a rejected one produces an ICMP or RST and therefore an instant refused. If that isn't already reflex, skim the netfilter packet-flow diagram first; the rest of Part 3 is one consequence of it.
• DNAT — carries Part 5. -p 39217:80 is a rewrite rule in the host's nat table, not a change to the container. See Docker's “Packet filtering and firewalls” for the chains Docker installs.

Environment

• Host: macOS 26.5.2 (build 25F84), Apple Silicon (arm64)
• Docker: Docker Desktop, Engine 29.6.2 — Linux VM kernel 6.12.76-linuxkit, 16 GiB allocated to the VM
• Image: nginx:alpine — nginx/1.31.3 on Alpine 3.24.1, digest sha256:4a73073bd557c65b759505da037898b61f1be6cbcc3c2c3aeac22d2a470c1752
• Captured: 2026-07-26

Two figures below are specific to this machine and will differ on yours without changing anything: the upstream resolver 192.168.65.7 (Docker Desktop's VM gateway) and the default-bridge address 172.17.0.10 (which depends on what else you have running). Ping latencies are illustrative — the claim rests on 0% vs 100% packet loss, not on the milliseconds.

Mental model

Two questions, not one

ping other-container is the command everyone reaches for, and it's a bad diagnostic: it can fail for two unrelated reasons and reports both the same way. Split it in half and keep the halves separate for the whole exercise.

The shape of a failure is also information. There are four distinct signatures, and they mean genuinely different things:

The four network modes

The picture

Setup

Two terminals, side by side. Everything below is alpine-based, so the tools (ping, getent, nslookup, wget, ip) are busybox applets that are already there — nothing to install. nginx:alpine is used so each container is also serving something on port 80, which makes reachability testable with more than ICMP.

docker network create net-blue
docker network create net-green

docker run -d --name net-alpha --network net-blue  nginx:alpine
docker run -d --name net-beta  --network net-blue  nginx:alpine
docker run -d --name net-gamma --network net-green nginx:alpine

Note what is not in those docker run lines: no -p. Nothing is published to your host at all, and every bit of traffic in Parts 1–4 still works. Hold onto that for Part 5.

Terminal A — a shell inside net-alpha:

docker exec -it net-alpha sh

Terminal B — a shell inside net-gamma (not needed until Part 3, but open it now and leave it open — Part 4 depends on the same shell process outliving a network change made from outside it):

docker exec -it net-gamma sh

Some steps are run from your ordinary host shell rather than inside a container — those are labelled with the third tag colour.

Part 1 — one network, and the resolver that comes with it

What this part tests: the baseline. Two containers on one user-defined bridge, checking the two questions separately — name resolution first, then reachability — so that when they come apart in Part 2 you know what “together” looked like.

ip -4 -o addr show eth0

cat /etc/resolv.conf

getent hosts net-beta
nslookup net-beta

ping -c 3 net-beta
wget -qO- http://net-beta/ | grep title

wget -O- -T 5 http://net-beta:9999/

docker network inspect net-blue \
  --format '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{println}}{{end}}'

Part 2 — the default bridge, where the two answers come apart

What this part tests: the claim in the mental model that name resolution and reachability are independent. The default bridge network is the cleanest proof, because it has no embedded DNS but perfectly ordinary connectivity — everything works except names.

docker run -d --name net-legacy1 nginx:alpine
docker run -d --name net-legacy2 nginx:alpine
docker exec net-legacy2 ip -4 -o addr show eth0

docker exec -it net-legacy1 sh

cat /etc/resolv.conf
getent hosts net-legacy2 ; echo "exit=$?"
ping -c 2 net-legacy2
nslookup net-legacy2

ping -c 3 172.17.0.10
wget -qO- http://172.17.0.10/ | grep title

Part 3 — a different network, where nothing works and the failure looks different

What this part tests: the actual isolation boundary. net-gamma is on net-green and shares no network with anything in net-blue. Both questions should now answer no — and per the mental model, the reason each fails should be legible in the shape of the failure.

grep nameserver /etc/resolv.conf
ip -4 -o addr show eth0
ip route

getent hosts net-alpha ; echo "exit=$?"
nslookup net-alpha

ping -c 3 -w 6 172.20.0.2
wget -O- http://172.20.0.2/

wget -O- -T 5 http://172.20.0.2/

Part 4 — attach a running container to a second network

What this part tests: that membership is live state, not something baked in at docker run time. Per the mental model — and per the Docker docs quoted in Provenance — user-defined bridges accept attach and detach on running containers. If the DNS zone really is just “the members of the networks I'm on”, a name should start resolving the instant membership changes, with no restart.

Do this one in the same Terminal B shell you opened in Setup. That the running shell's view changes underneath it, without the shell or the container restarting, is the point of the part.

echo "SESSION-PID=$$"
getent hosts net-beta ; echo "exit=$?"

docker inspect -f '{{.State.StartedAt}} pid={{.State.Pid}}' net-beta

docker network connect net-green net-beta

getent hosts net-beta ; echo "exit=$?"
echo "SESSION-PID-STILL=$$"
wget -qO- http://net-beta/ | grep title

getent hosts net-beta

docker exec net-beta ip -4 -o addr show

getent hosts net-alpha ; echo "exit=$?"
wget -O- -T 4 http://172.20.0.2/

docker network disconnect net-green net-beta

Part 5 — published ports have nothing to do with any of this

What this part tests: the most common misconception in the topic — that a container needs -p 8080:80 before another container can reach port 80. Everything above already disproves it (no -p anywhere), but it's worth watching the mapping actively fail to help.

docker run -d --name net-pub --network net-blue -p 39217:80 nginx:alpine
docker port net-pub
docker port net-alpha

wget -qO- http://net-pub/ | grep title
wget -O- -T 4 http://net-pub:39217/

wget -O- -T 4 http://net-pub/
wget -O- -T 4 http://172.20.0.4:39217/

wget -qO- http://host.docker.internal:39217/ | grep title

What you should see

On one user-defined network: nameserver 127.0.0.11 in /etc/resolv.conf, getent hosts net-beta → 172.20.0.3, and 0% packet loss. On the default bridge: no embedded resolver at all, ping: bad address 'net-legacy2' — and yet ping 172.17.0.10 at the same sub-millisecond latency, the two questions visibly diverging. Across two networks: an embedded resolver that is running and answers NXDOMAIN, and a wget that connects to nothing forever rather than being refused. Then docker network connect on a running container making its name resolve immediately — to 172.21.0.3 from one network and 172.20.0.3 from the other, same name, same instant, same container, container PID and even the asking shell's PID unchanged. And a published -p 39217:80 that is Connection refused from inside the container's own network.

Why

Docker's embedded DNS server is reachable at 127.0.0.11 inside a container's network namespace, and the records it serves are derived from exactly one thing: the set of endpoints on the networks that container is attached to. That's why the resolver can be present, healthy, and still return NXDOMAIN — it isn't broken, it's answering correctly for a zone that doesn't contain the name you asked for. It also explains the two different answers for net-beta in Part 4: the zone is built per network, so a container on two networks has two records, and each asker is told the address reachable from where it stands. And it explains why the default bridge has none of this — it predates the feature and is kept for compatibility, so containers there get a copy of the host's /etc/resolv.conf, whose nameserver has no idea what a container is.

The packet side is a separate mechanism with the same root cause. Each user-defined network is a Linux bridge, and a container's veth lands in exactly one bridge per network it joins. Traffic to another bridge's subnet does get routed — the container emits it, the gateway sees it — and is then dropped by Docker's DOCKER-ISOLATION-STAGE-1/-2 iptables chains, which exist for precisely this purpose. Dropped, not rejected, which is why you get a hang rather than a Connection refused. That distinction is the whole diagnostic value of Part 3.

Publishing a port is a third, unrelated mechanism: a DNAT rule in the host's nat table mapping a host port to a container's IP and port. It concerns the boundary between the host and the container world, and has nothing to say about traffic already inside that world. Ports are open between containers on a shared network by default; -p is how you let your laptop in, and nothing else.

Go deeper

• Network aliases. docker run -d --name net-delta --network net-blue --network-alias db --network-alias cache nginx:alpine, then from net-alpha ask for db, cache and net-delta:
  172.20.0.5 db db 172.20.0.5 cache cache 172.20.0.5 net-delta net-delta
  All three, one container. The alias is per network attachment, not per container, so the same container can be db on one network and something else on another. This is how blue/green cutovers work without touching client config: attach the new container under the alias, detach the old one.
• Total isolation. docker run -d --name net-solo --network none nginx:alpine, then docker exec net-solo ip -o addr show:
  1: lo inet 127.0.0.1/8 scope host lo\ valid_lft forever preferred_lft forever 1: lo inet6 ::1/128 scope host \ valid_lft forever preferred_lft forever
  Only lo. Reaching for a container IP gives an instant
  Connecting to 172.20.0.2 (172.20.0.2:80) wget: can't connect to remote host (172.20.0.2): Network unreachable
  — the fourth failure signature from the mental model, and a different one from Part 3's timeout: here the container's own kernel has no route and never puts a packet on any wire.
• Watch the drop happen. On a Linux host (not macOS), run sudo iptables -L DOCKER-ISOLATION-STAGE-2 -v -n while re-running Part 3's wget, and watch the DROP rule's packet counter tick up. That counter is the isolation boundary, in one number.
• --internal networks. docker network create --internal net-vault builds a bridge with no route to the outside. Compare a container there with one on net-blue:

  docker run --rm --network net-vault nginx:alpine ip route
  docker run --rm --network net-vault nginx:alpine wget -O- -T 5 http://example.com/

  172.22.0.0/16 dev eth0 scope link src 172.22.0.2
  wget: bad address 'example.com'
  Two things worth noticing. There is no default route at all — that single link-scope line is the entire routing table, versus the default via 172.21.0.1 you saw in Step 10. And the failure that surfaces first is a DNS failure, not a timeout: the embedded resolver is there, but it has no path to its upstream, so external names die before any packet is addressed. Skip DNS and the real shape appears — wget -O- -T 5 http://23.192.228.80/ gives wget: can't connect to remote host (23.192.228.80): Network unreachable, the same instant no-route signature as --network none. Meanwhile the same wget -qO- http://example.com/ from net-alpha returns the Example Domain page. This is the “database subnet” pattern done properly.
• What docker compose is doing. Bring up any compose project and run docker network ls — there's a <project>_default user-defined bridge. Everything in Parts 1 and 4 is what makes postgres:5432 resolve from your app container. Compose is a thin wrapper over exactly these commands.

Sources: Docker Docs: Bridge network driver — in particular the “differences between user-defined bridges and the default bridge” section, which lists the DNS behavior you just watched · Docker Docs: Networking overview for the other drivers

Cleanup

Remove only what this exercise created, by name:

docker rm -f net-alpha net-beta net-gamma net-pub net-legacy1 net-legacy2 net-delta net-solo
docker network rm net-blue net-green net-vault