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>
3.9 KiB
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:
backends/
├── fedora/
│ ├── backend.sh
│ ├── kickstart.tpl
│ └── README.md
│
├── mint/
│ ├── backend.sh
│ ├── autoinstall.tpl
│ └── README.md
Lebenszyklus
Der Orchestrator arbeitet immer in derselben Reihenfolge:
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.