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