Thomas Stallinger
9949ca860c
Ergaenzt einen kurzen Hinweis, dass /opt/tuxflotte auf Mint/Casper-Medien nicht automatisch vorhanden ist, sondern erst durch einen casper-bottom-Initrd-Hook vor backend_init() entsteht (siehe tuxflotte-installer, Phase 4 des Self-Service-ISO-Plans) - und Abgrenzung zu backend_postinstall(), das ein anderes, spaeteres Dateisystem anfasst (Ziel-Platte nach der Installation statt Live-Session davor). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
211 lines
3.9 KiB
Markdown
211 lines
3.9 KiB
Markdown
# Tuxflotte Backend API v1
|
|
|
|
## Zweck
|
|
|
|
Die Backend-API definiert die Schnittstelle zwischen dem Tuxflotte-Orchestrator und den distributionsspezifischen Backends.
|
|
|
|
Der Orchestrator kennt keine distributionsabhängigen Details. Er ruft ausschließlich die in diesem Dokument definierten Funktionen auf.
|
|
|
|
Jedes Backend muss diese Schnittstelle implementieren.
|
|
|
|
---
|
|
|
|
# Backend-Verzeichnis
|
|
|
|
Beispiel:
|
|
|
|
```text
|
|
backends/
|
|
├── fedora/
|
|
│ ├── backend.sh
|
|
│ ├── kickstart.tpl
|
|
│ └── README.md
|
|
│
|
|
├── mint/
|
|
│ ├── backend.sh
|
|
│ ├── autoinstall.tpl
|
|
│ └── README.md
|
|
```
|
|
|
|
---
|
|
|
|
# Lebenszyklus
|
|
|
|
Der Orchestrator arbeitet immer in derselben Reihenfolge:
|
|
|
|
```text
|
|
backend_init()
|
|
|
|
↓
|
|
|
|
backend_validate()
|
|
|
|
↓
|
|
|
|
backend_generate_config()
|
|
|
|
↓
|
|
|
|
backend_launch()
|
|
|
|
↓
|
|
|
|
backend_postinstall()
|
|
```
|
|
|
|
Voraussetzung (Mint/Casper): der gesamte obige Zyklus läuft innerhalb der
|
|
gebooteten Live-Session und setzt voraus, dass die Orchestrator-Skripte
|
|
selbst (`/opt/tuxflotte/...`) dort bereits vorhanden sind. Das ist bei
|
|
Casper-basierten Medien kein Selbstläufer — Casper merged `/updates` vom
|
|
Medium nicht automatisch auf das Live-System. Diese Voraussetzung wird
|
|
schon *vor* `backend_init()` durch einen `casper-bottom`-Initrd-Hook
|
|
geschaffen (`tuxflotte-installer/initrd-hooks/casper-bottom/99casperboot`),
|
|
nicht durch diese API. `backend_postinstall()` dagegen fasst ein anderes,
|
|
später existierendes Dateisystem an: das frische Ziel-Root-FS auf der
|
|
echten Platte, nach der Installation, vor dem ersten Reboot.
|
|
|
|
---
|
|
|
|
# Pflichtfunktionen
|
|
|
|
## backend_init()
|
|
|
|
Initialisiert das Backend.
|
|
|
|
Aufgaben:
|
|
|
|
* Backend-Version prüfen
|
|
* benötigte Werkzeuge prüfen
|
|
* Templates laden
|
|
* interne Variablen initialisieren
|
|
|
|
Rückgabe:
|
|
|
|
* 0 = erfolgreich
|
|
* ungleich 0 = Fehler
|
|
|
|
---
|
|
|
|
## backend_validate()
|
|
|
|
Prüft, ob das Runtime Blueprint mit diesem Backend kompatibel ist.
|
|
|
|
Beispiele:
|
|
|
|
* unterstützte Distribution
|
|
* unterstützte Version
|
|
* unterstützte Architektur
|
|
|
|
Rückgabe:
|
|
|
|
* 0 = Profil gültig
|
|
* ungleich 0 = Profil ungültig
|
|
|
|
---
|
|
|
|
## backend_generate_config()
|
|
|
|
Erzeugt die installationsspezifischen Konfigurationsdateien.
|
|
|
|
Beispiele:
|
|
|
|
Fedora:
|
|
|
|
* Kickstart-Datei
|
|
|
|
Ubuntu:
|
|
|
|
* Autoinstall-Konfiguration
|
|
|
|
Debian:
|
|
|
|
* Preseed-Datei
|
|
|
|
Mint:
|
|
|
|
* distributionsabhängige Antwortdatei
|
|
|
|
Ausgabe:
|
|
|
|
Konfigurationsdateien im Laufzeitverzeichnis.
|
|
|
|
---
|
|
|
|
## backend_launch()
|
|
|
|
Startet den nativen Installer.
|
|
|
|
Beispiele:
|
|
|
|
* Anaconda
|
|
* Calamares
|
|
* Debian Installer
|
|
* Subiquity
|
|
|
|
Ab diesem Zeitpunkt übernimmt der Installer der Distribution die eigentliche Installation.
|
|
|
|
---
|
|
|
|
## backend_postinstall()
|
|
|
|
Vorbereitung für den ersten Start.
|
|
|
|
Beispiele:
|
|
|
|
* Provisioning-Agent installieren oder aktivieren
|
|
* Erststart-Konfiguration vorbereiten
|
|
* Registrierung am Provisioning-Server vorbereiten
|
|
|
|
---
|
|
|
|
# Optionale Funktionen
|
|
|
|
Ein Backend kann zusätzliche Funktionen bereitstellen.
|
|
|
|
Beispiele:
|
|
|
|
* backend_upgrade()
|
|
* backend_cleanup()
|
|
* backend_debug()
|
|
|
|
Der Orchestrator verwendet ausschließlich die Pflichtfunktionen.
|
|
|
|
---
|
|
|
|
# Laufzeitdaten
|
|
|
|
Der Orchestrator stellt dem Backend alle benötigten Informationen bereit.
|
|
|
|
Beispiele:
|
|
|
|
* Runtime Blueprint
|
|
* Zielsystem
|
|
* Hardwareinformationen
|
|
* Netzwerk
|
|
* Laufzeitverzeichnis
|
|
* Installationszeitliche Vorgaben der Bereitstellungsvorlage (zum Beispiel Partitionierung, Datenträgerverschlüsselung, Secure-Boot-Pflicht)
|
|
|
|
Diese Vorgaben fließen direkt in `backend_generate_config()` ein. Sie sind kein Bestandteil der Merkmal-Blueprints (siehe `12-feature-blueprint-model.md`), sondern Teil der gewählten Bereitstellungsvorlage selbst.
|
|
|
|
Backends greifen nicht direkt auf andere Module zu.
|
|
|
|
---
|
|
|
|
# Fehlerbehandlung
|
|
|
|
Jede Backend-Funktion liefert einen Rückgabecode.
|
|
|
|
Der Orchestrator entscheidet, ob:
|
|
|
|
* erneut versucht wird,
|
|
* abgebrochen wird,
|
|
* oder der Benutzer eingreifen muss.
|
|
|
|
---
|
|
|
|
# Grundsatz
|
|
|
|
Backends enthalten ausschließlich distributionsspezifische Logik.
|
|
|
|
Der Tuxflotte-Kern bleibt distributionsneutral.
|