Thomas Stallinger
8ece25f954
Introduces the Merkmal-Backend-Blueprint realization model: a Merkmal describes one distribution-independent workspace feature, a Blueprint realizes exactly one Merkmal for exactly one backend (usually an Ansible role applied post-first-boot via ansible-pull), and a Bereitstellungsvorlage bundles workspace + backend + org-specific installation directives (partitioning, encryption, secure boot). Replaces the old flat profile model (profiles/profile.json/ distribution+version) throughout the provisioning API, data model, interactive provisioning flow, and device enrollment docs with templates/Bereitstellungsvorlage terminology. Moves 02-workspace-model.md and 04-backend-model.md into architecture/, archives the superseded flat organization-model.md.
200 lines
3.2 KiB
Markdown
200 lines
3.2 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()
|
|
```
|
|
|
|
---
|
|
|
|
# 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.
|