docs: define interactive provisioning flow and commit point
This commit is contained in:
parent
40d9bc77a6
commit
679eb20e0e
257
architecture/10-interactive-provisioning-flow.md
Normal file
257
architecture/10-interactive-provisioning-flow.md
Normal file
@ -0,0 +1,257 @@
|
|||||||
|
# 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
|
||||||
|
↓
|
||||||
|
Aktivierungscode erfassen
|
||||||
|
↓
|
||||||
|
Provisioning Handshake
|
||||||
|
↓
|
||||||
|
Gerät und Organisation erkennen
|
||||||
|
↓
|
||||||
|
verfügbare Profile anzeigen
|
||||||
|
↓
|
||||||
|
Profil auswählen
|
||||||
|
↓
|
||||||
|
Installationsplan anzeigen
|
||||||
|
↓
|
||||||
|
Installation explizit bestätigen
|
||||||
|
↓
|
||||||
|
Commit Point
|
||||||
|
↓
|
||||||
|
Runtime Blueprint
|
||||||
|
↓
|
||||||
|
Backend
|
||||||
|
↓
|
||||||
|
Native Installation
|
||||||
|
|
||||||
|
|
||||||
|
Also:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
↓
|
||||||
|
Native Installation
|
||||||
|
|
||||||
|
## Runtime-Zustände
|
||||||
|
|
||||||
|
Der interaktive Provisionierungsablauf übergibt seinen Zustand über klar getrennte Runtime-Verzeichnisse unter `/run/tuxflotte/`.
|
||||||
|
|
||||||
|
### 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 Profile.
|
||||||
|
|
||||||
|
### Profilauswahl
|
||||||
|
|
||||||
|
Die Auswahl eines Provisioning-Profils wird unter folgendem Pfad gespeichert:
|
||||||
|
|
||||||
|
```text
|
||||||
|
/run/tuxflotte/assignment/
|
||||||
|
└── profile.json
|
||||||
|
```
|
||||||
|
|
||||||
|
`profile.json` enthält das vom Benutzer ausgewählte Profil.
|
||||||
|
|
||||||
|
Beispiel:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": 1,
|
||||||
|
"profile": {
|
||||||
|
"id": "fedora-workstation",
|
||||||
|
"label": "Fedora Workstation",
|
||||||
|
"distribution": "fedora",
|
||||||
|
"version": "40",
|
||||||
|
"description": "Standard-Workstation-Profil für Fedora.",
|
||||||
|
"ansible_repo": "<repository-url>",
|
||||||
|
"installer": {
|
||||||
|
"type": "kickstart",
|
||||||
|
"url": "<kickstart-url>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Die Profilauswahl darf ausschließlich Profile 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
|
||||||
|
15_server_handshake.sh
|
||||||
|
20_profile_selection.sh
|
||||||
|
25_installation_confirm.sh
|
||||||
|
30_runtime_blueprint.sh
|
||||||
|
40_backend.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 20_profile_selection.sh
|
||||||
|
|
||||||
|
Das Modul:
|
||||||
|
|
||||||
|
- liest `/run/tuxflotte/server/response.json`,
|
||||||
|
- validiert die vom Server gelieferten Profile,
|
||||||
|
- zeigt die verfügbaren Profile an,
|
||||||
|
- erfasst die Auswahl des Benutzers,
|
||||||
|
- speichert ausschließlich ein vom Server geliefertes Profil unter `/run/tuxflotte/assignment/profile.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.
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user