Flughandbücher sind an sonnigen Tagen langweilig und unbezahlbar, wenn etwas Unerwartetes passiert. Runbooks sind dieselbe Art Dokument. Den Vergleich habe ich nicht erfunden, und ich behaupte nicht, die Luftfahrt habe Operations gelöst. Was ich vom Fliegen mitgenommen habe, ist einfacher: Wenn der Puls steigt, fällt man auf Struktur zurück. Ein gutes Runbook gibt diese Struktur, ohne so zu tun, als würde die Welt immer dem Skript folgen.

Offenes Notizbuch und Stift auf einem Schreibtisch

Foto von Leeloo The First auf Pexels

Dieser Beitrag handelt davon, wie ich Runbooks heute schreibe, womit ich noch danebenliege und wo Kubernetes ins Bild passt. Wer eine Template-Bibliothek oder eine Zertifizierungsantwort sucht, ist hier falsch. Es sind Notizen aus Incidents, die schlecht liefen, und aus ein paar, die weniger schlecht liefen, weil jemand etwas aufgeschrieben hatte, als noch Ruhe war.

Was ein gutes Runbook wirklich enthält

Kein Copy-Paste jedes kubectl-Befehls, den man je getippt hat. Ein Runbook sollte eine kleine Zahl von Fragen beantworten, die das zukünftige Ich um 2 Uhr nachts nicht aus dem Gedächtnis rekonstruieren will.

Symptom — wie sieht kaputt für Nutzer und Metriken aus? Konkret sein. „App langsam” ist kein Symptom. „P95-Latenz über 800 ms beim Checkout-Service länger als fünf Minuten” ist näher dran. Welche Alerts feuern, was Kunden melden, wie eine gesunde Baseline aussieht: Das gehört hinein, damit man den Unterschied erkennt.

Erste Prüfungen — drei bis fünf Befehle oder Dashboard-Panels, in Reihenfolge. Reihenfolge zählt. Wenn man zur interessanten Hypothese springt, bevor man die Grundlagen bestätigt, verschwendet man Zeit. Ich starte meist mit: Erhält der Service Datenverkehr? Sind Pods bereit? Sind Fehler erhöht? Gab es kürzlich einen Deploy? Langweilige Prüfungen zuerst.

Sichere Gegenmaßnahmen — skalieren, Rollback, Datenverkehr umleiten, Deploys einfrieren. Jeder Schritt sollte sagen, was er behebt, was er kaputt machen könnte und wie man ihn rückgängig macht. „Deployment neu starten” ist keine Gegenmaßnahme, wenn man nicht weiß, warum ein Neustart hilft und welchen Zustand man verlieren könnte.

Eskalation — wen anrufen und welche Infos sie brauchen. Person oder Rotation benennen, nicht Abteilung. Fakten auflisten, die sie sowieso fragen: wann es begann, Wirkungsradius, letzte Änderung, was schon versucht wurde.

Stopp-Bedingungen — wann pausieren und nachdenken, statt weiter herumzustochern. Das überspringen die meisten Runbooks. In der Luftfahrt haben Checklisten explizite Haltepunkte: nicht weiter, bis diese Bedingung erfüllt ist. Operations braucht dasselbe. Wenn zwei Gegenmaßnahmen scheitern: stoppen und die Untersuchung erweitern. Zufällige Deletes um 3 Uhr altern selten gut.

Ist das Runbook fünfzig Seiten lang, öffnet es niemand während eines Incidents. Eine Seite pro häufigem Fehlermodus reicht zum Start. Für seltene Fälle kann man tiefer verlinken.

Luftfahrt-Parallel, ohne Postersprüche

Piloten üben Abläufe, bis die Struktur Muskelgedächtnis ist, und passen sich dann an, wenn die Realität nicht zum Skript passt. Notfallverfahren im Flughandbuch sind keine inspirierenden Zitate. Es sind sequenzielle Schritte mit Entscheidungsästen: wenn dies, dann das; wenn nicht, hierhin.

Runbooks versuche ich genauso zu schreiben. Stabile Schritte, explizite Entscheidungspunkte, Leerraum für Notizen nach einem Incident. Ziel ist nicht, Urteilskraft zu entfernen. Ziel ist, Urteilskraft für die Teile zu reservieren, die das Handbuch nicht kennen kann — die seltsame Wechselwirkung zwischen neuem Feature Flag und altem Cache — statt kognitive Bandbreite dafür zu verbrauchen, sich zu erinnern, welches Dashboard Ingress-Fehler zeigt.

Es gibt einen Unterschied zwischen Checkliste und Referenzhandbuch. Checklisten sind kurz und werden unter Zeitdruck ausgeführt. Referenzkapitel erklären Systeme in der Tiefe, für Training und Fehlersuche, wenn man eine Stunde hat. Ich behalte beides, aber ich kennzeichne es klar. Während eines Incidents will ich die Checkliste. Am Tag danach das Referenzhandbuch.

Eine Cockpit-Gewohnheit, die sich besser übertragen lässt als erwartet: Read-back. Wenn jemand sagt „Deployment auf zehn skalieren”, wiederholt der Incident Lead und bestätigt. Klein, aber wirksam. Es reduziert „Oh, ich dachte, du meintest den anderen Cluster”-Momente.

Wo Kubernetes hineinpasst

Cluster-Incidents wiederholen sich öfter, als wir zugeben. Node NotReady, CrashLoopBackOff, pending PVCs, DNS-Seltsames, Ingress-Fehlkonfiguration, ablaufende Zertifikate, erschöpfte Quotas, hängende terminating Namespaces. Jeder dieser Fälle verdient einen kurzen Pfad, dokumentiert, während man ruhig ist.

So sieht ein Runbook-Abschnitt aus, den ich für CrashLoopBackOff nutze — nicht weil er neu ist, sondern weil einmal aufschreiben mich zweimal vor schlechtem Improvisieren bewahrt hat:

# Symptom: Pod restarts repeatedly; kubectl get pods shows CrashLoopBackOff

# 1. Recent change?
kubectl rollout history deployment/<name> -n <ns>
kubectl get events -n <ns> --sort-by='.lastTimestamp' | tail -20

# 2. Why is the container exiting?
kubectl logs deployment/<name> -n <ns> --previous
kubectl describe pod -n <ns> -l app=<label> | grep -A5 "Last State"

# 3. Safe mitigations (pick one, document in incident channel)
kubectl rollout undo deployment/<name> -n <ns>   # if correlated with deploy
kubectl scale deployment/<name> -n <ns> --replicas=0  # stop bleeding, if acceptable

# Stop: do not delete PVCs, Secrets, or Namespaces without explicit approval

Dieser Block ist nicht clever. Er ist geordnet. Das Runbook verlinkt auch das Grafana-Dashboard für den Service und benennt die Datenbankbereitschaft, wenn Logs connection refused zeigen.

Auf Node-Ebene trenne ich „Pod cannot schedule” von „node is NotReady”. In Slack sehen sie ähnlich aus („nichts geht”), aber die Lösungswege laufen schnell auseinander. Ein Scheduling-Runbook erwähnt taints, resource requests, PVC zone mismatch und cluster autoscaler status. Ein NotReady-Runbook erwähnt kubelet logs, disk pressure und Cloud-Provider-Statusseiten. Beides in einem Dokument zu mischen heißt, dass jemand mit Zuversicht die falsche Maßnahme anwendet.

OpenShift fügt eine Schicht hinzu: Routes statt Ingress, Operatoren, die Custom Resources abgleichen, SCC constraints, die Pods still blockieren. Ich pflege plattformspezifische Ergänzungen, statt so zu tun, als passe ein Runbook gleichermaßen für Vanilla Kubernetes und OpenShift. Duplikation ist nervig. Falsche Schritte während eines Ausfalls sind schlimmer.

Wie ich sie wirklich schreibe und pflege

Ich schreibe Runbooks nach Incidents, nicht vor dem Launch. Das klingt verkehrt herum. In der Praxis ist das Post-Incident-Fenster der Moment, in dem das Team sich einig ist, was passiert ist und was geholfen hätte. Das festhalten, solange es frisch ist. Ein Runbook aus einem echten Fehlermodus wird gelesen. Eines aus einer Vorlage wird ignoriert.

Jede Seite bekommt Datum und Verantwortliche. „Last verified: 2024-05-02, @marc” ist keine Bürokratie. Es ist die Erlaubnis, der Seite zu misstrauen, wenn das Datum zwei Jahre alt ist und sich die Architektur zweimal geändert hat.

Ich verlinke Live-Dashboards, keine Screenshots. Screenshots lügen in der Woche, nachdem jemand ein Panel umbenannt hat. Wenn der Link verrottet, scheitert das Runbook sichtbar beim Drill. Genau dann will man es merken.

Drills zählen. Einmal pro Quartal ein Runbook wählen und in Staging oder anhand eines aufgezeichneten Incidents durchgehen. Man findet Schritte mit gelöschten Namespaces und Befehle, die neuere Flags brauchen. Dann korrigieren, nicht während Produktionsschmerz.

Bei GitOps-Umgebungen sollte das Runbook sagen, wie man Reconciliation sicher pausiert. Argo CD und Flux kämpfen gegen manuelle Patches an Dingen, die sie verwalten. Eine Zeile „freeze sync on application X before manual scale” verhindert einen zweiten Incident im ersten.

Womit ich noch danebenliege

Runbooks nach Architekturänderungen aktuell zu halten ist meine schwächste Stelle. Ein veraltetes Runbook ist schlimmer als keines, weil es Misstrauen trainiert. Menschen öffnen sie nicht mehr. Und dann folgt doch einmal jemand einem Rollback-Befehl für ein Deployment, das nicht mehr existiert.

Ich habe auch überdokumentiert. Früh in meiner Runbook-Begeisterung habe ich Troubleshooting, Architekturdiagramme und Onboarding in einen Confluence-Baum gemischt. Niemand fand die Checkliste in der Enzyklopädie. „Wie das System funktioniert” von „was tun, wenn es bricht” zu trennen half.

Ein weiterer Fehler: für den Experten schreiben, den man sich wünscht, nicht für die Person, die wirklich On-Call ist. Wenn das Runbook tiefes Wissen über ein custom Service Mesh voraussetzt, sollte man es umschreiben oder akzeptieren, dass es Referenzmaterial ist, keine Incident-Checkliste.

Ich improvisiere während Incidents trotzdem viel. Das Runbook hindert mich daran, mit zufälligen Deletes zu beginnen. Es ersetzt nicht Gespräche mit Menschen, die die Anwendung besser kennen als ich. CRM auf der Bridge — wer spricht, wer entscheidet — zählt genauso wie das Dokument. Das Runbook ist ein Crewmitglied, nicht die ganze Crew.

Eine minimale Vorlage, die für mich funktioniert

Wenn ich eine neue Runbook-Seite starte, nutze ich jedes Mal dieselben Überschriften:

  1. Symptome und Alerts
  2. Auswirkung (wer betroffen ist, SLO-Verletzung oder nicht)
  3. Erste fünf Minuten (Befehle/Panels in Reihenfolge)
  4. Wenn das X bestätigt, dann Y (Entscheidungsäste)
  5. Sichere Gegenmaßnahmen (mit Schritten zum Rückgängigmachen)
  6. Eskalieren, wenn (Personen + zu sammelnde Daten)
  7. Stopp / nicht tun
  8. Nach der Behebung (Post-Incident-Notiz, Runbook-Update-Ticket)

Diese Struktur passt für häufige Fälle auf eine gedruckte Seite. Seltene Randfälle bekommen einen Link und eine verantwortliche Person zum Anrufen.

Abschlussgedanke

Flughandbücher allein haben mich nicht zu einem guten Piloten gemacht. Fliegen, Briefings, Nachbesprechungen und Korrekturen durch Fluglehrer haben mich besser gemacht. Runbooks sind ähnlich. Sie lohnen sich, weil sie ruhiges Denken in eine Form bringen, die man nutzen kann, wenn man nicht ruhig ist. Sie sind es nicht wert, angebetet zu werden. Aktualisieren, üben und sich verzeihen, wenn man trotzdem improvisieren muss.

Wer diesen Monat ein Runbook pflegt, sollte den Fehlermodus wählen, der einen im letzten Quartal geweckt hat. Eine ehrliche Seite schlägt eine Bibliothek aus Wunschdokumentation. Ich arbeite an meiner eigenen Bibliothek noch Seite für Seite.