Thomas Stallinger 679eb20e0e docs: define interactive provisioning flow and commit point

2026-07-14 10:54:19 +02:00

6.8 KiB

Raw Blame History

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

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:

/run/tuxflotte/assignment/
└── profile.json

profile.json enthält das vom Benutzer ausgewählte Profil.

Beispiel:

{
  "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:

/run/tuxflotte/installation/
└── state.env

Der Zustand besitzt genau eine der folgenden Bedeutungen:

TUXFLOTTE_INSTALLATION_CONFIRMED=true

oder:

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

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:

/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:

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:

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:

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