Docker-Netzwerk debuggen mit temporären Hilfs-Containern

Ein temporärer Debug-Container im selben Netzwerk ist die schnellste Methode um Netzwerkprobleme zwischen Containern zu diagnostizieren.

Das Prinzip

Statt Tools in den Ziel-Container zu installieren oder die Anwendung zu verändern, startet man einen dedizierten Debug-Container im selben Docker-Netzwerk. Nach der Diagnose verschwindet er rückstandslos (--rm).

# Netzwerkname herausfinden
docker inspect ZIELCONTAINER --format '{{json .NetworkSettings.Networks}}' | python3 -m json.tool

# Debug-Container im selben Netzwerk starten
docker run --rm -it --network NETZWERKNAME nicolaka/netshoot

netshoot — das vollständige Diagnose-Toolkit

nicolaka/netshoot ist das empfohlene Debug-Image für Docker-Netzwerkprobleme. Es enthält:

• curl, wget — HTTP-Tests
• dig, nslookup — DNS-Diagnose
• nmap — Port-Scanner
• tcpdump — Paket-Capture
• iperf3 — Bandbreiten-Test
• ss, netstat — Socket-Status
• ping, traceroute, mtr — Konnektivität
• tshark — Wireshark CLI

# Direkt starten mit Netzwerk des Ziel-Containers
docker run --rm -it --network container:ZIELCONTAINER nicolaka/netshoot

Typische Diagnose-Szenarien

HTTP-Verbindung testen

# Im netshoot-Container:
curl -v http://myservice:3000
curl -v http://myservice:3000/health

# Mit Timeout
curl --connect-timeout 5 http://myservice:3000

DNS-Auflösung prüfen

# Kann myservice aufgelöst werden?
dig myservice
nslookup myservice

# Mit explizitem DNS-Server
dig @127.0.0.11 myservice   # 127.0.0.11 ist Dockers interner DNS

Welche Ports sind offen?

nmap -p 1-65535 myservice
# Schneller: nur häufige Ports
nmap myservice

Paket-Capture

# Alle HTTP-Pakete mitschneiden
tcpdump -i eth0 -A 'port 80 or port 3000'

# Nur zwischen zwei Hosts
tcpdump -i eth0 host myservice

Bandbreite messen

# Auf dem Ziel-Container oder -Service: iperf3 -s
# Im netshoot:
iperf3 -c myservice -p 5201

Alpine als leichter Debug-Container

Für einfachere Tests reicht Alpine:

docker run --rm -it --network NETZWERKNAME alpine sh
apk add --no-cache curl bind-tools
curl http://myservice:3000
nslookup myservice

Compose-Netzwerkname ermitteln

# Compose-Netzwerke folgen dem Schema: PROJECTNAME_NETWORKNAME
docker network ls | grep myproject

# Alle Container in einem Netzwerk
docker network inspect myproject_default --format '{{range .Containers}}{{.Name}} {{end}}'

# Debug-Container im Compose-Standardnetzwerk
docker run --rm -it --network myproject_default nicolaka/netshoot

Ohne netshoot: Minimalvariante

# On-the-fly mit Alpine und Installation
docker run --rm -it \
  --network NETZWERKNAME \
  alpine sh -c "apk add -q curl && curl http://myservice:3000"

Fazit: Kein Aufräumen nötig

Das --rm-Flag entfernt den Container automatisch nach dem Beenden. Kein Stop, kein docker rm, keine Spuren im docker ps -a. Temporäre Debug-Container sind deshalb die sauberste Diagnosemethode — sie verändern weder das Ziel-Image noch den laufenden Container.

Zusammenfassung

| Tool | Befehl | Einsatz |
|------|--------|---------|
| netshoot | docker run --rm -it --network NET nicolaka/netshoot | Vollständige Netzwerkdiagnose |
| busybox | docker run --rm -it --network NET busybox sh | Einfache Tests |
| alpine | docker run --rm -it --network NET alpine sh | Mit apk-Install |
| nsenter | sudo nsenter -t PID -n sh | Host-Level, kein Extra-Container |