# Der Nutzlast-Vertrag

XinionOS liefert ein Gerät, das startet, sich prüft und zurückspringt. Was darauf arbeitet, ist die
**Nutzlast** — und dieser Vertrag ist alles, was die beiden voneinander wissen.

Er ist bewusst klein. Je mehr das Betriebssystem über die Nutzlast weiß, desto weniger Produkte
kann es tragen.

## Der Grundsatz: eine Fassung, ein Rückweg

**Die Nutzlast liegt in der Wurzel und wird mit ihr getauscht.** Damit erbt sie den A/B-Wechsel und
den Rücksprung, ohne selbst etwas dafür zu tun.

Das ist die wichtigste Festlegung dieses Dokuments, und sie ist eine Entscheidung gegen eine
naheliegende Alternative: Nutzlast und Betriebssystem **getrennt** zu versionieren. Das klingt
flexibler und erzeugt eine Verträglichkeitsmatrix — welche Nutzlastfassung läuft auf welcher
OS-Fassung —, die gepflegt und geprüft werden muss. Vor allem aber gäbe es **zwei Rücksprünge**,
die zueinander passen müssten.

> **Ein Abbild, eine Fassung, ein Rückweg.** Wer die Nutzlast aktualisieren will, baut ein neues
> Abbild.

## Was die Nutzlast bereitstellt

| Pfad | Pflicht | Zweck |
|---|---|---|
| `/opt/nutzlast/bin/selbstpruefung` | **ja** | Meldet mit Rückgabewert 0, dass die Nutzlast arbeitsfähig ist |
| `/opt/nutzlast/nutzlast.target` | **ja** | systemd-Ziel, unter dem alle Dienste der Nutzlast hängen |
| `/opt/nutzlast/kennung` | **ja** | Name und Fassung, einzeilig — erscheint auf der Statusseite |
| `/opt/nutzlast/bin/einrichten` | nein | Wird bei der Ersteinrichtung einmalig aufgerufen |

## Wie der Selbstprüflauf zusammenspielt

Der Selbstprüflauf des Betriebssystems prüft **seine** Sachen — Wurzel erkennbar, Bestandsbereich
eingehängt und beschreibbar, Statusseite antwortet. Danach ruft er
`/opt/nutzlast/bin/selbstpruefung` auf.

**Fällt einer von beiden durch, gilt der Start als misslungen.** Das ist der ganze Mechanismus: Die
Nutzlast entscheidet über den Rücksprung mit, ohne dass das Betriebssystem wissen muss, woran sie
das erkennt.

Was die Nutzlast dort prüft, ist ihre Sache. Eine Fach-Appliance fragt ihre Datenbank; eine
Anwendungsplattform fragt, ob ihre Dienste bereit sind; ein Proxy prüft, ob er lauscht.

## Was die Nutzlast nicht darf

**Sich selbst aktualisieren.** Kein Dienst, der im Hintergrund neue Fassungen holt. Das umginge
Updatekanal, Signaturprüfung und Rücksprung — also alles, wofür dieses Betriebssystem da ist.

**Zustand außerhalb des Bestandsbereichs ablegen.** Alles Dauerhafte gehört nach `/bestand`. Was in
der Wurzel liegt, ist beim nächsten Fassungswechsel weg — das ist Absicht.

**In die andere Wurzel schreiben.** Die gehört dem Fassungswechsel.

## Drei Beispiele

**Eine Anwendungsplattform** (Helm-Bündel, Kubernetes): Die Nutzlast bringt die Laufzeitumgebung und
das Bündel mit; ihr Selbstprüflauf fragt, ob die Freigabe ausgerollt und erreichbar ist.

**Eine Fach-Appliance mit Wirt-Diensten:** Die Nutzlast bringt ihre Dienste als systemd-Units unter
`nutzlast.target`; ihr Selbstprüflauf fragt Datenbank und Dienste ab.

**Ein Proxy:** Ein einziger Dienst, ein dreizeiliger Selbstprüflauf.

**Keines der drei erfordert eine Änderung am Betriebssystem.** Wenn doch, ist der Vertrag falsch
geschnitten — dann wird er geändert und nicht umgangen.

## Was noch offen ist

* **Wie die Nutzlast ins Abbild kommt.** Als Verzeichnis beim Bau oder als signiertes Paket, das
  das Bauwerkzeug einliest. Zu entscheiden, bevor das zweite Produkt gebaut wird.
* **Die Signatur.** Nutzlast und Abbild müssen gemeinsam signiert und vor dem Umschalten geprüft
  werden.
* **Ob die Statusseite Angaben der Nutzlast anzeigt** — und wenn ja, wie sie sie bekommt, ohne dass
  das Betriebssystem sie versteht.