Day 2: Networks
Goal: Understand how services find each other via DNS, and split the stack into a public
frontendand an internalbackendnetwork. · Duration: approx. 60 min · Prerequisite: Day 1
Briefing
- If you specify nothing, Compose attaches all services to one network
<project>_default. A built-in DNS server (127.0.0.11) resolves every service name there. ports:publishes a port on the Mac. Containers in the same network don’t need that; they reach every port directly.- Multiple networks separate responsibilities: whoever doesn’t share a network with a service can neither resolve nor reach it.
internal: truecuts a network off from the outside: no internet, no published ports.
Mac 127.0.0.1:3000 127.0.0.1:8080
│ │
notes_frontend ─────┼──────────────────────────┼───────────── (with internet)
┌────▼─────┐ ┌────▼─────┐
│ web │──── api ─────►│ api │
└──────────┘ └────▲─────┘
notes_backend ─────────────────────────────────┼──────────── internal: true
┌────┴─────┐
│ worker │
└──────────┘
Drill 1: The default network
Start of the day: take over the state from Day 1 and start it.
source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag02 && cd ~/compose-lab/tag02
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag01/notes/." .
docker compose up -d
docker network inspect notes_default --format \
'{{.Name}} {{.Driver}} {{range .IPAM.Config}}{{.Subnet}} {{.Gateway}}{{end}}'
docker network inspect notes_default --format \
'{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'Expected (shortened, addresses differ on your machine):
Container notes-web-1 Started
Container notes-worker-1 Started
notes_default bridge 172.20.0.0/16 172.20.0.1
notes-worker-1 172.20.0.4/16
notes-web-1 172.20.0.3/16
notes-api-1 172.20.0.2/16
A bridge network with its own subnet, all three containers in it. Docker assigns the IP addresses anew on every start – that’s why the services address each other only by name.
Save your progress? Sign up for free
Drill 2: Service discovery via DNS
web ships BusyBox with nslookup:
docker compose exec web nslookup api
docker compose exec web nslookup notes-api-1
docker compose exec web nslookup notes-apiExpected (shortened):
Server: 127.0.0.11
Address: 127.0.0.11:53
Non-authoritative answer:
Name: api
Address: 172.20.0.2
…
Name: notes-api-1
Address: 172.20.0.2
…
** server can't find notes-api: NXDOMAIN
The service name api and the container name
notes-api-1 resolve. notes-api – the default
in the code of worker and web – does not exist; that’s why the
compose.yaml sets
NOTES_API_URL: http://api:8080. For containers without
tools (like notes-api in scratch), you look with a helper
container in the same network:
docker run --rm --label lab=compose-lab --network notes_default alpine:3.24 \
sh -c 'getent hosts api; wget -qO- http://api:8080/healthz; echo; \
grep -v "^#" /etc/resolv.conf'Expected (shortened):
172.20.0.2 api api
ok
nameserver 127.0.0.11
options ndots:0
127.0.0.11 is Docker’s DNS server in every user-defined
network. It knows the names in its own network and forwards everything
else to the host’s DNS.
Save your progress? Sign up for free
Drill 3: ports and expose
docker compose port api 8080
docker compose port web 3000
docker compose port worker 8080; echo "Exit: $?"
docker compose ps --format '{{.Service}}: {{.Ports}}'Expected:
127.0.0.1:8080
127.0.0.1:3000
no port 8080/tcp for container notes-worker-1:
Exit: 1
api: 127.0.0.1:8080->8080/tcp
web: 127.0.0.1:3000->3000/tcp
worker:
- Only those who access a service from the Mac need
ports:. worker has no published port and still reaches api. - Within the network, the container port always
applies: web calls
api:8080, even if you setAPI_PORT=8081. expose:publishes nothing. According to the reference, it only describes ports for other services; whatever the Dockerfile declares viaEXPOSEis visible anyway. Containers in the same network reach every port on which a process listens.
Save your progress? Sign up for free
Drill 4: Two networks
Now each service gets only the networks it needs:
cat > compose.yaml <<'EOF'
# compose.yaml – state at the end of Day 2
name: notes
services:
api:
build: notes-api
environment:
NOTES_API_KEY: ${NOTES_API_KEY}
ports:
- "127.0.0.1:${API_PORT:-8080}:8080"
networks: [frontend, backend]
worker:
build: notes-worker
environment:
NOTES_API_URL: http://api:8080
NOTES_API_KEY: ${NOTES_API_KEY}
depends_on:
- api
networks: [backend]
web:
build: notes-web
environment:
NOTES_API_URL: http://api:8080
NOTES_API_KEY: ${NOTES_API_KEY}
ports:
- "127.0.0.1:${WEB_PORT:-3000}:3000"
depends_on:
- api
networks: [frontend]
networks:
frontend: {}
backend:
internal: true
EOF
docker compose up -d
docker network ls --filter label=com.docker.compose.project=notes \
--format '{{.Name}} internal={{.Internal}}'Expected (shortened):
Network notes_backend Created
Network notes_frontend Created
Container notes-api-1 Recreated
Container notes-web-1 Recreated
Container notes-worker-1 Recreated
Container notes-api-1 Started
Container notes-worker-1 Started
Container notes-web-1 Started
notes_backend internal=true
notes_default internal=false
notes_frontend internal=false
Wait – notes_default is still there. No service uses it,
but Compose only removes a network if it is in the file.
down leaves it behind, too. Get rid of it:
docker network inspect notes_default --format '{{len .Containers}} Container'
docker network rm notes_defaultExpected:
0 Container
notes_default
Tip:
docker network ls --filter label=com.docker.compose.project=notesfinds such leftovers as well.
Save your progress? Sign up for free
Drill 5: Who sees whom?
docker compose exec web wget -qO- -T 2 http://api:8080/healthz; echo
docker compose exec web nslookup worker | tail -1
docker compose logs worker --tail 2
docker network inspect notes_frontend --format \
'{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'
docker network inspect notes_backend --format \
'{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'Expected (shortened, addresses differ):
ok
** server can't find worker: NXDOMAIN
worker-1 | worker started, api=http://api:8080, interval=10s
worker-1 | summary: 0 notes, 0 words
notes-api-1 172.22.0.2/16
notes-web-1 172.22.0.3/16
notes-api-1 172.21.0.2/16
notes-worker-1 172.21.0.3/16
| from to | api | web | worker |
|---|---|---|---|
| web (frontend) | ✔ | – | ✘ (cannot be resolved) |
| worker (backend) | ✔ | ✘ | – |
| Mac | ✔ 8080 | ✔ 3000 | ✘ |
api is attached to both networks and has its own address in each. web and worker share no network and know nothing about each other.
Save your progress? Sign up for free
Drill 6: internal – no way out
A helper container in each network, once to the internet, once to api:
for n in notes_frontend notes_backend; do
echo "== $n"
docker run --rm --label lab=compose-lab --network "$n" alpine:3.24 sh -c \
'wget -q -T 3 -O /dev/null https://example.com && echo "Internet: ja" \
|| echo "Internet: nein"; wget -qO- -T 2 http://api:8080/healthz; echo'
doneExpected:
== notes_frontend
Internet: ja
ok
== notes_backend
wget: bad address 'example.com'
Internet: nein
ok
In the internal network, Docker only resolves the names of the neighbors, not external names. The worker itself notices this the same way:
docker compose exec worker python -c \
"import httpx; print(httpx.get('https://example.com', timeout=3).status_code)" \
2>&1 | tail -1Expected:
httpx.ConnectError: [Errno -3] Temporary failure in name resolution
Second consequence of internal: a container
only in this network cannot publish ports. Test it with
a single notes-api container:
docker run -d --name notes-probe --label lab=compose-lab --network notes_backend \
-p 127.0.0.1:8088:8080 -e NOTES_API_KEY=lab-api-key-123 notes-api >/dev/null
sleep 2
docker ps --filter name=notes-probe --format '{{.Names}} {{.Status}} [{{.Ports}}]'
curl -s -m 3 localhost:8088/healthz; echo "curl Exit: $?"
docker rm -f notes-probeExpected (shortened):
notes-probe Up 2 seconds (healthy) [8080/tcp]
curl Exit: 7
notes-probe
No error at startup, but no forwarding either: -p is
silently ignored. That’s why every service with ports: is
also attached to frontend.
Save your progress? Sign up for free
Drill 7: Network names and external
Compose puts the project name in front of every network. With
name: you set the real name yourself; with
external: true, Compose uses an existing network instead of
creating one. Test it with --dry-run and a copy of the
file:
sed 's|^ frontend: {}| frontend:\n name: notes-shared|' compose.yaml > netz.yaml
docker compose -f netz.yaml --dry-run up -d 2>&1 | grep -m1 Network
sed 's|^ frontend: {}| frontend:\n name: notes-shared\n external: true|' \
compose.yaml > netz.yaml
docker compose -f netz.yaml up -dExpected:
Network notes-shared Creating
network notes-shared declared as external, but could not be found
An external network must exist beforehand; Compose never creates it and never deletes it. Typical for networks shared by several projects, for example a common reverse proxy:
docker network create --label lab=compose-lab notes-shared
docker compose -f netz.yaml --dry-run up -d 2>&1 | grep -E 'Container' | head -3
docker network rm notes-shared
rm netz.yamlExpected (shortened):
9cd5b9051dac…
Container notes-worker-1 Running
Container notes-api-1 Recreate
Container notes-api-1 Recreated
notes-shared
api and web would be recreated (different network), worker would
stay. In this book we stick with the two project-owned networks;
external only shows up again in the Enterprise Note.
Warning: Without
grepyou additionally see a warning: the previous networknotes_frontendno longer matches the file and is left untouched. As in Drill 4, Compose does not clean up networks that are no longer part of the file by itself.
Save your progress? Sign up for free
Checkpoint
The stack with the compose.yaml from Drill 4 is running.
The networks:
cd ~/compose-lab/tag02
docker network ls --filter name=notes_ --format '{{.Name}} internal={{.Internal}}'Expected: backend internal, frontend
normal, no notes_default anymore.
notes_backend internal=true
notes_frontend internal=false
web reaches api:
docker compose exec web wget -qO- -T 2 http://api:8080/healthz; echoExpected:
ok
web does not see worker:
docker compose exec web nslookup workerExpected (shortened):
Server: 127.0.0.11
Address: 127.0.0.11:53
** server can't find worker…: NXDOMAIN
worker reaches api, but not the internet:
docker compose exec worker python -c \
"import httpx; print(httpx.get('http://api:8080/healthz').text)"
docker compose exec worker python -c \
"import httpx; httpx.get('https://example.com', timeout=3)" 2>&1 | tail -1Expected (shortened):
ok
httpx.ConnectError: [Errno -3] Temporary failure in name resolution
api is published, a POST via web works:
curl -s localhost:8080/healthz; echo
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
-d '{"text":"Kontrollpunkt Tag 2"}'; echoExpected (shortened, ID differs):
ok
{"id":"30480990-…","text":"Kontrollpunkt Tag 2"}
The complete file is in
code/tag02/notes/compose.yaml.
Challenge
The worker should get by without
NOTES_API_URL and use the code default
http://notes-api:8080. Don’t change anything in the code
for this, only the network configuration of api – in such a way that the
name notes-api applies only in backend, so web
cannot resolve it. Work in a copy compose.alias.yaml.
Hint: The long form of networks: on a
service supports aliases: per network.
Solution
cp compose.yaml compose.alias.yamlIn compose.alias.yaml, write the networks of
api in the long form and delete the line
NOTES_API_URL from worker:
api:
# … as before
networks:
frontend: {}
backend:
aliases: [notes-api]
worker:
build: notes-worker
environment:
NOTES_API_KEY: ${NOTES_API_KEY}
depends_on:
- api
networks: [backend]docker compose -f compose.alias.yaml up -d
sleep 12
docker compose -f compose.alias.yaml logs worker | head -1
docker compose -f compose.alias.yaml logs worker --tail 1
docker compose -f compose.alias.yaml exec worker getent hosts notes-api
docker compose -f compose.alias.yaml exec web nslookup notes-api | tail -1Expected (shortened, addresses differ):
Container notes-web-1 Running
Container notes-api-1 Recreated
Container notes-worker-1 Recreated
worker-1 | worker started, api=http://notes-api:8080, interval=10s
worker-1 | summary: 0 notes, 0 words
172.20.0.2 notes-api
** server can't find notes-api: NXDOMAIN
Aliases apply per network: in backend, api is
additionally called notes-api, in frontend it
is not. web stays unchanged and keeps running. The whole file:
code/tag02/challenge/compose.alias.yaml. Back to the state
of the day:
docker compose up -d
rm compose.alias.yaml
docker compose downSave your progress? Sign up for free
Enterprise Note
- Networks are the simplest segmentation on a Docker host: databases
and workers belong in an
internalnetwork, only the proxy and API in a network with ports. internalalso blocks updates, telemetry and license checks. Whoever needs egress gets it in a controlled way through an egress proxy, not through an open network.- Shared networks between projects (
external: true) are a contract: name, subnet and owner must be documented, otherwise one team’sdocker network rmbreaks another team’s services. - Use fixed subnets (
ipam.config.subnet) only when they collide with the corporate VPN or Docker hosts in the same network; the default ranges172.16.0.0/12frequently overlap with corporate networks. - In Kubernetes, service names correspond to Services and
internalroughly to a NetworkPolicy without egress – the mental model carries over.