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.
321 lines
8.7 KiB
Markdown
321 lines
8.7 KiB
Markdown
# F-005 – Interactive Provisioning Flow
|
||
|
||
**Status:** In Arbeit
|
||
|
||
## Zweck
|
||
|
||
F-005 beschreibt den interaktiven Provisionierungsablauf zwischen Netzwerkinitialisierung und dem Beginn der destruktiven Installationsphase.
|
||
|
||
Ziel ist ein vollständig testbarer Provisionierungsprozess, der vor dem Start der eigentlichen Betriebssysteminstallation kontrolliert abgebrochen werden kann.
|
||
|
||
## Ablauf
|
||
|
||
```text
|
||
Boot
|
||
↓
|
||
Netzwerk initialisieren
|
||
↓
|
||
Hardware und Geräteidentität erfassen
|
||
↓
|
||
Enrollment-Autorisierung erfassen
|
||
↓
|
||
Provisioning Handshake
|
||
↓
|
||
Gerät und Organisation erkennen
|
||
↓
|
||
Gerätestatus anzeigen
|
||
↓
|
||
Provisionierung fortsetzen?
|
||
├── nein → kontrollierter Abbruch
|
||
└── ja
|
||
↓
|
||
verfügbare Bereitstellungsvorlagen anzeigen
|
||
↓
|
||
Bereitstellungsvorlage auswählen
|
||
↓
|
||
Installationsplan anzeigen
|
||
↓
|
||
Installation explizit bestätigen
|
||
↓
|
||
Commit Point
|
||
↓
|
||
Runtime Blueprint
|
||
↓
|
||
Backend
|
||
↓
|
||
Native Installation
|
||
```
|
||
|
||
## Runtime-Zustände
|
||
|
||
Der interaktive Provisionierungsablauf übergibt seinen Zustand über klar getrennte Runtime-Verzeichnisse unter `/run/tuxflotte/`.
|
||
|
||
### Enrollment-Autorisierung
|
||
|
||
Die Autorisierung des Provisionierungsvorgangs wird unter folgendem Pfad gespeichert:
|
||
|
||
```text
|
||
/run/tuxflotte/enrollment/
|
||
└── authorization.json
|
||
```
|
||
|
||
`authorization.json` enthält den für den aktuellen Provisionierungsvorgang vorbereiteten Autorisierungszustand.
|
||
|
||
Im aktuellen Bootstrap-Modell wird ein temporärer Aktivierungscode verwendet.
|
||
|
||
Beispiel:
|
||
|
||
```json
|
||
{
|
||
"schema_version": 1,
|
||
"authorization_type": "bootstrap_activation_code",
|
||
"activation_code": "LAB-2026-START"
|
||
}
|
||
```
|
||
|
||
Der Provisioning Handshake besitzt keinen eigenen Fallback-Aktivierungscode.
|
||
|
||
Fehlt eine gültige Enrollment-Autorisierung, muss der Handshake abgebrochen werden.
|
||
|
||
Der Bootstrap-Aktivierungscode ist ein Übergangsmechanismus und wird langfristig durch Benutzeranmeldung oder Enrollment Sessions ersetzt.
|
||
|
||
### Provisionierungsentscheidung
|
||
|
||
Die Entscheidung, ob der interaktive Provisionierungsablauf nach Anzeige des Gerätestatus fortgesetzt werden soll, wird unter folgendem Pfad gespeichert:
|
||
|
||
```text
|
||
/run/tuxflotte/provisioning/
|
||
└── state.env
|
||
```
|
||
|
||
Der Zustand enthält:
|
||
|
||
```bash
|
||
TUXFLOTTE_PROVISIONING_CONTINUE=true
|
||
```
|
||
|
||
oder:
|
||
|
||
```bash
|
||
TUXFLOTTE_PROVISIONING_CONTINUE=false
|
||
```
|
||
|
||
Bei `false` beendet der Orchestrator den Provisionierungsvorgang kontrolliert und erfolgreich.
|
||
|
||
Fehlt die Zustandsdatei oder enthält sie einen unbekannten Wert, muss der Orchestrator den Ablauf mit einem Fehler beenden.
|
||
|
||
|
||
### Aktivierung
|
||
|
||
Die Aktivierungsphase verwendet die bereits bestehende Server-Runtime:
|
||
|
||
```text
|
||
/run/tuxflotte/server/
|
||
├── activation.json
|
||
└── response.json
|
||
```
|
||
|
||
`activation.json` enthält den an den Provisioning-Server gesendeten Aktivierungsrequest.
|
||
|
||
`response.json` enthält die erfolgreiche Antwort des Provisioning-Servers einschließlich Geräteinformationen, Organisation und verfügbarer Bereitstellungsvorlagen.
|
||
|
||
### Auswahl der Bereitstellungsvorlage
|
||
|
||
Die Auswahl einer Bereitstellungsvorlage wird unter folgendem Pfad gespeichert:
|
||
|
||
```text
|
||
/run/tuxflotte/assignment/
|
||
└── template.json
|
||
```
|
||
|
||
`template.json` enthält die vom Benutzer ausgewählte Bereitstellungsvorlage.
|
||
|
||
Beispiel:
|
||
|
||
```json
|
||
{
|
||
"schema_version": 1,
|
||
"template": {
|
||
"id": "schulcomputer-fedora",
|
||
"label": "Schulcomputer (Fedora)",
|
||
"workspace": {
|
||
"id": "schulcomputer",
|
||
"name": "Schulcomputer"
|
||
},
|
||
"backend": {
|
||
"id": "fedora",
|
||
"name": "Fedora",
|
||
"version": "40"
|
||
},
|
||
"is_default": true
|
||
}
|
||
}
|
||
```
|
||
|
||
Die Auswahl darf ausschließlich Bereitstellungsvorlagen verwenden, die in der erfolgreichen Antwort des Provisioning-Servers für den aktuellen Aktivierungsvorgang enthalten sind.
|
||
|
||
### Installationsbestätigung
|
||
|
||
Die explizite Installationsbestätigung wird unter folgendem Pfad gespeichert:
|
||
|
||
```text
|
||
/run/tuxflotte/installation/
|
||
└── state.env
|
||
```
|
||
|
||
Der Zustand besitzt genau eine der folgenden Bedeutungen:
|
||
|
||
```bash
|
||
TUXFLOTTE_INSTALLATION_CONFIRMED=true
|
||
```
|
||
|
||
oder:
|
||
|
||
```bash
|
||
TUXFLOTTE_INSTALLATION_CONFIRMED=false
|
||
```
|
||
|
||
`true` bedeutet, dass der Benutzer den Beginn der destruktiven Installationsphase explizit bestätigt hat.
|
||
|
||
`false` bedeutet, dass der Provisionierungsvorgang vor dem Commit Point kontrolliert beendet werden muss.
|
||
|
||
Fehlt `state.env` oder enthält die Datei keinen gültigen Bestätigungszustand, darf die destruktive Installationsphase nicht gestartet werden.
|
||
|
||
## Fail-Closed-Prinzip
|
||
|
||
Der Übergang über den Commit Point erfolgt nach dem Fail-Closed-Prinzip.
|
||
|
||
Nur der explizite Zustand
|
||
|
||
```bash
|
||
TUXFLOTTE_INSTALLATION_CONFIRMED=true
|
||
```
|
||
|
||
berechtigt den Orchestrator zum Start der nachfolgenden Installationsphase.
|
||
|
||
Jeder andere Zustand führt dazu, dass die Provisionierung vor destruktiven Aktionen beendet wird.
|
||
|
||
Ein fehlender, beschädigter oder unbekannter Runtime-Zustand darf niemals implizit als Installationsbestätigung interpretiert werden.
|
||
|
||
## Orchestrator und Abbruchpfad
|
||
|
||
Der Installer-Orchestrator ist für die Durchsetzung des Commit Points verantwortlich.
|
||
|
||
Das Modul zur Installationsbestätigung erfasst ausschließlich die Entscheidung des Benutzers und speichert den Zustand unter:
|
||
|
||
```text
|
||
/run/tuxflotte/installation/state.env
|
||
```
|
||
|
||
Nach Ausführung des Bestätigungsmoduls muss der Orchestrator den gespeicherten Zustand selbst prüfen.
|
||
|
||
Der Exit-Code des Bestätigungsmoduls allein berechtigt nicht zum Start der destruktiven Installationsphase.
|
||
|
||
Der logische Ablauf ist:
|
||
|
||
```text
|
||
25_installation_confirm.sh
|
||
↓
|
||
Orchestrator liest state.env
|
||
↓
|
||
Zustand gültig?
|
||
├── nein → Provisionierung sicher beenden
|
||
└── ja
|
||
↓
|
||
TUXFLOTTE_INSTALLATION_CONFIRMED
|
||
├── false → kontrollierter Benutzerabbruch
|
||
└── true → Commit Point überschreiten
|
||
↓
|
||
Runtime Blueprint
|
||
↓
|
||
Backend
|
||
↓
|
||
Native Installation
|
||
```
|
||
|
||
### Kontrollierter Benutzerabbruch
|
||
|
||
Wählt der Benutzer den Abbruch, speichert das Bestätigungsmodul:
|
||
|
||
```bash
|
||
TUXFLOTTE_INSTALLATION_CONFIRMED=false
|
||
```
|
||
|
||
Das Bestätigungsmodul wird erfolgreich beendet.
|
||
|
||
Der Orchestrator erkennt den expliziten Abbruchzustand und beendet den Provisionierungsvorgang ebenfalls erfolgreich.
|
||
|
||
Ein kontrollierter Benutzerabbruch ist kein Fehler.
|
||
|
||
Der Benutzer muss darüber informiert werden, dass:
|
||
|
||
- die Installation nicht gestartet wurde,
|
||
- keine destruktiven Änderungen an lokalen Datenträgern vorgenommen wurden,
|
||
- der Provisionierungsvorgang beendet wird.
|
||
|
||
### Ungültiger Bestätigungszustand
|
||
|
||
Fehlt die Zustandsdatei, ist sie nicht lesbar oder enthält sie einen unbekannten Wert, muss der Orchestrator den Provisionierungsvorgang mit einem Fehler beenden.
|
||
|
||
Die destruktive Installationsphase darf in diesem Fall nicht gestartet werden.
|
||
|
||
### Verantwortung des Orchestrators
|
||
|
||
Nur der Orchestrator darf den Übergang vom nicht destruktiven Provisionierungsablauf in die destruktive Installationsphase freigeben.
|
||
|
||
Nachfolgende Module und Backends dürfen nicht davon ausgehen, dass eine vorherige Benutzerinteraktion automatisch eine gültige Installationsbestätigung darstellt.
|
||
|
||
## Module von F-005
|
||
|
||
Der Interactive Provisioning Flow wird durch folgende Module umgesetzt:
|
||
|
||
```text
|
||
05_network.sh
|
||
10_hardware.sh
|
||
12_enrollment_auth.sh
|
||
15_server_handshake.sh
|
||
17_device_status.sh
|
||
20_profile_selection.sh
|
||
25_installation_confirm.sh
|
||
30_runtime_blueprint.sh
|
||
40_backend.sh
|
||
```
|
||
|
||
### 20_profile_selection.sh
|
||
|
||
Der Modulname stammt noch aus dem flachen Profil-Modell und wird erst bei der Installer-Umsetzung (Phase B) an die Bereitstellungsvorlage angepasst.
|
||
|
||
Das Modul:
|
||
|
||
- liest `/run/tuxflotte/server/response.json`,
|
||
- validiert die vom Server gelieferten Bereitstellungsvorlagen,
|
||
- zeigt die verfügbaren Bereitstellungsvorlagen an,
|
||
- erfasst die Auswahl des Benutzers,
|
||
- speichert ausschließlich eine vom Server gelieferte Bereitstellungsvorlage unter `/run/tuxflotte/assignment/template.json`.
|
||
|
||
Das Modul nimmt keine Änderungen an lokalen Datenträgern vor.
|
||
|
||
### 25_installation_confirm.sh
|
||
|
||
Das Modul:
|
||
|
||
- liest das ausgewählte Profil,
|
||
- zeigt eine Zusammenfassung des geplanten Installationsvorgangs,
|
||
- fordert eine explizite Bestätigung an,
|
||
- speichert die Entscheidung unter `/run/tuxflotte/installation/state.env`.
|
||
|
||
Das Modul startet keine Installation und führt keine destruktiven Aktionen aus.
|
||
|
||
### 30_runtime_blueprint.sh
|
||
|
||
Das Modul wird nur nach erfolgreicher Prüfung des Commit Points durch den Orchestrator ausgeführt.
|
||
|
||
Es erzeugt das Runtime Blueprint für den bestätigten Provisionierungsvorgang.
|
||
|
||
### 40_backend.sh
|
||
|
||
Das Modul wird nur nach erfolgreicher Prüfung des Commit Points durch den Orchestrator ausgeführt.
|
||
|
||
Es lädt das zum Runtime Blueprint passende Backend und startet den distributionsspezifischen Installationsprozess.
|
||
|