management/verfahren/deploy-uebergabe.md

# Verfahren: Deploy-Übergabe

Für die Konstellation „einer baut, ein anderer rollt aus". Zweck ist nicht mehr
Prozess, sondern **weniger Rückfragen und weniger stille Fehlschläge**.

Eingeführt am 2026-08-01 nach dem Deploy der CVE-Pipeline (`gitops#47`), siehe
[aar/2026-08-01-cve-pipeline-gitops47.md](aar/2026-08-01-cve-pipeline-gitops47.md).

## Ablauf

1. Wer baut, öffnet ein Issue aus der Vorlage **Deploy-Übergabe**
   (`.gitea/ISSUE_TEMPLATE/deploy-uebergabe.yaml`).
2. Wer ausrollt, arbeitet die Prüfliste unten ab und deployt.
3. Wer ausrollt, hängt den **AAR** als Kommentar an dasselbe Issue
   (Vorlage: [aar-vorlage.md](aar-vorlage.md)). Bei Befunden ab MEDIUM
   zusätzlich als Datei unter [aar/](aar/).

## Die vier Punkte, die den Unterschied machen

### 1. Mengengerüst vor dem Deploy

Bei allem, was etwas erzeugt — Nachrichten, Alarme, Zeitreihen, Requests —
gehört die erwartete Anzahl beim **ersten** Lauf in die Übergabe. Geschätzt ist
in Ordnung, gemessen ist besser; welches von beidem, muss dabeistehen.

Der Grund: „ein Alarm pro Fund" ist eine völlig unauffällige Zeile im Code und
harmlos bei 5 Funden. Bei 126 ist es ein Ausfall. Der Unterschied steht nirgends
im Diff — er ergibt sich erst aus den Daten, gegen die das Ding läuft.

Eine Stichprobe reicht: drei repräsentative Elemente von 29 messen und
hochrechnen kostet Minuten und liefert die Größenordnung.

### 2. Verifikation dort, wo der Dienst liest

Ein grüner Linter belegt, dass eine Datei **gültig** ist — nicht, dass sie
**geladen** wurde. Diese beiden Aussagen sind bei Bind-Mounts, Caches und
Reload-Semantiken regelmäßig verschieden.

Also im Container prüfen, in der laufenden API, im tatsächlich geladenen
Regelwerk. Ein Blick auf die Platte beweist nichts über den Prozess.

### 3. Deploy-Kommando vollständig übergeben

Inklusive Reload-, Restart- und Recreate-Schritten. Ein `docker compose up -d`,
das `Running` meldet und dabei nichts aktiviert, ist der häufigste stille
Fehlschlag: kein Fehler, kein Log, falscher Zustand.

Konkret auf dem Monitoring-Stack (CFGMON): Einzeldatei-Mounts hängen am Inode,
`git pull` benennt beim Schreiben um und erzeugt damit einen neuen — der
Container zeigt danach weiter auf die alte Datei. Es braucht
`--force-recreate`. Details: `gitops#52`.

### 4. Zustellwege stumm schalten statt Deploy verschieben

Datensammlung und Außenwirkung lassen sich fast immer getrennt scharf schalten.
Wenn der Zustellweg das Risiko ist, wird **er** abgeklemmt — nicht der ganze
Deploy verschoben.

So läuft die Datensammlung ab sofort, das Dashboard steht, echte Zahlen
ersetzen die Schätzung, und die Entscheidung über die Zustellung fällt auf
Basis von Messwerten statt Vermutungen. Wichtig: die Stummschaltung gehört
committet und dokumentiert, sonst ist sie in zwei Wochen ein Rätsel.

## Prüfliste für den Ausrollenden

- [ ] Diff gelesen, nicht nur die Beschreibung
- [ ] Mengengerüst plausibel? Bei Zweifel an einer Stichprobe selbst messen
- [ ] Configs mit den jeweiligen Werkzeugen validiert (`promtool`, `amtool`,
      `compose config`, `py_compile` …)
- [ ] Außenwirkung identifiziert — was verlässt beim ersten Lauf das System?
- [ ] Nach dem Deploy **im Container** verifiziert, dass die neue Config aktiv ist
- [ ] Geprüft, ob vorher gesunde Dinge noch gesund sind (keine stille Regression)
- [ ] AAR geschrieben, Folge-Issues angelegt, Stummschaltungen dokumentiert

## Abgrenzung

Das Verfahren gilt für Übergaben zwischen Personen. Wer baut **und** ausrollt,
braucht kein Issue — der AAR lohnt trotzdem, sobald es Befunde ab MEDIUM gab.

## Kanonisierung nach CFGMON-Deploys (Topologie-Pflichtschritt)

CFGMON erreicht git.lab nicht — Commits aus Deploy-Sessions landen zwangsläufig
direkt auf dem Gitea-Mirror und werden vom nächsten Mirror-Lauf **kommentarlos
überschrieben** (zweimal passiert: dfe04c4→6ffab68 am 01.08. nachts,
2b715ca→0bd77e2 am 01.08. nachmittags). Deshalb gehört zu jeder Übergabe:

1. **CFGMON-Seite** vermerkt den Commit-Hash im Übergabe-Issue (Feld „Stand").
2. **Mac-Seite** kanonisiert zeitnah: Patch per
   `https://rohana.axion1337.de/sorb/<repo>/commit/<sha>.patch` ziehen
   (verwaiste Objekte bleiben eine Weile abrufbar), `git am`, Push nach git.lab.
   Der Hash ändert sich dabei — **Autorschaft und Inhalt bleiben erhalten**.
3. **CFGMON** vor dem nächsten Pull: `git fetch && git reset --hard origin/main`
   (inhaltsgleich, nur neuer Hash).