Thomas Stallinger 8ece25f954 docs: define Merkmal/Blueprint/Bereitstellungsvorlage model (ADR-0002)

Introduces the Merkmal-Backend-Blueprint realization model: a Merkmal
describes one distribution-independent workspace feature, a Blueprint
realizes exactly one Merkmal for exactly one backend (usually an
Ansible role applied post-first-boot via ansible-pull), and a
Bereitstellungsvorlage bundles workspace + backend + org-specific
installation directives (partitioning, encryption, secure boot).

Replaces the old flat profile model (profiles/profile.json/
distribution+version) throughout the provisioning API, data model,
interactive provisioning flow, and device enrollment docs with
templates/Bereitstellungsvorlage terminology. Moves 02-workspace-model.md
and 04-backend-model.md into architecture/, archives the superseded
flat organization-model.md.

2026-07-18 10:45:48 +02:00

8.7 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
  ↓
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