Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: Netzwerke

Ziel: Verstehen, wie Dienste sich per DNS finden, und den Stack in ein öffentliches frontend- und ein internes backend-Netz aufteilen. · Dauer: ca. 60 min · Voraussetzung: Tag 1

Briefing

  • Ohne Angabe hängt Compose alle Dienste in ein Netz <projekt>_default. Ein eingebauter DNS-Server (127.0.0.11) löst dort jeden Dienstnamen auf.
  • ports: veröffentlicht einen Port auf dem Mac. Container im selben Netz brauchen das nicht, sie erreichen jeden Port direkt.
  • Mehrere Netze trennen Zuständigkeiten: Wer kein Netz mit einem Dienst teilt, kann ihn weder auflösen noch erreichen.
  • internal: true schneidet ein Netz von außen ab: kein Internet, keine veröffentlichten Ports.
              Mac 127.0.0.1:3000          127.0.0.1:8080
                     │                          │
 notes_frontend ─────┼──────────────────────────┼───────────── (mit Internet)
                ┌────▼─────┐               ┌────▼─────┐
                │   web    │──── api ─────►│   api    │
                └──────────┘               └────▲─────┘
 notes_backend ─────────────────────────────────┼──────────── internal: true
                                           ┌────┴─────┐
                                           │  worker  │
                                           └──────────┘

Drill 1: Das Default-Netz

Tagesstart: Stand von Tag 1 übernehmen und starten.

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}}'

Erwartet (gekürzt, Adressen weichen bei dir ab):

 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

Ein Bridge-Netz mit eigenem Subnetz, alle drei Container darin. Die IP-Adressen vergibt Docker bei jedem Start neu – deshalb sprechen die Dienste sich nur über Namen an.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Service-Discovery per DNS

web bringt BusyBox mit nslookup mit:

docker compose exec web nslookup api
docker compose exec web nslookup notes-api-1
docker compose exec web nslookup notes-api

Erwartet (gekürzt):

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

Auflösbar sind der Dienstname api und der Containername notes-api-1. notes-api – der Standard im Code von worker und web – existiert nicht; deshalb setzt die compose.yaml NOTES_API_URL: http://api:8080. In Container ohne Werkzeuge (wie notes-api in scratch) schaust du mit einem Hilfscontainer im selben Netz:

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'

Erwartet (gekürzt):

172.20.0.2        api  api
ok
nameserver 127.0.0.11
options ndots:0

127.0.0.11 ist der DNS-Server von Docker in jedem benutzerdefinierten Netz. Er kennt die Namen im eigenen Netz und leitet alles andere an den DNS des Hosts weiter.

Fortschritt speichern? Kostenlos registrieren

Drill 3: ports und expose

docker compose port api 8080
docker compose port web 3000
docker compose port worker 8080; echo "Exit: $?"
docker compose ps --format '{{.Service}}: {{.Ports}}'

Erwartet:

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:
  • ports: braucht nur, wer vom Mac aus zugreift. worker hat keinen veröffentlichten Port und erreicht api trotzdem.
  • Im Netz gilt immer der Container-Port: web ruft api:8080, auch wenn du API_PORT=8081 setzt.
  • expose: veröffentlicht nichts. Laut Referenz beschreibt es nur Ports für andere Dienste; was das Dockerfile per EXPOSE deklariert, ist ohnehin sichtbar. Container im selben Netz erreichen jeden Port, auf dem ein Prozess lauscht.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Zwei Netze

Jetzt bekommt jeder Dienst nur die Netze, die er braucht:

cat > compose.yaml <<'EOF'
# compose.yaml – Stand Ende Tag 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}}'

Erwartet (gekürzt):

 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

Moment – notes_default gibt es noch. Kein Dienst benutzt es, aber Compose entfernt ein Netz nur, wenn es in der Datei steht. Auch down lässt es liegen. Weg damit:

docker network inspect notes_default --format '{{len .Containers}} Container'
docker network rm notes_default

Erwartet:

0 Container
notes_default

Tipp: docker network ls --filter label=com.docker.compose.project=notes findet solche Reste ebenfalls.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Wer sieht wen?

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}}'

Erwartet (gekürzt, Adressen weichen ab):

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
von  nach api web worker
web (frontend) ✔ – ✘ (nicht auflösbar)
worker (backend) ✔ ✘ –
Mac ✔ 8080 ✔ 3000 ✘

api hängt an beiden Netzen und hat in jedem eine eigene Adresse. web und worker teilen kein Netz und wissen nichts voneinander.

Fortschritt speichern? Kostenlos registrieren

Drill 6: internal – kein Weg nach draußen

Ein Hilfscontainer in jedem Netz, einmal ins Internet, einmal zu 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'
done

Erwartet:

== notes_frontend
Internet: ja
ok
== notes_backend
wget: bad address 'example.com'
Internet: nein
ok

Im internen Netz löst Docker nur die Namen der Nachbarn auf, externe Namen nicht. Der worker selbst merkt das genauso:

docker compose exec worker python -c \
  "import httpx; print(httpx.get('https://example.com', timeout=3).status_code)" \
  2>&1 | tail -1

Erwartet:

httpx.ConnectError: [Errno -3] Temporary failure in name resolution

Zweite Folge von internal: Ein Container nur in diesem Netz kann keine Ports veröffentlichen. Probe mit einem einzelnen 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-probe

Erwartet (gekürzt):

notes-probe Up 2 seconds (healthy) [8080/tcp]
curl Exit: 7
notes-probe

Kein Fehler beim Start, aber auch keine Weiterleitung: -p wird stillschweigend ignoriert. Deshalb hängt jeder Dienst mit ports: auch an frontend.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Netznamen und external

Compose setzt den Projektnamen vor jedes Netz. Mit name: legst du den echten Namen selbst fest, mit external: true benutzt Compose ein vorhandenes Netz, statt eines anzulegen. Probe mit --dry-run und einer Kopie der Datei:

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 -d

Erwartet:

 Network notes-shared Creating
network notes-shared declared as external, but could not be found

Ein externes Netz muss vorher existieren; Compose legt es nie an und löscht es nie. Typisch für Netze, die mehrere Projekte teilen, zum Beispiel einen gemeinsamen 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.yaml

Erwartet (gekürzt):

9cd5b9051dac…
 Container notes-worker-1 Running
 Container notes-api-1 Recreate
 Container notes-api-1 Recreated
notes-shared

api und web würden neu erstellt (anderes Netz), worker bliebe. Im Buch bleibt es bei den beiden projekteigenen Netzen; external taucht erst wieder in der Enterprise-Notiz auf.

Achtung: Ohne grep siehst du zusätzlich eine Warnung: Das bisherige Netz notes_frontend passe nicht mehr zur Datei und bleibe unangetastet. Wie in Drill 4 räumt Compose fremd gewordene Netze nicht selbst weg.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Der Stack mit der compose.yaml aus Drill 4 läuft. Die Netze:

cd ~/compose-lab/tag02
docker network ls --filter name=notes_ --format '{{.Name}} internal={{.Internal}}'

Erwartet: backend intern, frontend normal, kein notes_default mehr.

notes_backend internal=true
notes_frontend internal=false

web erreicht api:

docker compose exec web wget -qO- -T 2 http://api:8080/healthz; echo

Erwartet:

ok

web sieht worker nicht:

docker compose exec web nslookup worker

Erwartet (gekürzt):

Server:     127.0.0.11
Address:    127.0.0.11:53

** server can't find worker…: NXDOMAIN

worker erreicht api, aber nicht das 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 -1

Erwartet (gekürzt):

ok
httpx.ConnectError: [Errno -3] Temporary failure in name resolution

api ist veröffentlicht, ein POST über web klappt:

curl -s localhost:8080/healthz; echo
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Kontrollpunkt Tag 2"}'; echo

Erwartet (gekürzt, ID weicht ab):

ok
{"id":"30480990-…","text":"Kontrollpunkt Tag 2"}

Die vollständige Datei liegt in code/tag02/notes/compose.yaml.

Challenge

Der worker soll ohne NOTES_API_URL auskommen und den Code-Standard http://notes-api:8080 benutzen. Ändere dafür nichts am Code, nur die Netzkonfiguration von api – und zwar so, dass der Name notes-api nur im backend gilt, web ihn also nicht auflösen kann. Arbeite in einer Kopie compose.alias.yaml.

Hinweis: Die lange Form von networks: an einem Dienst kennt pro Netz aliases:.

Lösung

cp compose.yaml compose.alias.yaml

In compose.alias.yaml bei api die Netze in der langen Form schreiben und bei worker die Zeile NOTES_API_URL löschen:

  api:
    # … wie bisher
    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 -1

Erwartet (gekürzt, Adressen weichen ab):

 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

Aliase gelten pro Netz: Im backend heißt api zusätzlich notes-api, im frontend nicht. web bleibt unverändert und läuft weiter. Die ganze Datei: code/tag02/challenge/compose.alias.yaml. Zurück zum Stand des Tages:

docker compose up -d
rm compose.alias.yaml
docker compose down

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Netze sind die einfachste Segmentierung auf einem Docker-Host: Datenbanken und Worker gehören in ein internal-Netz, nur Proxy und API in ein Netz mit Ports.
  • internal blockiert auch Updates, Telemetrie und Lizenzprüfungen. Wer Ausgang braucht, bekommt ihn kontrolliert über einen Egress-Proxy, nicht über ein offenes Netz.
  • Gemeinsame Netze zwischen Projekten (external: true) sind ein Vertrag: Name, Subnetz und Besitzer gehören dokumentiert, sonst bricht ein docker network rm eines Teams die Dienste eines anderen.
  • Feste Subnetze (ipam.config.subnet) nur, wenn sie mit Firmen-VPN oder Docker-Hosts im selben Netz kollidieren; die Standardbereiche 172.16.0.0/12 überschneiden sich häufig mit Unternehmensnetzen.
  • In Kubernetes entsprechen Dienstnamen den Services und internal grob einer NetworkPolicy ohne Egress – das Denkmodell trägt weiter.