cluster-knaster/docs/spec/SPEC-healer.md

SPEC-healer: Deterministisches Autohealing

Paket: knaster.healer.

1. Eingang

Alertmanager-Webhook (Version 4) an POST /v1/healer/alertmanager. Pro Alert werden status (firing/resolved), labels, annotations und fingerprint verarbeitet.

2. Regeln (config/healer-rules.yaml)

rules:
  - id: slot-endpoint-down
    match: {alertname: SlotEndpointDown}          # alle Labels müssen gleich sein
    ladder:
      - {action: restart_container, params: {host: "{node}", container: "{container}"}, attempts: 2, cooldown: 5m}
      - {action: restart_vm,        params: {vmid: "{vmid}", pve_node: "{pve_node}"}, attempts: 1, cooldown: 15m}
      - {action: mark_slot,         params: {slot: "{slot}", status: degraded}, attempts: 1}
    on_exhausted: notify
    on_resolved: [{action: mark_slot, params: {slot: "{slot}", status: ok}, only_if_set_by_healer: true}]

{label} wird aus den Alert-Labels ersetzt. Fehlt ein Label, wird die Stufe übersprungen und im Ergebnis vermerkt.

3. Ablauf pro Alert (firing)

1. Erste passende Regel suchen (Reihenfolge der Datei). Passt keine, wird nur benachrichtigt (unmatched).
2. Zustand pro (rule_id, fingerprint): Versuche pro Stufe und Zeitpunkt der letzten Aktion.
3. Ist der Cooldown der letzten Aktion noch nicht vorbei, passiert nichts (cooldown).
4. Sonst wird die erste Stufe genommen, deren Versuchsbudget noch nicht erschöpft ist. Vor der Ausführung entscheidet die Policy (SPEC-maintenance §2): Bei auto wird ausgeführt, bei approve entsteht ein Vorschlag (Quelle healer) und die Stufe gilt als verbraucht.
5. Sind alle Stufen erschöpft, wird einmalig benachrichtigt (exhausted).
6. Ein globaler Schutz begrenzt die Infrastruktur-Aktionen auf max_actions_per_hour (Standard 10). Darüber wird nur noch benachrichtigt.

resolved: Die on_resolved-Aktionen laufen, und der Zustand des Fingerprints wird gelöscht.

4. Treiber (knaster.healer.drivers)

Aktion	Treiber	API
restart_container	Portainer	POST /api/endpoints/{endpoint}/docker/containers/{container}/restart
restart_vm	Proxmox	POST /api2/json/nodes/{pve_node}/qemu/{vmid}/status/reboot
reboot_host	Proxmox	POST /api2/json/nodes/{pve_node}/status (command=reboot)
mark_slot	Registry	Laufzeitzustand
notify	Webhook (n8n)	POST NOTIFY_WEBHOOK_URL

Alle Treiber haben einen Dry-Run-Modus (Standard: an). Ein globales KNASTER_DRY_RUN=false schaltet die Ausführung frei, zusätzlich muss der Treiber pro Aktion in config/healer-rules.yaml unter enabled_actions aufgeführt sein.

5. Mitgelieferte Alerts (deploy/prometheus/alerts.yml)

SlotEndpointDown, SlotCanaryFailing, GpuXidError, GpuTemperatureHigh, VllmKvCacheSaturated, NodeDown, DiskAlmostFull.