CluPilotCloud/docs/superpowers/specs/2026-08-01-vorlagenbau-design.md

# Vorlagenbau in der Übernahme-Pipeline (`BuildVmTemplate`)

*Entwurf, 1. August 2026*

## Das Loch

`VerifyVmTemplate` **meldet**, dass eine Vorlage fehlt, und baut ausdrücklich
keine. Das war richtig, solange niemand entschieden hatte, was in die goldene
Vorlage gehört — inzwischen ist das entschieden und steht in
`deploy/bootstrap/lib/template.sh`. Damit ist die Übernahme eines Hosts heute an
genau einer Stelle unfertig: der Betreiber muss die Vorlage von Hand bauen oder
von einem anderen Knoten kopieren, sonst bleibt der Lauf bei `verify_vm_template`
stehen.

Das Abnahmeziel ist eine frische Debian-13-Maschine, Host anlegen, zusehen,
`active` — ohne einen Handgriff. Der Vorlagenbau ist der Schritt, der dazwischen
fehlt.

## Die Entscheidung: das vorhandene Skript ausführen, nicht in PHP nachbauen

`template.sh` sind 252 geprüfte Zeilen, die drei Fallen abdecken, die je einen
bezahlten Auftrag gekostet haben. Eine zweite Fassung in PHP wäre genau der
Fehler, den die Wege-Entscheidung vom 1. August vermeiden sollte: zwei
Installationen, die bei jeder Proxmox-Version nachgezogen werden müssen, und die
zweite fällt erst auf, wenn jemand sie benutzt.

Also: **die Datei wortgleich per SSH auf den Host laden und dort ausführen.**
Was heute nur `clupilot-bootstrap.sh` konnte, kann danach die Pipeline — aus
derselben Datei.

## Aufbau

### 1. `deploy/bootstrap/lib/template.sh` — erweitert, nicht kopiert

Fünf Änderungen an der einen Fassung. Der Rettungssystem-Weg erbt sie
automatisch, sollte er je wiederbelebt werden.

**`ensure_image_storage()` — neu.** Auf einem per Debian aufgesetzten Proxmox
ist `local` eine Verzeichnis-Ablage, deren Inhaltsliste standardmäßig **keine
Platten** enthält. `detect_vm_storage()` findet dann nichts und der Bau stirbt,
bevor er anfängt — und `RegisterCapacity` meldete hinterher Kapazität 0. Das
wäre ein Host, der in der Liste fertig aussieht und auf den nie ein Kunde gelegt
werden kann: dieselbe Sorte Fehler wie die fehlende Vorlage, nur leiser.

Die Funktion greift **nur ein, wenn keine Ablage Platten annimmt**:

- Erst `detect_vm_storage()`. Liefert sie etwas, passiert nichts. Ein Host mit
  `local-lvm` oder `local-zfs` kommt also gar nicht erst hierher — die nehmen
  Platten längst, und an `local` wird dort nicht gerührt.
- Sonst: die **vorhandene** Inhaltsliste aus `/etc/pve/storage.cfg` lesen und
  `images` **anhängen**. Eine feste Liste zu schreiben würde löschen, was
  jemand auf diesem Host ergänzt hat.
- Geschrieben wird über **`pvesm set`**, nie in die Datei. `/etc/pve` ist
  pmxcfs; ein von Hand geschriebener Eintrag umgeht Prüfung und Neuladen.

**`check_build_space()` — neu.** Abbild, Arbeitskopie und importierte Platte
sind zusammen ein Vielfaches der Abbildgröße. Ein `df` vorab mit klarer Absage
ist billiger als ein Abbruch nach zwanzig Minuten mitten im `virt-customize`.

**`fetch_cloud_image()` lädt nach `.part`** und benennt erst um, wenn die
SHA512-Summe stimmt. Bisher schrieb sie direkt ans Ziel; ein abgebrochener Lauf
hinterließ eine abgeschnittene Datei, die der nächste wegen `[ ! -f "$_image" ]`
ungeprüft weiterbenutzt hätte.

**`customise_cloud_image()` installiert `cloud-guest-utils`** —
`GrowGuestFilesystem` ruft `growpart` auf, und installiert hat es nie jemand. Es
funktioniert heute, weil Debians Cloud-Abbild es zufällig mitbringt. Fällt es
dort einmal heraus, bekommt jeder Kunde stillschweigend ein Kontingent, das nie
angewendet wird — bemerkt wird das erst, wenn eine Platte voll ist, die laut
Rechnung dreimal so groß sein sollte. `verify_image_contents()` weist es danach
als **vierte Falle** nach. Installieren *und* nachweisen: `ping` war auch
„bringt das System doch mit", und `VM.Monitor` war auch „das gibt es doch".

**`create_proxmox_template()` importiert über `qm set --import-from`** statt
`qm importdisk` mit anschließend geratenem Datenträgernamen. Der bisherige Code
hängte die Platte als `${storage}:vm-${vmid}-disk-0` ein — dieser Name gilt nur
bei **Block**-Speichern. Auf einer Verzeichnis-Ablage heißt der Datenträger
`local:9000/vm-9000-disk-0.qcow2`, und genau diese Ablage ist der Fall, den
`ensure_image_storage()` gerade erst möglich macht. Das Skript hätte die Platte
angelegt und dann unter einem Namen eingehängt, den es dort nicht gibt.
`--import-from` überlässt die Benennung Proxmox, das als einziges weiß, wie sie
auf dieser Ablage lautet.

### 2. `deploy/bootstrap/lib/template-run.sh` — neu, der Treiber

Der einzige Shell-Neubau. Er trägt:

- einen knappen Vorspann mit den vier Helfern, die `template.sh` erwartet
  (`log`, `die`, `http_download`, `http_get`). Bewusst eine eigene, kleine
  Fassung statt `clupilot-bootstrap.sh` anzufassen: das ist der stillgelegte
  Weg, und die Helfer sind curl-Hüllen ohne Entwurfsentscheidung — die 252
  Zeilen mit den Fallen bleiben die eine Fassung, und nur darum ging es.
- die Phasen in Reihe: Platz prüfen → `libguestfs-tools` → Ablage sichern →
  Abbild laden → Aufbau prüfen (Falle 2) → **Arbeitskopie ziehen** → umbauen →
  Inhalt prüfen (Fallen 1, 3, 4) → je VMID Vorlage anlegen → `template: 1`
  nachweisen.
- die Statusdateien.

**Die Arbeitskopie** ist der Grund, warum ein Wiederanlauf nichts erbt: das
geprüfte Abbild bleibt unangetastet liegen, umgebaut wird eine Kopie. Ein
Abbruch mitten im `virt-customize` hinterlässt sonst ein halb umgebautes Abbild,
das der nächste Lauf für fertig heruntergeladen hält.

**Statusprotokoll** im Arbeitsverzeichnis `/var/lib/clupilot/template-build`:

| Datei | Inhalt |
|---|---|
| `state` | `running` \| `ok` \| `failed` |
| `pid` | PID des Treibers |
| `phase` | laufende Phase, für die Fortschrittszeile im Protokoll |
| `note` | Grund im Fehlerfall |
| `build.log` | alles |

### 3. `App\Provisioning\Steps\Host\BuildVmTemplate`

Zwischen `VerifyProxmoxApi` und `VerifyVmTemplate`: bauen, dann prüfen. Vor
`RegisterCapacity`, damit die Ablagenerweiterung schon gewirkt hat, wenn die
Kapazität gezählt wird.

Ablauf je Aufruf:

1. Kein Katalog veröffentlicht → `advance()`. Dieselbe Ausnahme, die
   `VerifyVmTemplate` schon macht: eine Installation, die ihren ersten Host
   übernimmt, bevor sie Pakete veröffentlicht, verlangt keine Vorlage.
2. Welche der verlangten VMIDs melden **nicht** `template: 1`? Keine → `advance()`,
   ohne etwas anzufassen. Die Abkürzung fragt bewusst nach dem Merkmal, nicht
   nach der Existenz: ein abgebrochener Bau hinterlässt eine VM mit der Nummer
   9000, und eine Existenzprüfung sagte dazu „passt".
3. Gebaut wird **nur die Fehlliste**, nie alles Verlangte. `create_proxmox_template`
   räumt eine VMID weg, bevor es sie anlegt — zwei Pakete mit zwei Vorlagen, von
   denen eine steht, hieße die stehende auf dem Weg zu zerstören und bei einem
   Fehlschlag ohne sie dazustehen.
4. Statusdateien lesen. Sie überleben den Lauf, der sie geschrieben hat, also
   entscheidet zuerst: **hat dieser Lauf überhaupt etwas gestartet?** Das sagt
   die Frist im Run-Kontext.

**Status aus einem früheren Lauf** (keine Frist im Kontext):

| `state` | Prozess | Ergebnis |
|---|---|---|
| `running` | lebt | **übernehmen** — `poll(30)`, eigene Frist setzen |
| alles andere | — | Dateien hochladen, `nohup setsid` starten, `poll(30)` |

Ein `ok` von gestern beantwortet keine Frage, die dieser Lauf gestellt hat. Als
eigenes Ergebnis gelesen hieße es „der Bau, den ich angestoßen habe, ist fertig
geworden, ohne zu liefern, worum ich gebeten habe" — und das ist der gewöhnliche
Fall an dem Tag, an dem der Katalog eine zweite Vorlage bekommt. Ein *lebender*
Bau ist die Ausnahme: er baut dasselbe, also wird er übernommen statt daneben
ein zweiter gestartet.

**Status aus diesem Lauf** (Frist gesetzt):

| `state` | Prozess | Ergebnis |
|---|---|---|
| — | — | **`fail`** — der Start hat nicht gegriffen |
| `running` | lebt (`kill -0`) | `poll(30, phase)` |
| `running` | tot | **sofort `fail`** |
| `ok` | — | `fail` — das Skript meldet fertig, die API widerspricht |
| `failed` | — | `fail(note)` mit den letzten Protokollzeilen |

Zeile 3 ist der Punkt, an dem beides schiefgeht, wenn man ihn weglässt: startet
der Schritt neu, obwohl noch ein Treiber läuft, laufen zwei `virt-customize` auf
derselben Datei und beide legen VMID 9000 an. Und pollt er weiter, weil in der
Datei `running` steht, obwohl der Prozess nach einem Neustart weg ist, wartet er
fünfundvierzig Minuten gegen eine Leiche. **„Läuft noch" heißt: der Prozess
lebt** — nicht: in der Datei steht `running`.

Eigene Frist von 45 Minuten im Run-Kontext, `maxDuration()` 3600 darüber, damit
die eigene Frist zuerst greift und nicht der allgemeine Schritt-Zeitablauf —
dieselbe Form wie `RebootIntoPveKernel`.

**Aufgeben beendet erst, dann räumt es auf.** Der Fristablauf trifft einen
Prozess, der noch läuft; nur die Statusdateien zu löschen machte den Schritt
wiederholbar und ließe den alten Bau weiterlaufen — dieselbe Kollision, von der
anderen Seite. Beendet wird die **Prozessgruppe** (`kill -TERM -$P`, dann
`-KILL`), weil der Treiber die meiste Zeit auf ein `virt-customize` wartet, das
sonst allein weitermahlt. Dass die PID zugleich die Prozessgruppe ist, ist der
Grund für `setsid` beim Start — und der Grund, warum das Skript seine PID selbst
per `$$` hinterlegt statt `$!` auf der Startseite: mit `setsid` dazwischen kann
`$!` auf einen Prozess zeigen, den es schon nicht mehr gibt. Der Startbefehl
wartet deshalb bis zu 15 Sekunden auf die Datei, sonst hielte der erste Poll
einen gesunden Bau für tot. Gegen eine wiederverwendete PID prüft der
Abbruch `/proc/$P/cmdline`.

Beim `fail` verschwinden Statusdateien **und** die Frist im Kontext, damit ein
Wiederholen aus der Konsole wieder ein erster Besuch ist; das geprüfte Abbild
bleibt liegen und muss nicht neu geladen werden.

### 4. `ProxmoxClient::isTemplate()` — neu

Zwei Anfragen, weil die falsche Antwort hier **etwas zerstört**: `false` heißt
für `BuildVmTemplate` „Vorlage fehlt", und der Bau fängt mit `qm destroy
--purge` an. „Nicht da" und „konnte nicht fragen" dürfen sich deshalb nicht
ähnlich sehen — und am Rückgabecode sind sie nicht zu unterscheiden: Proxmox
beantwortet die Konfiguration einer nicht vorhandenen VM mit **500**, demselben
Code wie einen Knoten in Not.

Also klärt die **VM-Liste** (`GET /nodes/{node}/qemu`) die Abwesenheit und sonst
nichts: fehlt die VMID in einer erfolgreichen Liste, ist sie wirklich nicht da.
Alles unterhalb einer erfolgreichen Liste **wirft** und landet im
Wiederholungs-Zweig des Aufrufers — die vorhandene Vorlage überlebt. Erst danach
klärt das **Konfigurationsdokument** (`GET …/{vmid}/config`) das Merkmal
`template`.

Benutzt von `VerifyVmTemplate` **und** von `VmTemplateCheck`. Beide prüften nur
`vmExists`, beide stellen dieselbe Frage — die eine bei der Übernahme, die
andere vor dem Verkauf —, und beide hätten eine VM durchgelassen, die zufällig
9000 heißt.

### 5. `PlanVersion::requiredTemplateVmids()` — neu

Dieselbe Fensterlogik stand in `VerifyVmTemplate` und `VmTemplateCheck` und wäre
mit `BuildVmTemplate` zum dritten Mal abgeschrieben worden. Drei Kopien driften,
und die abgedriftete fände ein Kunde.

## Was dieser Entwurf nicht tut

- **`vmbr0` anlegen.** `qm create --net0 virtio,bridge=vmbr0` schreibt nur
  Konfigurationstext und stört sich nicht an einer fehlenden Brücke. Die Brücke
  ist ein eigener offener Punkt in `ConfigureProxmox`.
- **Die Proxmox-Version fixieren.** Eigener offener Punkt.
- **Den Rettungssystem-Weg wiederbeleben.** Er bleibt liegen; er erbt die
  Korrekturen an `template.sh` nur, falls er je zurückkommt.

## Prüfung

Pest, vollständig mit Attrappen, wie der Rest der Pipeline:

- Kein veröffentlichter Katalog → `advance`, nichts hochgeladen.
- Vorhandene echte Vorlage → `advance`, kein Start.
- VM 9000 existiert, ist aber **keine** Vorlage → es wird gebaut.
- Erster Aufruf lädt alle drei Dateien **wortgleich** hoch (Byte für Byte gegen
  die Repo-Dateien geprüft) und startet abgekoppelt → `poll`.
- Zwei Vorlagen verlangt, eine steht → nur die fehlende landet in `env`.
- `running` + lebender Prozess → `poll`, **kein** zweiter Start.
- `running` + toter Prozess → `fail`, nicht `poll`.
- `failed` → `fail` mit dem Grund aus `note`; `state` wird entfernt.
- `ok`, aber `template: 1` fehlt → `fail`.
- Frist überschritten → `fail`, **und** die Prozessgruppe wird beendet.
- Start hinterließ keinen Status → `fail` statt endlos neu zu starten.
- Nach einem `fail` ist die Frist weg, damit „Wiederholen" wirklich neu anfängt.
- Status aus einem früheren Lauf: `ok` → neu bauen; lebendes `running` →
  übernehmen statt danebenstarten.
- `isTemplate`: 502 → **wirft** (nicht „fehlt"); VMID nicht in der Liste →
  `false`; `template: 1` → `true`; gewöhnliche VM mit der Nummer → `false`.
- `VerifyVmTemplate`/`VmTemplateCheck`: eine VM ohne `template: 1` besteht nicht
  mehr.
- **Jeder Befehl, den der Schritt absetzt, geht durch `sh -n`.** Keine andere
  Prüfung führt diese Shell je aus — ein verrutschtes Anführungszeichen käme
  sonst zuerst auf einem echten Host zur Ausführung, und zwar in dem Schritt,
  der VMs zerstört und neu anlegt.

Dazu `sh -n` über alle drei Shell-Dateien, und die awk-Auswertung von
`storage.cfg` gegen eine echte Beispieldatei durchgespielt (`CLUPILOT_STORAGE_CFG`
ist genau dafür überschreibbar).

## Was hier NICHT geprüft ist

Nichts davon lief je gegen einen echten Proxmox-Host. Alle Tests sind Attrappen,
und die Stellen mit dem größten Risiko sind genau die, die eine Attrappe nicht
abbilden kann: `qm set --import-from` auf einer Verzeichnis-Ablage, `virt-customize`
unter PVE 9, `pvesm set` gegen pmxcfs, und ob `nohup setsid` den Bau wirklich
überleben lässt, wenn phpseclib den Kanal schließt. Die erste Übernahme auf
echter Hardware ist die Abnahme, nicht dieser Testlauf.