feat(runbook): Notfall-Runbook + Inline-Hints an Alarm-Flaechen (CHO tower-notfall-runbook)
DATEI 1: public/runbook/runbook-tower-notfall.md (statisch, Anker #deadman/#spool/#deadletter/#health)
DATEI 2: /runbook-Route (Server Component, Mini-MD-Renderer, CSP-konform, force-static)
DATEI 3: runbookHints.ts (LAMP_HINTS/buildView/renderHintHtml 1:1 aus runbook_hints.py)
+ RunbookHint.tsx eingebunden an 4 Alarm-Flaechen:
- EscalationHistory (Deadman, Szenario A)
- TaskBrowser Spool-Tab (Szenario B) + Dead-Letter-Tab (B3)
- TaskBrowser/OpsPanels Degraded/Error (Health, Szenario C)
Keine Ampelfarben/Deadman-Logik/Degraded-Banner/Datenpfade angefasst (CHO-NICHT ANFASSEN erfuellt).
Build verifiziert: tsc --noEmit clean, next build gruen (/runbook static).
This commit is contained in:
@@ -0,0 +1,131 @@
|
||||
# Notfall-Runbook Tower (Fleet vs-fleet-rebuild)
|
||||
|
||||
Stand: 2026-10-30 · Autor: devops · Karte: tower-notfall-runbook
|
||||
Geltung: Owner am Tower-Panel (10.0.30.213, tcp/8099). Ziel: in <5 min
|
||||
entscheiden und handeln, ohne zu raetseln.
|
||||
|
||||
## Anker (Deep-Link-Ziele fuer die Alarm-Ampeln)
|
||||
Die Inline-Hints/Links an den Tower-Ampeln springen genau auf einen dieser
|
||||
Anker (nur interne Links, kein aktiver Inhalt/Script, keine Secrets):
|
||||
- **#deadman** -> Deadman-Status / Szenario A
|
||||
- **#spool** -> Spool-Aging / Szenario B
|
||||
- **#deadletter** -> Dead-Letter-Ansicht / Szenario B (Punkt 3)
|
||||
- **#health** -> Health-Ampel / Degraded-Banner / Szenario C
|
||||
Diese Datei ist reiner Text (Markdown); die Hints rendern daraus nur
|
||||
Ueberschrift + Link, nichts Ausfuehrbares.
|
||||
|
||||
## 0. Grundlagen (immer zuerst lesen)
|
||||
- Heartbeat-Intervall: 300 s je Agent an den Beacon.
|
||||
- Ampel Health: gruen <120 s, gelb 120-300 s, rot >300 s (Beacon-Heartbeat-Age).
|
||||
- Deadman-Schwelle: 5400 s (90 min) blockierte Fleet -> Kaskade reisst.
|
||||
- Spool-Aging: offene Envelopes (submitted/working), rot >5400 s.
|
||||
- Diagnose-Oberflaechen am Tower-Panel: Deadman-Status, Spool-Aging,
|
||||
Dead-Letter, Alarm-Feed, Health-Ampel, /healthz + /api/status.
|
||||
- Aufgaben des Owners: nur ENTSCHEIDEN + Freigeben. Kein Debugging im Panel.
|
||||
|
||||
## ESKALATIONSKONTAKT (Owner)
|
||||
- Primaer: **Owner** (Dominik). Kanal: Owner-Inbox/Queue im Tower.
|
||||
- Eskalation aus einem Agenten heraus: ueber den CISO-Kanal
|
||||
(`submit_task(from_agent=<id>, to=ciso, type=review, topic="[NAR] <ziel>")`);
|
||||
der CISO leitet kritische Faelle als `escalation` P1 an `tower-owner`
|
||||
weiter (FLEET-POLICIES 1.3). Direkt-Adressierung an `tower-owner` ist nur
|
||||
dem CISO erlaubt.
|
||||
- Owner-Entscheidungen (Abnahme/Review/NAR) laufen ueber die Owner-Queue.
|
||||
- Bei Netz-Themen: NAR ueber den CISO; bei Infrastruktur/Tower: tower-owner.
|
||||
|
||||
---
|
||||
|
||||
<a id="deadman"></a>
|
||||
## Szenario A — Deadman-Blockade (Fleet steht, Ampel "Deadman: blocked")
|
||||
Beobachtung: Deadman-Status zeigt Zustand `blocked` + blockierenden Owner-Task
|
||||
(ID, Typ, Alter) im Header; ggf. rot in der Health-Ampel.
|
||||
|
||||
Diagnose-Pfad:
|
||||
1. Panel -> **Deadman-Status**: welcher Owner-Task blockiert? Alter auslesen.
|
||||
2. Panel -> **Alarm-Feed**: juengste Deadman-Kaskade (Zeit, Agent, Ursache,
|
||||
Dauer) - bestaetigt, ob es die laufende Blockade ist.
|
||||
3. Panel -> **Health-Ampel** (#health): welche Agents stehen rot/gelb (wer ist
|
||||
betroffen)?
|
||||
4. Abgleich: blockierender Task-Typ (Abnahme/Review/NAR/Entscheidung).
|
||||
|
||||
Schritte:
|
||||
1. Blockierenden Owner-Task oeffnen und INNERHALB der Queue entscheiden
|
||||
(Abnahme erteilen, Review freigeben/ablehnen, NAR approven).
|
||||
2. Nach Entscheidung Deadman-Status auf `progress` pruefen (Auto-Refresh 30 s).
|
||||
3. Wenn der Task nicht entscheidbar ist (fehlender Kontext): Task mit
|
||||
Kommentar zurueck an Absender (reply_to) statt liegen zu lassen.
|
||||
4. Verifikation: Health-Ampel der betroffenen Agents wieder gruen <120 s
|
||||
binnen 2 Heartbeat-Zyklen (<=10 min).
|
||||
|
||||
Eskalation: Bleibt die Blockade >5400 s bestehen oder ist der Task unklar ->
|
||||
Owner direkt ansprechen (Kanal s.o.), Grund + Task-ID nennen.
|
||||
|
||||
---
|
||||
|
||||
<a id="spool"></a>
|
||||
## Szenario B — Spool-Stau (Tasks haengen, Zustellung klemmt)
|
||||
Beobachtung: Spool-Aging listet Envelopes >5400 s rot; Zusteller liefern nicht.
|
||||
|
||||
Diagnose-Pfad:
|
||||
1. Panel -> **Spool-Aging**: Envelopes nach Alter + Empfaenger. Aeltester
|
||||
Eintrag zuerst; rot = >5400 s.
|
||||
<a id="deadletter"></a>
|
||||
2. Panel -> **Dead-Letter**: status=failed (letzte 7 Tage) mit from->to, Alter -
|
||||
bereits verlorene Arbeit (Luecke Spool-Aging vs. Alarm-Feed).
|
||||
3. Panel -> **Health-Ampel** (#health): ist Empfaenger-Agent rot? -> down.
|
||||
4. Panel -> **/api/status**: Datenquellen-Zustand Prometheus/Beacon; degraded?
|
||||
|
||||
Schritte:
|
||||
1. Einzelner haengender Envelope, Empfaenger gruen -> Zustellung neu anstossen
|
||||
(Task erneut submitten an denselben Empfaenger, reply_to setzen).
|
||||
2. Blockierter ganzer Empfaenger (rot) -> Szenario A/C zuerst loesen; der Spool
|
||||
leert sich danach automatisch.
|
||||
3. Failed-Tasks aus der Dead-Letter-Ansicht pruefen: wiederholbar -> erneut
|
||||
submitten; endgueltig unloesbar -> Task mit Grund neu aufsetzen (nicht still
|
||||
verwerfen).
|
||||
4. Verifikation: keine Eintraege mehr >5400 s im Spool-Aging; Dead-Letter
|
||||
waechst nicht weiter.
|
||||
|
||||
Eskalation: Envelopes >5400 s ohne down-Empfaenger -> Ursache unklar, an
|
||||
tower-owner mit Screenshot/IDs melden; bei >2 betroffenen Agents zusaetzlich
|
||||
Owner informieren (Kanal s.o.).
|
||||
|
||||
---
|
||||
|
||||
<a id="health"></a>
|
||||
## Szenario C — Panel-Ausfall (Tower nicht erreichbar/leer/fehlerhaft)
|
||||
Beobachtung: Panel laedt nicht, Leeranzeige oder Crash; /healthz antwortet nicht.
|
||||
|
||||
Diagnose-Pfad (Reihenfolge, um Server vs. Daten zu trennen):
|
||||
1. Panel -> **/healthz**: 200 = Server lebt -> Problem ist Datenquelle/UI.
|
||||
2. Panel -> **/api/status**: Version, Uptime, Datenquellen-Zustand
|
||||
Prometheus/Beacon. Liefert JSON = API ok.
|
||||
3. Degraded-Banner + Datenalter-Anzeige: bei Prometheus-/Beacon-Ausfall zeigt
|
||||
der Tower Datenalter + 60 s-Cache; das ist Degraded, KEIN Totalausfall.
|
||||
4. Wenn /healthz gar nicht antwortet: Panel-/Prozess-Ausfall am Tower-Host.
|
||||
|
||||
Schritte:
|
||||
1. Degraded (healthz 200, /api/status zeigt Quelle down): keine Panik -
|
||||
Betrieb laeuft mit Cache weiter. Ursache der Quelle pruefen (Beacon-Ausfall
|
||||
= alle Agents rot -> Szenario-A-Umfeld).
|
||||
2. Totalausfall (healthz kein 200 / Verbindung abgelehnt): Tower braucht
|
||||
Neustart/Deploy -> Aenderungsauftrag an tower-owner (nicht selbst am Host
|
||||
eingreifen).
|
||||
3. Waehrend Ausfall: Diagnose ersatzweise ueber die Agenten-Boards/Beacon
|
||||
(Karten-Status, Heartbeat-Zeitstempel) weiterfuehren, Owner informieren.
|
||||
4. Verifikation: /healthz 200 UND /api/status mit allen Quellen "up"; Panel
|
||||
zeigt Datenalter ~0.
|
||||
|
||||
Eskalation: healthz-Ausfall oder Deploy-Bedarf -> sofort P1 an tower-owner
|
||||
(ueber den CISO-Kanal); parallele Owner-Info, da ohne Panel die Lage ueber
|
||||
Agenten nicht sichtbar ist.
|
||||
|
||||
---
|
||||
|
||||
## Kurz-Anhang: Anzeige am Tower
|
||||
Dieses Runbook + Eskalationskontakt sollen an den Alarm-Ampeln (Deadman-Status
|
||||
-> #deadman, Spool-Aging -> #spool, Dead-Letter -> #deadletter, Health-Ampel ->
|
||||
#health) als kontextueller Hilfe-Link/Inline-Hint erscheinen. Der Hint ist
|
||||
reiner Text (Ueberschrift + interner Link), kein aktives Element; Alarmlogik
|
||||
und Degraded-Banner bleiben unberuehrt. Aenderungsauftrag an tower-owner siehe
|
||||
separater Task "[build] tower-notfall-runbook: Runbook-Link an Alarm-Ampeln".
|
||||
Reference in New Issue
Block a user