pjt222/write-incident-runbook

Incident-Runbook erstellen

Handlungsorientierte Runbooks erstellen, die Responder durch Incident-Diagnose und -Loesung fuehren.

Wann verwenden

• Reaktionsverfahren fuer wiederkehrende Alerts oder Incidents dokumentieren
• Incident-Reaktion innerhalb der On-Call-Rotation standardisieren
• Mean Time to Resolution (MTTR) mit klaren Diagnoseschritten reduzieren
• Schulungsmaterialien fuer neue Teammitglieder zur Incident-Behandlung erstellen
• Eskalationspfade und Kommunikationsprotokolle etablieren
• Stammeswissen in schriftliche Dokumentation uebertragen
• Alerts mit Loesungsverfahren verknuepfen (Alert-Annotationen)

Eingaben

• Pflichtfeld: Incident- oder Alert-Name/-Beschreibung
• Pflichtfeld: Historische Incident-Daten und Loesungsmuster
• Optional: Diagnoseabfragen (Prometheus, Logs, Traces)
• Optional: Eskalationskontakte und Kommunikationskanaele
• Optional: Fruehereincident-Post-Mortems

Vorgehensweise

Schritt 1: Runbook-Template-Struktur auswaehlen

Unter Extended Examples sind vollstaendige Template-Dateien verfuegbar.

Ein passendes Template basierend auf Incident-Typ und Komplexitaet auswaehlen.

Grundlegende Runbook-Template-Struktur:

# [Alert/Incident Name] Runbook
## Overview | Severity | Symptoms
## Diagnostic Steps | Resolution Steps
## Escalation | Communication | Prevention | Related

Erweitertes SRE-Runbook-Template (Auszug):

# [Service Name] - [Incident Type] Runbook

## Metadata
- Service, Owner, Severity, On-Call, Last Updated

## Diagnostic Phase
### Quick Health Check (< 5 min): Dashboard, error rate, deployments
### Detailed Investigation (5-20 min): Metrics, logs, traces, failure patterns
# ... (see EXAMPLES.md for complete template)

Wichtige Template-Komponenten:

• Metadaten: Service-Eigentuemer, Schweregrad, On-Call-Rotation
• Diagnosephase: Schnellchecks → detaillierte Untersuchung → Fehlermuster
• Loesungsphase: Sofortige Schadensbegrenzung → Ursachenbehebung → Verifizierung
• Eskalation: Kriterien und Kontaktpfade
• Kommunikation: Interne/externe Vorlagen
• Praevention: Kurz-/Langzeitmassnahmen

Erwartet: Ausgewaehltes Template entspricht der Incident-Komplexitaet, Abschnitte sind fuer den Service-Typ angemessen.

Bei Fehler:

• Mit dem Basis-Template beginnen und basierend auf Incident-Mustern iterieren
• Branchenbeispiele pruefen (Google-SRE-Buecher, Anbieter-Runbooks)
• Template basierend auf Team-Feedback nach der ersten Verwendung anpassen

Schritt 2: Diagnoseverfahren dokumentieren

Unter Extended Examples sind vollstaendige Diagnoseabfragen und Entscheidungsbaeume verfuegbar.

Schrittweise Untersuchungsverfahren mit spezifischen Abfragen erstellen.

Sechsstufige Diagnose-Checkliste:

1. Service-Gesundheit pruefen: Gesundheitsendpunkt-Pruefungen und Uptime-Metriken

   curl -I https://api.example.com/health  # Expected: HTTP 200 OK
   

   up{job="api-service"}  # Expected: 1 for all instances
   

2. Fehlerrate pruefen: Aktuelle Fehlerprozentzahl und Aufschluesselung nach Endpunkt

   sum(rate(http_requests_total{status=~"5.."}[5m]))
   / sum(rate(http_requests_total[5m])) * 100  # Expected: < 1%
   

3. Logs analysieren: Aktuelle Fehler und haeufigste Fehlermeldungen aus Loki

   {job="api-service"} |= "error" | json | level="error"
   

4. Ressourcenauslastung pruefen: CPU, Arbeitsspeicher und Verbindungspool-Status

   avg(rate(container_cpu_usage_seconds_total{pod=~"api-service.*"}[5m])) * 100
   # Expected: < 70%
   

5. Aktuelle Aenderungen pruefen: Deployments, Git-Commits, Infrastrukturanpassungen

6. Abhaengigkeiten untersuchen: Downstream-Service-Gesundheit, Datenbank-/API-Latenz

Fehlermuster-Entscheidungsbaum (Auszug):

• Service ausgefallen? → Alle Pods/Instanzen pruefen
• Fehlerrate erhoht? → Spezifische Fehlertypen pruefen (5xx, Gateway, Datenbank, Timeouts)
• Wann hat es begonnen? → Nach Deployment (Rollback), graduell (Ressourcenleck), ploetzlich (Traffic/Abhaengigkeit)

Erwartet: Diagnoseverfahren sind spezifisch, enthalten erwartete vs. tatsaechliche Werte, fuehren Responder durch die Untersuchung.

Bei Fehler:

• Abfragen im tatsaechlichen Monitoring-System testen, bevor sie dokumentiert werden
• Screenshots von Dashboards als visuelle Referenz einschliessen
• Abschnitt "Haeufige Fehler" fuer oft uebersehene Schritte hinzufuegen
• Basierend auf Feedback von Incident-Respondern iterieren

Schritt 3: Loesungsverfahren definieren

Unter Extended Examples sind alle 5 Loesungsoptionen mit vollstaendigen Befehlen und Rollback-Verfahren verfuegbar.

Schrittweise Behebung mit Rollback-Optionen dokumentieren.

Fuenf Loesungsoptionen (kurze Zusammenfassung):

1. Rollback eines Deployments (am schnellsten): Bei Fehlern nach dem Deployment

   kubectl rollout undo deployment/api-service
   

   Verifizieren → Ueberwachen → Loesungsbestaetigung (Fehlerrate < 1%, Latenz normal, keine Alerts)

2. Ressourcen hochskalieren: Bei hoher CPU/Arbeitsspeicher, Verbindungspool-Erschoepfung

   kubectl scale deployment/api-service --replicas=$((current * 3/2))
   

3. Service neustarten: Bei Speicherlecks, haengenden Verbindungen, Cache-Beschaedigung

   kubectl rollout restart deployment/api-service
   

4. Feature Flag / Circuit Breaker: Bei spezifischen Feature-Fehlern oder externen Abhaengigkeitsausfaellen

   kubectl set env deployment/api-service FEATURE_NAME=false
   

5. Datenbank-Behebung: Bei Datenbankverbindungen, langsamen Abfragen, Pool-Erschoepfung

   -- Kill long-running queries, restart connection pool, increase pool size
   

Universelle Verifikations-Checkliste:

• [ ] Fehlerrate < 1%
• [ ] Latenz P99 < Schwellenwert
• [ ] Durchsatz auf Basislinie
• [ ] Ressourcennutzung gesund (CPU < 70%, Arbeitsspeicher < 80%)
• [ ] Abhaengigkeiten gesund
• [ ] Benutzerseitige Tests bestanden
• [ ] Keine aktiven Alerts

Rollback-Verfahren: Wenn Loesung die Situation verschlechtert → pausieren/abbrechen → rueckgaengig machen → neu bewerten

Erwartet: Loesungsschritte klar, enthalten Verifikationspruefungen, bieten Rollback-Optionen fuer jede Aktion.

Bei Fehler:

• Mehr granulare Schritte fuer komplexe Verfahren hinzufuegen
• Screenshots oder Diagramme fuer mehrstufige Prozesse einschliessen
• Befehlsausgaben dokumentieren (erwartet vs. tatsaechlich)
• Separates Runbook fuer komplexe Loesungsverfahren erstellen

Schritt 4: Eskalationspfade etablieren

Unter Extended Examples sind vollstaendige Eskalationsstufen und Kontaktverzeichnis-Vorlage verfuegbar.

Festlegen, wann und wie Incidents eskaliert werden.

Wann sofort eskalieren:

• Kundenseitiger Ausfall > 15 Minuten
• SLO-Fehlerbudget > 10% erschoepft
• Datenverlust/-beschaedigung oder Sicherheitsverletzung vermutet
• Ursache innerhalb von 20 Minuten nicht identifizierbar
• Schadensminderungsversuche schlagen fehl oder verschlechtern die Situation

Fuenf Eskalationsstufen:

1. Primaerer On-Call (5 Min. Reaktionszeit): Fixes deployen, Rollback, Skalierung (bis zu 30 Min. allein)
2. Sekundaerer On-Call (automatisch nach 15 Min.): Zusaetzliche Unterstuetzung bei der Untersuchung
3. Teamleiter (architektonische Entscheidungen): Datenbankaenderungen, Anbieter-Eskalation, Incidents > 1 Stunde
4. Incident Commander (teamuebergreifende Koordination): Mehrere Teams, Kundenkommunikation, Incidents > 2 Stunden
5. Fuehrungsebene (C-Level): Grosse Auswirkungen (>50% Nutzer), SLA-Verletzung, Medien/PR, Ausfaelle > 4 Stunden

Eskalationsprozess:

1. Ziel benachrichtigen mit: aktuellem Status, Auswirkungen, ergriffenen Massnahmen, benoetigter Hilfe, Dashboard-Link
2. Bei Bedarf uebergeben: Timeline teilen, Massnahmen, Zugriff, erreichbar bleiben
3. Nicht still sein: alle 15 Min. aktualisieren, Fragen stellen, Feedback geben

Kontaktverzeichnis: Tabelle mit Rolle, Slack, Telefon, PagerDuty fuer:

• Plattform-/Datenbank-/Sicherheits-/Netzwerk-Teams
• Incident Commander
• Externe Anbieter (AWS, Datenbankanbieter, CDN-Anbieter)

Erwartet: Klare Eskalationskriterien, Kontaktinformationen leicht zugaenglich, Eskalationspfade entsprechen der Organisationsstruktur.

Bei Fehler:

• Kontaktinformationen auf Aktualitaet pruefen (vierteljaehrlich testen)
• Entscheidungsbaum hinzufuegen, wann eskaliert werden soll
• Beispiele fuer Eskalationsmeldungen einschliessen
• Reaktionszeiterwartungen fuer jede Stufe dokumentieren

Schritt 5: Kommunikationsvorlagen erstellen

Unter Extended Examples sind alle internen und externen Vorlagen mit vollstaendiger Formatierung verfuegbar.

Vorgefertigte Nachrichten fuer Incident-Updates bereitstellen.

Interne Vorlagen (Slack #incident-response):

1. Ersterklaerung:

   🚨 INCIDENT: [Title] | Severity: [Critical/High/Medium]
   Impact: [users/services] | Owner: @username | Dashboard: [link]
   Quick Summary: [1-2 sentences] | Next update: 15 min
   

2. Fortschrittsupdate (alle 15-30 Min.):

   📊 UPDATE #N | Status: [Investigating/Mitigating/Monitoring]
   Actions: [what we tried and outcomes]
   Theory: [what we think is happening]
   Next: [planned actions]
   

3. Schadensbegrenzung abgeschlossen:

   ✅ MITIGATION | Metrics: Error [before→after], Latency [before→after]
   Root Cause: [brief or "investigating"] | Monitoring 30min before resolved
   

4. Loesungsbekanntmachung:

   🎉 RESOLVED | Duration: [time] | Root Cause + Impact + Follow-up actions
   

5. Fehlalarm: Keine Auswirkungen, kein Follow-up erforderlich

Externe Vorlagen (Statusseite):

• Initial: Untersuchung, Startzeit, naechstes Update in 15 Min.
• Fortschritt: Ursache identifiziert (kundenverstaendlich), Behebung wird implementiert, geschaetzte Loesungszeit
• Loesung: Loesungszeit, Ursache (einfach), Dauer, Praeventionsmassnahmen

Kunden-E-Mail-Vorlage: Timeline, Auswirkungsbeschreibung, Loesung, Praevention, Entschaedigung (falls zutreffend)

Erwartet: Vorlagen sparen Zeit waehrend Incidents, gewaehrleisten konsistente Kommunikation, reduzieren kognitive Belastung der Responder.

Bei Fehler:

• Vorlagen an den Kommunikationsstil des Unternehmens anpassen
• Vorlagen mit gaengigen Incident-Typen vorab ausfuellen
• Slack-Workflow/Bot erstellen, um Vorlagen automatisch zu befuellen
• Vorlagen waehrend Incident-Retrospektiven ueberpruefen

Schritt 6: Runbook mit Monitoring verknuepfen

Unter Extended Examples sind vollstaendige Prometheus-Alert-Konfigurationen und Grafana-Dashboard-JSON verfuegbar.

Runbook mit Alerts und Dashboards integrieren.

Runbook-Links zu Prometheus-Alerts hinzufuegen:

- alert: HighErrorRate
  annotations:
    runbook_url: "https://wiki.example.com/runbooks/high-error-rate"
    dashboard_url: "https://grafana.example.com/d/service-overview"
    incident_channel: "#incident-platform"

Schnelle Diagnose-Links im Runbook einbetten:

• Service-Uebersichts-Dashboard
• Fehlerrate der letzten Stunde (Prometheus-Direktlink)
• Aktuelle Fehler-Logs (Loki/Grafana Explore)
• Aktuelle Deployments (GitHub/CI)
• PagerDuty-Incidents

Grafana-Dashboard-Panel erstellen mit Runbook-Links (Markdown-Panel, der alle Incident-Runbooks mit On-Call- und Eskalationsinformationen auflistet)

Erwartet: Responder koennen Runbooks direkt aus Alerts oder Dashboards aufrufen, Diagnoseabfragen sind vorab ausgefuellt, Ein-Klick-Zugriff auf relevante Tools.

Bei Fehler:

• Pruefen, ob Runbook-URLs ohne VPN/Login zugaenglich sind
• URL-Verkuerzer fuer komplexe Grafana/Prometheus-Links verwenden
• Links vierteljaehrlich testen, um sicherzustellen, dass sie nicht kaputt gehen
• Browser-Lesezeichen fuer haeufig verwendete Runbooks erstellen

Validierung

• [ ] Runbook folgt konsistenter Template-Struktur
• [ ] Diagnoseverfahren enthalten spezifische Abfragen und erwartete Werte
• [ ] Loesungsschritte sind handlungsorientiert mit klaren Befehlen
• [ ] Eskalationskriterien und Kontakte sind aktuell
• [ ] Kommunikationsvorlagen fuer interne und externe Zielgruppen bereitgestellt
• [ ] Runbook ist aus Monitoring-Alerts und Dashboards verknuepft
• [ ] Runbook waehrend einer Incident-Simulation oder einem echten Incident getestet
• [ ] Feedback von Respondern in das Runbook eingeflossen
• [ ] Revisionsverlauf mit Datum und Autoren verfolgt
• [ ] Runbook ohne Authentifizierung zugaenglich (oder offline gecacht)

Haeufige Stolperfallen

• Zu generisch: Runbooks mit vagen Schritten wie "Logs pruefen" ohne spezifische Abfragen sind nicht handlungsorientiert. Konkret sein.
• Veraltete Informationen: Runbooks, die auf alte Systeme oder Befehle verweisen, werden nutzlos. Vierteljaehrlich ueberpruefen.
• Keine Verifikationsschritte: Loesung ohne Verifizierung fuehrt zu falsch positiven Ergebnissen. Immer "Wie bestaetigt man, dass es behoben ist" einschliessen.
• Fehlende Rollback-Verfahren: Jede Aktion sollte einen Rollback-Plan haben. Responder nicht in einem schlechteren Zustand zuruecklassen.
• Wissen voraussetzen: Runbooks nur fuer Experten schliessen Junior-Engineers aus. Fuer die am wenigsten erfahrene Person in der Rotation schreiben.
• Kein Eigentuemer: Runbooks ohne Eigentuemer werden veraltet. Team/Person zuweisen, das/die fuer Updates zustaendig ist.
• Hinter Authentifizierung verborgen: Runbooks, die bei VPN/SSO-Problemen nicht zugaenglich sind, sind in einer Krise nutzlos. Kopien cachen oder oeffentliches Wiki verwenden.

Verwandte Skills

• configure-alerting-rules - Runbooks mit Alert-Annotationen verknuepfen fuer sofortigen Zugriff waehrend Incidents
• build-grafana-dashboards - Runbook-Links in Dashboards und Diagnose-Panels einbetten
• setup-prometheus-monitoring - Diagnoseabfragen aus Prometheus in Runbook-Verfahren einschliessen
• define-slo-sli-sla - SLO-Auswirkungen in die Incident-Schweregrad-Klassifizierung einbeziehen