Zum Inhalt

Runbook Netzwerk

Runbook: Netzwerk

Diagnose und Behebung von Netzwerkproblemen: HTTP-Fehler, TLS-Zertifikate, DNS und WebSocket.

502 Bad Gateway

Symptom: Browser zeigt 502 Bad Gateway.

Diagnose:

# Ingress-Controller Logs
kubectl logs -f deployment/inovetra-ingress-nginx-controller -n inovetra-platform

# Backend-Pod Status
kubectl get pods -n inovetra-platform

Ursachen:

  • Backend-Pod nicht bereit → Pod prüfen, siehe Runbook Pod-Fehler
  • Ingress-Controller überlastet → Ressourcen prüfen: 
    kubectl top pods -n inovetra-platform | grep ingress

Lösung: Backend-Pod neustarten oder zugrunde liegende Ursache beheben.

Verifikation:

curl -s -o /dev/null -w "%{http_code}" https://<domain>/api/customer/health

→ Erwartete Antwort: 200

503 Service Unavailable

Symptom: Service antwortet mit 503 Service Unavailable.

Diagnose:

# Wie bei 502, zusätzlich Readiness-Probe prüfen
kubectl describe pod <pod-name> -n inovetra-platform | grep -A5 "Readiness"
kubectl get endpoints -n inovetra-platform

Lösung:

kubectl rollout restart deployment/<name> -n inovetra-platform

Verifikation: Service antwortet mit 200.

TLS-Zertifikat abgelaufen

Symptom: Browser zeigt Zertifikatsfehler, NET::ERR_CERT_DATE_INVALID.

Diagnose:

kubectl get certificates -n inovetra-platform
kubectl describe certificate <name> -n inovetra-platform

Lösung (Let's Encrypt):

# Zertifikat löschen → cert-manager erstellt automatisch ein neues
kubectl delete certificate <name> -n inovetra-platform

# cert-manager Logs prüfen
kubectl logs -f deployment/cert-manager -n cert-manager

Lösung (eigenes Zertifikat): Siehe Wartung → Zertifikats-Erneuerung.

Verifikation:

echo | openssl s_client -connect <domain>:443 2>/dev/null | openssl x509 -noout -dates

→ notAfter muss in der Zukunft liegen.

DNS-Problem

Symptom: Domain ist nicht erreichbar.

Diagnose:

dig <domain>
nslookup <domain>

Lösung: DNS A-Record muss auf die öffentliche IP der VM zeigen. Beim DNS-Provider den Eintrag prüfen und ggf. korrigieren.

Verifikation:

dig <domain>

→ Zeigt die korrekte IP-Adresse.

WebSocket-Verbindungsfehler

Symptom: Chat funktioniert nicht, Echtzeit-Updates fehlen, Nachrichten werden nicht gestreamt.

Diagnose: Browser-Entwicklertools öffnen → Konsole auf WebSocket-Fehler prüfen (z.B. WebSocket connection failed).

Lösung: Ingress Controller prüfen — WebSocket-Support muss aktiviert sein (ist standardmäßig der Fall bei nginx-ingress). Falls deaktiviert:

kubectl get configmap inovetra-ingress-nginx-controller -n inovetra-platform -o yaml | grep proxy-read-timeout

Verifikation: Chat-Nachrichten werden in Echtzeit gestreamt.

TLS-Zertifikat: ACME Challenge schlägt fehl (502)

Symptom: Neues TLS-Zertifikat wird nicht ausgestellt. In den cert-manager Logs erscheinen 502-Fehler bei der ACME HTTP-01 Validierung.

Diagnose:

# Challenges prüfen
kubectl get challenges -n inovetra-platform

# cert-manager Logs
kubectl logs -f deployment/cert-manager -n cert-manager

# NetworkPolicies prüfen
kubectl get networkpolicy -n inovetra-platform | grep acme

Ursache: Die default-deny-ingress NetworkPolicy blockiert Ingress-Traffic zu den ACME HTTP-01 Solver-Pods auf Port 8089. Dieses Problem tritt auf Charts vor 0.72.6 auf.

Lösung:

  • Chart ≥ 0.72.6: Die allow-acme-solver NetworkPolicy ist automatisch enthalten. Prüfen, ob sie existiert: 
    kubectl get networkpolicy allow-acme-solver -n inovetra-platform
  • Chart < 0.72.6: Update auf ≥ 0.72.6 durchführen.

Verifikation:

kubectl get certificates -n inovetra-platform

→ Status True und gültiges Ablaufdatum.

Helm Install: "failed calling webhook"

Symptom: helm install oder helm upgrade schlägt bei der Erstinstallation mit failed calling webhook "webhook.cert-manager.io" fehl.

Diagnose:

# cert-manager Webhook-Pod Status prüfen
kubectl get pods -n cert-manager
kubectl describe pod -n cert-manager -l app.kubernetes.io/component=webhook

Ursache: Der cert-manager Webhook-Pod ist noch nicht bereit, wenn Helm versucht, den ClusterIssuer zu erstellen. Tritt häufig auf langsameren VMs auf.

Lösung:

# Auf Webhook-Readiness warten
kubectl wait --namespace cert-manager \
    --for=condition=ready pod \
    --selector=app.kubernetes.io/component=webhook \
    --timeout=120s

# Dann Helm erneut ausführen

Ab Chart 0.72.6 führt deploy-platform.sh diesen Wait-Schritt automatisch durch.

Verifikation: helm install / helm upgrade läuft ohne Webhook-Fehler durch.

NetworkPolicies unter K3s: Pod nicht erreichbar / DNS-Ausfälle

Symptom: Ein neuer Workload ist trotz READY 1/1 von anderen Pods nicht erreichbar (Connection refused), oder nach dem Anlegen zusätzlicher NetworkPolicies treten Readiness-Flaps und Portal-Aussetzer auf.

Hintergrund (K3s / kube-router): Auf K3s-Instanzen wird das Ingress-Enforcement der NetworkPolicies korrekt durchgesetzt (default-deny-ingress + Allow-Policy je Komponente). Das Egress-Enforcement ist de facto inert — Egress-Regeln haben keine schützende Wirkung.

Keine Egress-Policies an Plattform-Pods hängen

Niemals zusätzliche Egress-NetworkPolicies an Plattform-Pods anhängen: kube-router bricht dabei die DNS-Auflösung der Quell-Pods (Folge: Readiness-Flaps, Portal-Aussetzer — per A/B-Test verifiziert).

Diagnose:

# Bestehende NetworkPolicies prüfen
kubectl get networkpolicy -n inovetra-platform

# Erreichbarkeit aus einem anderen Pod testen (nicht nur READY-Status!)
kubectl exec -n inovetra-platform deploy/inovetra-customer-api -- \
    curl -s -o /dev/null -w "%{http_code}" http://<service>:<port>/

Ursache: Der Namespace hat eine default-deny-ingress-Policy. Neue Workloads brauchen daher eine eigene Ingress-Allow-Policy am Pod — sonst ist der Pod von anderen Pods aus nicht erreichbar.

Falle: kubelet-Probes sind gewhitelistet

Liveness-/Readiness-Probes des kubelet sind vom Default-Deny ausgenommen. Ein Pod kann also READY 1/1 melden, während Pod-zu-Pod-Verbindungen mit Connection refused scheitern. Der READY-Status ist kein Beleg für Erreichbarkeit.

Lösung: Für den neuen Workload eine Ingress-Allow-NetworkPolicy anlegen, die die zugreifenden Pods erlaubt. Keine Egress-Policies ergänzen.

Verifikation: Pod-zu-Pod-Test (siehe Diagnose) liefert den erwarteten HTTP-Code bzw. eine TCP-Verbindung.

LDAP: Zertifikats- und Bind-Fehler

Symptom: LDAP-Verbindungstest oder Login schlägt fehl.

Fehlermeldung Ursache und Lösung
unable to verify the first certificate Das DC-Zertifikat stammt von einer internen CA → CA-Zertifikat (PEM) im Customer Portal beim LDAP-Provider hinterlegen. LDAP-URL muss den FQDN enthalten (Hostname-Prüfung gegen Zertifikat-SAN). Siehe SSO-Einrichtung.
SASLprep error: ASCII control character present Unsichtbares Steuerzeichen (z. B. Tabulator) im Bind-Passwort — typisch beim Kopieren. Ab Chart 0.82.0 werden Steuerzeichen automatisch bereinigt; bei älteren Versionen den Wert von Hand neu eingeben.

Weiterführende Seiten