Zum Inhalt

Runbook Pod-Fehler

Runbook: Pod-Fehler

Diagnose und Behebung von Pod-Problemen: CrashLoopBackOff, OOMKilled, ImagePullBackOff und Pending.

CrashLoopBackOff

Symptom: Pod startet wiederholt neu, Status CrashLoopBackOff.

Diagnose:

kubectl describe pod <pod-name> -n inovetra-platform
kubectl logs <pod-name> -n inovetra-platform --previous

Häufige Ursachen & Lösungen:

  • Fehlende Umgebungsvariable/Secret → Secret prüfen: 
    kubectl get secret <name> -n inovetra-platform -o yaml
  • Datenbankverbindung fehlgeschlagen → Datenbank-Pod prüfen, siehe Runbook Datenbank
  • Fehlerhafte Konfiguration → Letzte Änderung prüfen, ggf. Rollback: 
    helm rollback ai-platform <rev> -n inovetra-platform

Verifikation:

kubectl get pods -n inovetra-platform

→ Status Running, keine Restarts.

OOMKilled

Symptom: Pod wird beendet mit Reason OOMKilled.

Diagnose:

kubectl describe pod <pod-name> -n inovetra-platform | grep -A5 "Last State"
kubectl top pods -n inovetra-platform

Lösung:

  • Memory Limit in Helm Values erhöhen (über Customer Portal → Einstellungen)
  • Typische Kandidaten mit hohem Speicherbedarf:
  • LiteLLM: Standard 12Gi
  • RAG API: Standard 6Gi
  • Embedding Service: Standard 12Gi
  • Bei wiederkehrendem OOM: VM-RAM erhöhen, siehe Kapazitätsplanung

Verifikation: Pod läuft stabil, kein erneuter OOMKill in kubectl describe pod.

ImagePullBackOff

Symptom: Pod bleibt in ImagePullBackOff oder ErrImagePull.

Diagnose:

kubectl describe pod <pod-name> -n inovetra-platform | grep -A10 "Events"

Häufige Ursachen:

  • GitHub PAT abgelaufen → Neuen PAT erstellen (Scope read:packages), im Customer Portal unter Einstellungen aktualisieren
  • Image-Tag existiert nicht → Verfügbare Tags in GitHub Packages prüfen
  • Netzwerkproblem → Erreichbarkeit testen: 
    curl -s https://ghcr.io/v2/

Lösung:

# imagePullSecrets prüfen
kubectl get secret inovetra-ghcr-secret -n inovetra-platform -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d

Verifikation: Pod wechselt zu Running.

Pending

Symptom: Pod bleibt dauerhaft im Status Pending.

Diagnose:

kubectl describe pod <pod-name> -n inovetra-platform | grep -A5 "Conditions"
kubectl describe node

Ursachen:

  • Unzureichende Ressourcen → kubectl describe node prüfen (Allocatable vs. Allocated)
  • PVC kann nicht gebunden werden → PVC-Status prüfen: 
    kubectl get pvc -n inovetra-platform
  • LiteLLM nach Update → Vor Chart 0.72.5 nutzte LiteLLM RollingUpdate. Bei Single-Node-VMs (32GB RAM) konnte der neue Pod (8Gi Memory Request) nicht neben dem alten Pod gestartet werden. Lösung: Update auf Chart ≥ 0.72.5 (nutzt Recreate-Strategie — alter Pod wird zuerst gelöscht, ~5s Downtime).

Lösung: Je nach Ursache VM-Ressourcen erhöhen oder Storage bereitstellen.

Verifikation: Pod wechselt zu Running.

Pod neu starten

# Einzelnes Deployment neustarten
kubectl rollout restart deployment/<name> -n inovetra-platform

# StatefulSet neustarten (z.B. MongoDB)
kubectl rollout restart statefulset/<name> -n inovetra-platform

RAG API: ContextWindowExceededError

Symptom: RAG-Antworten schlagen mit ContextWindowExceededError fehl. In den RAG-API-Logs erscheint ein Fehler von IONOS/LiteLLM über überschrittenes Kontextfenster.

Diagnose:

kubectl logs deployment/inovetra-rag-api -n inovetra-platform | grep -i "context overflow\|ContextWindow"

Ursachen:

  • Korrupte Mega-Chunks in Qdrant — Einzelne Chunks mit extrem viel Text (z.B. durch fehlerhafte Ingestion)
  • Sehr lange Konversationshistorie — Kombination aus vielen Nachrichten + umfangreichen Dokumenten

Lösung (ab RAG API v0.47.0):

Die RAG API erkennt Context Overflows automatisch und fasst den Dokumentenkontext mit dem schnellen 8b-Modell zusammen. In den Logs erscheint:

[RAG-v2] Context overflow: ~425000 tokens (limit 131072) — summarizing

Bei Bedarf kann das Limit über MODEL_CONTEXT_LIMIT (Standard: 131072) angepasst werden.

Bei Versionen < v0.47.0: Update auf RAG API ≥ v0.47.0 (Helm Chart ≥ 0.72.5).

KI-Modellanbieter Mistral: keine Antworten (ab 0.79.7)

Symptom: Nach dem Umschalten des KI-Modellanbieters auf Mistral (Customer Portal → KI-Einstellungen) liefern Inovetra RAG und Inovetra AI keine Antworten; in den RAG-API- oder LibreChat-Logs erscheinen Fehler zu mistral-large / mistral-small.

Ursache: Die Mistral-Modelle sind im zentralen LiteLLM (llm.inovetra.ai) nicht konfiguriert oder der MISTRAL_API_KEY fehlt bzw. ist ungültig. Lokale K8s-LiteLLM-Configs routen Mistral ausschließlich über den zentralen Proxy.

Lösung: Auf der Management-VM sicherstellen, dass mistral-large (mistral/mistral-large-latest) und mistral-small (mistral/mistral-small-latest) im zentralen LiteLLM konfiguriert sind und ein gültiger MISTRAL_API_KEY in der .env gesetzt sowie im environment:-Block des Compose-Service litellm durchgereicht wird. Anschließend centralLlmProxy.enabled=true der Kunden-Instanz prüfen. Details siehe LLM-Modelle.

Automatischer Neustart

Das Umschalten des Anbieters startet RAG API und LibreChat-Pods automatisch neu — ein manuelles kubectl rollout restart ist nicht erforderlich.

Weiterführende Seiten