Veröffentlicht am

Kubernetes Ingress 502, 503, 504 Fehler beheben

Teilen:
Authors

Kubernetes Ingress 502, 503, 504 Errors: Gateway Troubleshooting Guide

TL;DR

  • 502 Bad Gateway: Der Ingress Controller erreicht das Backend nicht -- Pod gecrasht, falscher Port oder Service-Selector stimmt nicht.
  • 503 Service Unavailable: Kein einziger Endpoint verfuegbar -- Deployment skaliert auf 0, Readiness Probe schlaegt fehl oder Label-Mismatch.
  • 504 Gateway Timeout: Backend antwortet zu langsam -- Timeout-Annotations erhoehen oder Backend-Performance optimieren.
  • Debugging-Reihenfolge: Endpoints pruefen, Ingress-Controller-Logs lesen, Annotations validieren.
  • Nginx Ingress Controller ist der haeufigste -- die meisten Beispiele hier beziehen sich darauf.

Ingress-Fehler: Was passiert eigentlich?

Ein Kubernetes Ingress leitet externen Traffic an Services weiter. Zwischen dem Client und Ihrem Pod liegen mindestens drei Komponenten: der Ingress Controller (meist Nginx), der Kubernetes Service und die Pods dahinter. Jede dieser Schichten kann Fehler verursachen.

Die HTTP-Statuscodes 502, 503 und 504 kommen dabei nicht von Ihrer Anwendung, sondern vom Ingress Controller selbst. Er meldet damit, dass er das Backend nicht erreichen kann oder keine Antwort bekommt.

Client */} Ingress Controller */} Service */} Endpoints */} Pod
              502/503/504
              kommen von hier

502 Bad Gateway: Backend nicht erreichbar

Was 502 bedeutet

Der Ingress Controller hat versucht, die Anfrage an das Backend weiterzuleiten, aber die Verbindung ist fehlgeschlagen. Das Backend hat die Verbindung abgelehnt, geschlossen oder eine ungueltige Antwort gesendet.

Die haeufigsten Ursachen

1. Pod ist gecrasht oder startet gerade neu

# Pruefen, ob Pods laufen
kubectl get pods -l app=my-backend -n production

# Typische Ausgabe bei Problem:
# NAME                       READY   STATUS             RESTARTS   AGE
# my-backend-5d4f8b-x9k2l   0/1     CrashLoopBackOff   5          8m

Wenn der Pod in CrashLoopBackOff ist, hilft kein Ingress-Tuning. Beheben Sie zuerst den Pod-Crash.

2. Falscher containerPort oder Service-Port

Ein klassischer Fehler: Der Service zeigt auf Port 80, aber der Container lauscht auf Port 8080.

# Service-Konfiguration pruefen
kubectl get svc my-backend -n production -o yaml

apiVersion: v1
kind: Service
metadata:
  name: my-backend
spec:
  selector:
    app: my-backend
  ports:
    - protocol: TCP
      port: 80          # Service-Port (hier kommt der Ingress an)
      targetPort: 8080   # Container-Port (muss zum Pod passen!)

Vergleichen Sie den targetPort mit dem containerPort im Deployment:

kubectl get deployment my-backend -n production -o jsonpath='{.spec.template.spec.containers[0].ports[0].containerPort}'
# Muss 8080 ergeben

3. Backend sendet ungueltige HTTP-Antwort

Wenn Ihr Backend gRPC, WebSocket oder ein anderes Protokoll spricht, muss der Ingress Controller das wissen:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-backend-ingress
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-backend
                port:
                  number: 50051

502 Debugging-Workflow

# 1. Endpoints pruefen -- gibt es ueberhaupt Backend-Pods?
kubectl get endpoints my-backend -n production

# Erwartete Ausgabe: mindestens eine IP:Port Kombination
# NAME         ENDPOINTS                         AGE
# my-backend   10.244.1.5:8080,10.244.2.3:8080   5d

# 2. Direkt zum Pod verbinden (umgeht Ingress)
kubectl port-forward svc/my-backend 8080:80 -n production
# Dann in einem zweiten Terminal:
curl http://localhost:8080/health

# 3. Ingress-Controller-Logs pruefen
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx --tail=50

In den Nginx-Ingress-Logs sehen Sie bei 502 typischerweise:

upstream prematurely closed connection while reading response header from upstream

oder:

connect() failed (111: Connection refused) while connecting to upstream

503 Service Unavailable: Keine Endpoints

Was 503 bedeutet

Der Ingress Controller kennt den Service, aber es gibt keinen einzigen verfuegbaren Endpoint. Das heisst: Kein Pod ist bereit, Traffic zu empfangen.

Die haeufigsten Ursachen

1. Label-Mismatch zwischen Service und Deployment

Der haeufigste Grund fuer 503 Errors. Der Service-Selector findet keine Pods, weil die Labels nicht uebereinstimmen.

# Service-Selector anzeigen
kubectl get svc my-backend -n production -o jsonpath='{.spec.selector}'
# Ausgabe: {"app":"my-backend"}

# Pods mit diesem Label suchen
kubectl get pods -l app=my-backend -n production
# Wenn hier "No resources found" steht, stimmt der Selector nicht

# Alle Labels der Pods anzeigen
kubectl get pods -n production --show-labels | grep backend

2. Readiness Probe schlaegt fehl

Pods laufen, aber die Readiness Probe meldet "nicht bereit". Kubernetes entfernt diese Pods aus den Endpoints.

# Pod-Status pruefen
kubectl describe pod my-backend-5d4f8b-x9k2l -n production | grep -A 10 "Readiness"

# Typische Readiness-Probe-Konfiguration
readinessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 3

Wenn der Health-Endpoint /health nicht existiert oder einen Fehler zurueckgibt, bleibt der Pod dauerhaft "not ready":

# Readiness manuell testen
kubectl exec my-backend-5d4f8b-x9k2l -n production -- curl -s http://localhost:8080/health

Mehr zu Health-Check-Konfiguration finden Sie im Artikel zu Liveness und Readiness Probes.

3. Deployment auf 0 Replicas skaliert

Manchmal trivial, aber leicht zu uebersehen:

kubectl get deployment my-backend -n production
# NAME         READY   UP-TO-DATE   AVAILABLE   AGE
# my-backend   0/0     0            0           5d

Passiert haeufig durch versehentliches kubectl scale oder einen Autoscaler, der auf 0 skaliert hat.

4. Namespace-Mismatch

Der Ingress verweist auf einen Service in einem anderen Namespace. In Kubernetes sind Services namespace-spezifisch.

# Falsch: Service existiert nicht in diesem Namespace
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  namespace: default      # Ingress ist in 'default'
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-backend   # Service muss auch in 'default' sein!
                port:
                  number: 80

503 Debugging-Workflow

# 1. Endpoints pruefen (leer = Problem)
kubectl get endpoints my-backend -n production
# NAME         ENDPOINTS   AGE
# my-backend               5d    <-- LEER! Keine Endpoints

# 2. Service-Selector mit Pod-Labels vergleichen
kubectl get svc my-backend -n production -o jsonpath='{.spec.selector}' && echo
kubectl get pods -n production --show-labels

# 3. Pod-Readiness pruefen
kubectl get pods -n production -l app=my-backend -o wide
# Spalte READY muss "1/1" zeigen

504 Gateway Timeout: Backend zu langsam

Was 504 bedeutet

Der Ingress Controller hat die Anfrage ans Backend weitergeleitet, aber innerhalb des konfigurierten Timeouts keine Antwort bekommen. Der Standard-Timeout bei Nginx Ingress ist 60 Sekunden.

Die haeufigsten Ursachen

1. Backend braucht zu lange

Aufwendige Datenbankabfragen, externe API-Aufrufe oder rechenintensive Operationen koennen dazu fuehren, dass das Backend laenger als 60 Sekunden braucht.

# Direkt zum Backend verbinden und Antwortzeit messen
kubectl exec -it debug-pod -n production -- curl -w "\nTotal: %{time_total}s\n" -o /dev/null -s http://my-backend:80/slow-endpoint

2. Timeout-Annotations zu niedrig

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-backend-ingress
  annotations:
    # Timeout fuer das Senden der Anfrage ans Backend
    nginx.ingress.kubernetes.io/proxy-send-timeout: "120"
    # Timeout fuer das Lesen der Antwort vom Backend
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
    # Timeout fuer die Verbindung zum Backend
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-backend
                port:
                  number: 80

Fuer Long-Running-Requests (z.B. Datei-Uploads, Report-Generierung) muessen Sie die Timeouts entsprechend erhoehen.

3. Keepalive-Probleme

Wenn das Backend Verbindungen schliesst, bevor der Ingress Controller es erwartet, koennen Timeouts entstehen:

annotations:
  nginx.ingress.kubernetes.io/upstream-keepalive-connections: "32"
  nginx.ingress.kubernetes.io/upstream-keepalive-timeout: "60"

4. Resource-Limits zu niedrig (CPU Throttling)

Wenn das Backend CPU-throttled wird, antwortet es langsamer. Das kann zu 504-Fehlern fuehren. Pruefen Sie die Performance Ihres Clusters und die Resource-Limits der Backend-Pods.

# CPU-Throttling pruefen
kubectl top pods -n production -l app=my-backend

504 Debugging-Workflow

# 1. Aktuelle Timeout-Konfiguration pruefen
kubectl get ingress my-backend-ingress -n production -o yaml | grep -A 5 annotations

# 2. Backend-Antwortzeit messen
kubectl run debug-curl --image=curlimages/curl --rm -it --restart=Never -- \
  curl -w "Connect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s http://my-backend.production.svc.cluster.local:80/

# 3. Ingress-Controller-Logs auf Timeout-Meldungen pruefen
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx --tail=100 | grep "504\|upstream timed out"

Ingress-Controller-Logs richtig lesen

Die Logs des Ingress Controllers sind die wichtigste Informationsquelle. So aktivieren Sie detailliertere Logs:

# Log-Level erhoehen (temporaer)
kubectl exec -it $(kubectl get pods -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx -o name | head -1) \
  -n ingress-nginx -- /nginx-ingress-controller --v=3

Fuer dauerhafte Aenderungen passen Sie das Helm-Chart an:

# values.yaml fuer Nginx Ingress Helm Chart
controller:
  config:
    # Detaillierte Access-Logs mit Upstream-Infos
    log-format-upstream: '$remote_addr - $request_id [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id'

Die wichtigsten Felder in den Logs:

FeldBedeutung
$upstream_statusHTTP-Status vom Backend (leer = keine Verbindung)
$upstream_response_timeAntwortzeit des Backends in Sekunden
$upstream_addrIP:Port des Backends, an das weitergeleitet wurde
$statusHTTP-Status, den der Client bekommt

Health Checks fuer den Ingress Controller selbst

Nicht nur Ihre Backends brauchen Health Checks. Pruefen Sie auch den Ingress Controller:

# Ingress-Controller-Health pruefen
kubectl get pods -n ingress-nginx
kubectl top pods -n ingress-nginx

# Ingress-Controller-Konfiguration validieren
kubectl exec -it $(kubectl get pods -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx -o name | head -1) \
  -n ingress-nginx -- cat /etc/nginx/nginx.conf | grep upstream -A 10

Wenn der Ingress Controller selbst ueberlastet ist (zu viele Connections, zu wenig CPU/Memory), kann er ebenfalls 502/503-Fehler werfen:

# Resource Limits fuer den Ingress Controller
controller:
  resources:
    requests:
      cpu: 200m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 512Mi
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5
    targetCPUUtilizationPercentage: 70

Annotations-Referenz: Die wichtigsten Nginx-Ingress-Settings

annotations:
  # Timeouts
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "60"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "60"

  # Body Size (wichtig fuer Uploads)
  nginx.ingress.kubernetes.io/proxy-body-size: "50m"

  # Retry-Verhalten
  nginx.ingress.kubernetes.io/proxy-next-upstream: "error timeout"
  nginx.ingress.kubernetes.io/proxy-next-upstream-tries: "3"

  # Rate Limiting
  nginx.ingress.kubernetes.io/limit-rps: "50"

  # SSL-Redirect
  nginx.ingress.kubernetes.io/ssl-redirect: "true"

  # Custom Error Pages
  nginx.ingress.kubernetes.io/custom-http-errors: "502,503,504"
  nginx.ingress.kubernetes.io/default-backend: error-pages

Checkliste: Ingress Troubleshooting in 5 Minuten

Verwenden Sie diese Checkliste, wenn ein Ingress-Fehler auftritt:

# Schritt 1: Welcher Fehlercode?
curl -I https://app.example.com

# Schritt 2: Ingress-Objekt pruefen
kubectl get ingress -n production
kubectl describe ingress my-ingress -n production

# Schritt 3: Service und Endpoints pruefen
kubectl get svc -n production
kubectl get endpoints -n production

# Schritt 4: Pod-Status pruefen
kubectl get pods -n production -l app=my-backend

# Schritt 5: Ingress-Controller-Logs
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx --tail=50

# Schritt 6: Direkte Verbindung zum Backend testen
kubectl port-forward svc/my-backend -n production 8080:80

Wenn der Fehler bei der direkten Verbindung (Schritt 6) auch auftritt, liegt das Problem im Backend. Wenn er nur ueber den Ingress auftritt, liegt es an der Ingress-Konfiguration.

Praeventive Massnahmen

Um Ingress-Fehler von vornherein zu vermeiden:

  1. Readiness Probes richtig konfigurieren: Nur Pods, die tatsaechlich bereit sind, sollten Traffic bekommen.
  2. PodDisruptionBudgets setzen: Verhindern, dass zu viele Pods gleichzeitig weg sind.
  3. Graceful Shutdown implementieren: Ihre Anwendung sollte laufende Requests vor dem Beenden abschliessen.
  4. Monitoring einrichten: Alerting auf 5xx-Raten am Ingress, bevor Nutzer sich beschweren.
# PodDisruptionBudget
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: my-backend-pdb
  namespace: production
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: my-backend

Fuer umfassendes Monitoring empfehlen wir den Artikel zu Kubernetes Monitoring und Observability.

Verwandte Artikel

Haben Sie wiederkehrende Ingress-Probleme oder komplexe Routing-Anforderungen? Unser Team unterstuetzt Sie beim Debugging und der Optimierung Ihrer Kubernetes-Netzwerkinfrastruktur. Kontaktieren Sie uns fuer eine kostenlose Erstberatung.

Diskutieren auf Twitter

Kubernetes-Beratung gesucht?

Wir helfen deutschen Unternehmen bei der Kubernetes-Implementierung, Migration und Optimierung. DSGVO-konform und praxiserprobt.

Termin buchenKontakt aufnehmen

📖 Verwandte Artikel

Weitere interessante Beiträge zu ähnlichen Themen

Alle Artikel durchsuchen