Betriebshandbuch

Health Check

Der Health-Endpunkt prüft Datenbankverbindung, Teams-Adapter-Initialisierung und MCP-Server-Status. Docker- und Kubernetes-Healthchecks nutzen diesen Endpunkt — der Pod wird als ungesund markiert, wenn ein MCP-Server nicht verbunden ist.

curl -s http://localhost:3978/api/health | python3 -m json.tool

curl -s https://ihre-domain.example.com/api/health | python3 -m json.tool

Erwartete Antwort (alle Systeme betriebsbereit):

{
  "status": "ok",
  "adapter_initialized": true,
  "db": true,
  "mcp": {
    "release": { "connected": true, "tools": 38, "error": null },
    "jira": { "connected": true, "tools": 29, "error": null }
  }
}

Metriken & Monitoring

Reva stellt Metriken in zwei Formaten bereit. Für Metriken-Endpunkte ist keine Authentifizierung erforderlich.

Prometheus-Format

GET /api/metrics    # text/plain; version=0.0.4

Diesen Endpunkt mit Prometheus, Grafana Agent oder einem kompatiblen Collector scrapen. Wichtige Metriken:

JSON-Format

GET /api/stats      # application/json

Dieselben Daten als strukturiertes JSON — nützlich für Dashboards, Skripte oder Ad-hoc-Prüfungen.

Support-Bundle

Das Support-Bundle sammelt DSGVO-konforme Diagnosedaten für die Fernanalyse. Es ist für Kundeninstallationen konzipiert, bei denen X-idra keinen SSH-Zugang hat. Zwei Erfassungsmethoden stehen zur Verfügung: ein API-Endpunkt (wenn die Anwendung läuft) und ein Shell-Skript (wenn nicht).

Einrichtung

Setzen Sie ein Shared Secret, um den Support-Bundle-Endpunkt zu aktivieren:

REVA_SUPPORT_SECRET=ihr-secret-hier

docker compose up -d reva

kubectl patch configmap reva-env -n reva \
  --type merge -p '{"data":{"REVA_SUPPORT_SECRET":"ihr-secret-hier"}}'
kubectl rollout restart deployment/reva -n reva

API-Endpunkt (Anwendung läuft)

Diagnosedaten als JSON oder herunterladbares ZIP-Archiv abrufen:

# JSON-Antwort
curl -H "X-Support-Secret: $REVA_SUPPORT_SECRET" \
  https://ihre-domain.example.com/api/support-bundle

# ZIP-Archiv (eine Datei pro Abschnitt)
curl -H "X-Support-Secret: $REVA_SUPPORT_SECRET" \
  https://ihre-domain.example.com/api/support-bundle?format=zip \
  -o support-bundle.zip

Was wird erfasst?

Das Bundle führt 11 unabhängige Kollektoren aus. Wenn einer fehlschlägt, laufen die anderen weiter.

DSGVO-Bereinigung

Das Support-Bundle ist so konzipiert, dass es sicher über Organisationsgrenzen hinweg geteilt werden kann:

Offline-Shell-Skript (Anwendung läuft nicht)

Wenn die Anwendung nicht starten kann oder die API nicht erreichbar ist, verwenden Sie das Shell-Skript. Es erkennt automatisch, ob Docker Compose oder Kubernetes verwendet wird.

# Ohne API-Zugang (erfasst Systeminfo, Logs, Container-Status, DB-Statistiken)
./bin/support-bundle.sh

# Mit API-Zugang (zieht zusätzlich das vollständige API-Bundle)
REVA_SUPPORT_SECRET=ihr-secret ./bin/support-bundle.sh

Das Skript erzeugt ein support-bundle-YYYY-MM-DD-HHMMSS.tar.gz-Archiv im Projektverzeichnis mit:

• Systeminformationen (OS, Arbeitsspeicher, Festplatte, Docker-/K8s-Version)
• Container-/Pod-Status und Ressourcenverbrauch
• Anwendungslogs (letzte 1000 Zeilen)
• Health-Check-Antwort (wenn erreichbar)
• Konfiguration mit maskierten Secrets
• Datenbankstatistiken (Zeilenzählungen, Verbindungen, Größe)
• Vollständiges API-Bundle (wenn Secret angegeben und API erreichbar)
• GDPR_NOTICE.txt mit Dokumentation der Bereinigung

Datenbank-Backups

# Manuelles Backup
./bin/backup-db.sh

# Automatisches tägliches Backup (Crontab hinzufügen)
0 2 * * * /pfad/zu/reva/bin/backup-db.sh

# Automatisch: CronJob läuft täglich um 02:00 UTC
kubectl get cronjob db-backup -n reva

# Manuelles Backup
kubectl create job --from=cronjob/db-backup db-backup-manual -n reva

# Backup-Logs prüfen
kubectl logs -n reva job/db-backup-manual

Log-Verwaltung

# Reva-Logs folgen
docker compose logs -f reva

# Nach Fehlern suchen
docker compose logs reva | grep -i "error\|warning\|critical"

# Reva-Anwendung
kubectl logs -n reva -l app=reva -c reva -f

# MCP-Sidecars
kubectl logs -n reva -l app=reva -c release-mcp -f
kubectl logs -n reva -l app=reva -c jira-mcp -f

# Vorherige Pod-Logs (nach Absturz)
kubectl logs -n reva -l app=reva -c reva --previous

# Nach Fehlern suchen
kubectl logs -n reva -l app=reva -c reva | grep -i "error\|warning"

Updates & Rollback

# Version in .env aktualisieren
REVA_VERSION=1.0.5

# Neues Image laden und neustarten
docker compose pull reva
docker compose up -d reva

# Auf vorherige Version zurücksetzen
REVA_VERSION=1.0.4
docker compose up -d reva

# Neues Image bauen und importieren
docker build -t reva:latest .
docker save reva:latest | sudo k3s ctr images import -

# Deployment neustarten
kubectl rollout restart deployment/reva -n reva

# Rollout beobachten
kubectl rollout status deployment/reva -n reva

# Auf vorherige Version zurücksetzen
kubectl rollout undo deployment/reva -n reva

# Rollout-Verlauf anzeigen
kubectl rollout history deployment/reva -n reva