Thomas Stallinger fce6e4860c docs: switch provisioning ISO to live medium with auto/interactive boot modes (ADR-0003)

Moves from a Fedora DVD/netinst base (GRUB boots straight into Anaconda
via a static inst.ks= URL, bypassing installer.sh entirely) to a real
live medium. installer.sh runs as an application inside the live
session; backend_launch() starts the native installer explicitly at
the end instead of a boot-time kickstart parameter.

The boot menu offers two entries: a default with a countdown that
leads to an unattended flow, and a manual entry for the branded
interactive flow. The unattended flow is gated on
device.registration_status == "existing" - unknown devices always
fail closed into the interactive enrollment path. Device registration
now documents that this is a condition of registering a device.

Also notes the tension with the installer roadmap's long-term
minimal-medium vision: distribution packages still aren't bundled and
are pulled per install, but the live environment itself makes the
medium larger, accepted for the UX it enables.

Details: architecture/13-live-provisioning-boot.md.

2026-07-18 10:46:46 +02:00

9.0 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.

Dieser Ablauf beschreibt den Interaktiv-Modus. Für bereits registrierte Geräte existiert daneben ein automatisierter Modus, der Bereitstellungsvorlage-Auswahl und Commit-Point-Bestätigung ohne Benutzereingabe durchläuft (siehe 13-live-provisioning-boot.md).

Ablauf

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:

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

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

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

Der Zustand enthält:

TUXFLOTTE_PROVISIONING_CONTINUE=true

oder:

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:

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

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

template.json enthält die vom Benutzer ausgewählte Bereitstellungsvorlage.

Beispiel:

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

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