diff --git a/architecture/10-interactive-provisioning-flow.md b/architecture/10-interactive-provisioning-flow.md new file mode 100644 index 0000000..383e12e --- /dev/null +++ b/architecture/10-interactive-provisioning-flow.md @@ -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": "", + "installer": { + "type": "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. +