Ephemeral Containers: Live-Debugging in Kubernetes

TL;DR

Ephemeral Containers sind temporaere Container, die in laufende Pods injiziert werden -- ohne Restart, ohne neues Deployment. Mit kubectl debug lassen sich Debug-Tools in jeden Pod bringen, auch wenn das Image weder Shell noch Package Manager enthaelt. Besonders wertvoll fuer Distroless-Images und Production-Debugging, bei dem ein Pod-Neustart Datenverlust oder Service-Unterbrechung bedeuten wuerde.

Das Problem: Minimale Images haben keine Debug-Tools

Moderne Container-Images folgen dem Prinzip der minimalen Angriffsflaeche. Distroless-Images von Google, Alpine ohne Shell oder Scratch-basierte Go-Binaries enthalten weder curl noch ps noch netstat. Das ist gut fuer Security, aber ein Problem beim Debugging.

Der klassische Workaround -- ein neues Image mit Debug-Tools bauen und deployen -- kostet Zeit und veraendert die Umgebung. Der Fehler ist danach moeglicherweise nicht mehr reproduzierbar.

Ephemeral Containers loesen dieses Dilemma. Sie werden in den laufenden Pod injiziert, teilen sich den Network Namespace und koennen auf das Filesystem anderer Container zugreifen. Nach dem Debugging verschwinden sie automatisch.

# Pruefen ob Ephemeral Containers unterstuetzt werden (GA seit Kubernetes 1.25)
kubectl version --short

# Einen einfachen Debug-Container an einen laufenden Pod anhaengen
kubectl debug -it my-app-pod-7f8d9 --image=busybox:1.36 -- sh

kubectl debug: Die drei Modi

Modus 1: Container in laufenden Pod injizieren

Der haeufigste Anwendungsfall. Ein Debug-Container wird dem bestehenden Pod hinzugefuegt:

# Debug-Container mit Ubuntu-Image anhaengen
kubectl debug -it my-app-pod-7f8d9 \
  --image=ubuntu:24.04 \
  --target=my-app-container \
  -- bash

# Im Debug-Container: Prozesse des Ziel-Containers sehen
ps aux

# Filesystem des Ziel-Containers inspizieren
ls /proc/1/root/app/
cat /proc/1/root/app/config/application.yaml

Das --target Flag ist entscheidend: Es aktiviert Process Sharing mit dem angegebenen Container. Ohne dieses Flag sieht der Debug-Container nur seine eigenen Prozesse. Mit dem Flag teilen sich beide Container den PID-Namespace.

Modus 2: Pod-Kopie mit veraendertem Image

Wenn der Pod selbst das Problem ist oder ein Restart akzeptabel:

# Kopie des Pods mit Debug-Image statt dem Original
kubectl debug my-app-pod-7f8d9 -it \
  --copy-to=my-app-debug \
  --set-image=my-app-container=ubuntu:24.04 \
  -- bash

# Kopie mit zusaetzlichem Container statt ersetztem Image
kubectl debug my-app-pod-7f8d9 -it \
  --copy-to=my-app-debug \
  --image=busybox:1.36 \
  --share-processes \
  -- sh

Die Kopie erbt Labels, Annotations und Volumes des Original-Pods, laeuft aber als separater Pod.

Modus 3: Node-Debugging

Fuer Probleme auf Node-Ebene -- Dateisystem, Kernel-Module, Netzwerk-Interfaces:

# Debug-Shell auf einem Node starten
kubectl debug node/worker-node-03 -it --image=ubuntu:24.04

# Im Node-Debug-Container:
# Host-Filesystem ist unter /host gemountet
chroot /host
journalctl -u kubelet --since "10 minutes ago"
crictl ps
iptables -L -n -v

Distroless-Images debuggen

Distroless-Images sind der haeufigste Grund fuer Ephemeral Containers. Ein konkretes Beispiel mit einem Go-Service auf Scratch-Basis:

# Der Pod laeuft, aber der Health-Check schlaegt fehl
kubectl get pods
# NAME                      READY   STATUS    RESTARTS   AGE
# payment-api-5c8f7-xk2m   1/1     Running   0          3h

kubectl describe pod payment-api-5c8f7-xk2m | grep -A5 "Liveness"
# Liveness probe failed: connection refused

# Debug-Container mit curl und weiteren Tools anhaengen
kubectl debug -it payment-api-5c8f7-xk2m \
  --image=curlimages/curl:8.5.0 \
  --target=payment-api \
  -- sh

# Health-Endpoint lokal im Pod testen (gleicher Network Namespace)
curl -v http://localhost:8080/healthz
# Connection refused -- der Service bindet auf einem anderen Port

curl -v http://localhost:9090/healthz
# 200 OK -- der tatsaechliche Port

Das Problem: Die Liveness-Probe war auf Port 8080 konfiguriert, der Service lauscht aber auf 9090. Ohne Ephemeral Container waere die Diagnose nur durch Log-Analyse oder externes Port-Scanning moeglich gewesen.

Netzwerk-Debugging mit netshoot

Das Image nicolaka/netshoot ist das Schweizer Taschenmesser fuer Netzwerk-Debugging in Kubernetes. Es enthaelt unter anderem tcpdump, nmap, dig, nslookup, iperf3, mtr und strace.

# Netshoot-Container an einen Pod anhaengen
kubectl debug -it my-app-pod-7f8d9 \
  --image=nicolaka/netshoot \
  --target=my-app-container \
  -- bash

# DNS-Aufloesung pruefen
dig kubernetes.default.svc.cluster.local
nslookup postgres-primary.database.svc.cluster.local

# TCP-Verbindung zu einem Service testen
nc -zv postgres-primary.database 5432

# Live-Traffic mitschneiden
tcpdump -i eth0 -n port 8080 -c 50

# HTTP-Requests an den eigenen Pod analysieren
tcpdump -i eth0 -A -s 0 'tcp port 8080 and (((ip[2:2] - ((ip[0]&0xf)<\\\\\\\\\\\\\\\\\\\\\\\\\\\\\<2)) - ((tcp[12]&0xf0)>>2)) != 0)'

# Latenz zu einem anderen Service messen
mtr --report --report-cycles 10 redis-master.cache.svc.cluster.local

Praxisbeispiel: Intermittierende Verbindungsfehler

Ein Service meldet sporadisch Timeouts zur Datenbank. Die Logs zeigen nur "connection timeout". Mit netshoot laesst sich die Ursache eingrenzen:

kubectl debug -it order-service-6d9f8-abc12 \
  --image=nicolaka/netshoot \
  -- bash

# DNS-Antwortzeit messen
dig postgres-primary.database.svc.cluster.local | grep "Query time"
# Query time: 2 msec -- DNS ist nicht das Problem

# TCP-Verbindungsaufbau testen
time nc -zv postgres-primary.database 5432
# 0.003s -- Verbindung steht schnell

# Paket-Retransmissions zaehlen
ss -ti | grep retrans
# retrans:4/12 -- hier liegt das Problem

# Detaillierte Paketanalyse
tcpdump -i eth0 -n host 10.244.3.15 and port 5432 -w /tmp/capture.pcap &
sleep 30
kill %1

# Capture-Datei aus dem Pod kopieren (aus einem anderen Terminal)
kubectl cp order-service-6d9f8-abc12:/tmp/capture.pcap ./capture.pcap

Die hohe Retransmission-Rate deutet auf ein Netzwerk-Problem hin -- moeglicherweise eine ueberlastete Node-zu-Node-Verbindung oder ein fehlkonfiguriertes CNI-Plugin.

Mehr zu Netzwerk-Themen: Kubernetes CNI Vergleich.

Security-Ueberlegungen

Ephemeral Containers sind maechtig -- und muessen entsprechend abgesichert werden:

# RBAC: Debug-Berechtigung fuer SRE-Team
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pod-debugger
rules:
  - apiGroups: [""]
    resources: ["pods/ephemeralcontainers"]
    verbs: ["patch"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: sre-pod-debugger
subjects:
  - kind: Group
    name: sre-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: pod-debugger
  apiGroup: rbac.authorization.k8s.io

Kurzreferenz: Debug-Befehle

# Container in laufenden Pod injizieren
kubectl debug -it <pod> --image=<image> --target=<container> -- <command>

# Pod-Kopie mit anderem Image
kubectl debug <pod> -it --copy-to=<name> --set-image=<container>=<image>

# Node debuggen
kubectl debug node/<node> -it --image=ubuntu:24.04

# Aktive Ephemeral Containers anzeigen
kubectl get pod <pod> -o jsonpath='{.spec.ephemeralContainers[*].name}'

# Debug-Container-Logs lesen
kubectl logs <pod> -c <ephemeral-container-name>

Weitere Debugging-Methoden: Telepresence Kubernetes Debugging.

FAQ

Bleiben Ephemeral Containers nach dem Debugging bestehen?

Ephemeral Containers bleiben in der Pod-Spec sichtbar, bis der Pod geloescht wird. Der Container-Prozess selbst laeuft nur waehrend der Debug-Session. Ein laufender Ephemeral Container kann nicht entfernt werden -- er muss beendet werden (exit), und die Pod-Spec behaelt den Eintrag als historischen Record.

Funktionieren Ephemeral Containers mit Pod Security Standards?

Ja, aber der Debug-Container muss die gleichen Security-Einschraenkungen erfuellen wie regulaere Container im Pod. Bei restricted Pod Security Standards sind privilegierte Debug-Container nicht moeglich. In diesem Fall hilft der Copy-Modus mit angepassten Security-Kontexten.

Welches Debug-Image sollte ich verwenden?

Fuer Netzwerk-Debugging: nicolaka/netshoot. Fuer allgemeines Debugging: ubuntu:24.04 oder alpine:3.19. Fuer minimale HTTP-Tests: curlimages/curl. Idealerweise pflegt das Plattform-Team ein eigenes Debug-Image mit allen benoetigten Tools.

Kann ich Ephemeral Containers in Production verwenden?

Ja, das ist der primaere Anwendungsfall. Ephemeral Containers veraendern den laufenden Workload nicht -- sie fuegen nur einen temporaeren Container hinzu. RBAC-Regeln sollten den Zugriff auf Production-Namespaces auf On-Call-Engineers beschraenken.

Was ist der Unterschied zwischen kubectl debug und kubectl exec?

kubectl exec fuehrt einen Befehl in einem bestehenden Container aus -- der Container braucht die entsprechenden Tools. kubectl debug erstellt einen neuen Container mit eigenem Image, der die Tools mitbringt. Bei Distroless-Images ist kubectl exec nutzlos, weil keine Shell vorhanden ist.

Verwandte Artikel

• Telepresence Kubernetes Debugging
• CKA Troubleshooting Cluster-Probleme
• Kubernetes DNS Debugging CoreDNS
• Kubernetes Monitoring und Observability