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.
This commit is contained in:
parent
de3d7352df
commit
8ece25f954
@ -44,9 +44,25 @@ Beispiele:
|
||||
- VPN
|
||||
- Monitoring
|
||||
|
||||
## Merkmal
|
||||
|
||||
Eine einzelne fachliche Eigenschaft eines Workspace, distributionsunabhängig benannt.
|
||||
|
||||
Beispiele:
|
||||
|
||||
- browser-brave
|
||||
- office-onlyoffice
|
||||
- guest-session-ephemeral
|
||||
|
||||
Ein Workspace besteht aus einer Menge von Merkmalen.
|
||||
|
||||
## Blueprint
|
||||
|
||||
Die technische Beschreibung eines Workspace.
|
||||
Die technische Umsetzung genau eines Merkmals für genau ein Backend.
|
||||
|
||||
Ein Blueprint ist im Regelfall eine Ansible-Rolle beziehungsweise -Aufgabe, die nach dem ersten Start über den bestehenden Ansible-Pull-Mechanismus angewendet wird.
|
||||
|
||||
Details: `architecture/12-feature-blueprint-model.md`.
|
||||
|
||||
## Runtime Blueprint
|
||||
|
||||
@ -54,9 +70,8 @@ Die zur Installationszeit erzeugte vollständige Zielbeschreibung.
|
||||
|
||||
Sie entsteht aus:
|
||||
|
||||
- Backend
|
||||
- Organization
|
||||
- Workspace
|
||||
- den aufgelösten Blueprints der Merkmale des Workspace für das gewählte Backend
|
||||
- direkten Organization- und Backend-Vorgaben (zum Beispiel Partitionierung, Verschlüsselung)
|
||||
- optional Benutzerkontext
|
||||
|
||||
## Orchestrator
|
||||
|
||||
@ -1,57 +0,0 @@
|
||||
# Workspace Model
|
||||
|
||||
**Status:** Stable
|
||||
|
||||
## Zweck dieses Dokuments
|
||||
|
||||
Dieses Dokument beschreibt den Workspace als zentralen Gegenstand von Tuxflotte.
|
||||
|
||||
Es definiert seine Aufgabe innerhalb der Plattform und beschreibt seine Verantwortung sowie seine Abgrenzung zu den übrigen Komponenten der Architektur.
|
||||
|
||||
---
|
||||
|
||||
## Motivation
|
||||
|
||||
Benutzende erfüllen unterschiedliche Aufgaben und übernehmen unterschiedliche Rollen.
|
||||
|
||||
Daraus ergeben sich unterschiedliche Anforderungen an ihren Arbeitsplatz.
|
||||
|
||||
**Ein Workspace beschreibt die Anforderungen, die sich aus einer bestimmten Aufgabe oder Rolle der Benutzenden ergeben.**
|
||||
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Der Workspace ist der zentrale Gegenstand von Tuxflotte.
|
||||
|
||||
Er beschreibt den gewünschten Zielzustand eines Linux-Arbeitsplatzes unabhängig von dessen technischer Umsetzung.
|
||||
|
||||
Ein Workspace definiert, welche Eigenschaften ein Arbeitsplatz besitzen soll. Er beschreibt den gewünschten Zielzustand, der durch die weiteren Komponenten der Plattform umgesetzt wird.
|
||||
|
||||
---
|
||||
|
||||
## Verantwortungsbereich
|
||||
|
||||
Ein Workspace beschreibt beispielsweise
|
||||
|
||||
- den Zweck eines Arbeitsplatzes,
|
||||
- die Zielgruppe,
|
||||
- die erforderlichen Funktionen,
|
||||
- die benötigte Software,
|
||||
- optionale Erweiterungen,
|
||||
- Sicherheitsanforderungen sowie
|
||||
- organisatorische Anforderungen.
|
||||
|
||||
Der Workspace beschreibt den gewünschten Zielzustand eines Arbeitsplatzes.
|
||||
|
||||
Die technische Umsetzung dieses Zielzustands erfolgt durch die weiteren Komponenten der Plattform.
|
||||
|
||||
---
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Der Workspace bildet die Grundlage jeder Bereitstellung.
|
||||
|
||||
Er beschreibt den gewünschten Zielzustand eines Linux-Arbeitsplatzes.
|
||||
|
||||
Alle weiteren Komponenten von Tuxflotte arbeiten darauf hin, diesen Zielzustand auf einem Zielsystem bereitzustellen.
|
||||
@ -1,55 +0,0 @@
|
||||
# Backend Model
|
||||
|
||||
**Status:** Stable
|
||||
|
||||
## Zweck dieses Dokuments
|
||||
|
||||
Dieses Dokument beschreibt das Backend als distributionsspezifische Umsetzung der Workspaces von Tuxflotte.
|
||||
|
||||
Es definiert seine Aufgabe innerhalb der Plattform und beschreibt seine Verantwortung sowie seine Abgrenzung zu den übrigen Komponenten der Architektur.
|
||||
|
||||
---
|
||||
|
||||
## Motivation
|
||||
|
||||
Die Linux-Welt zeichnet sich durch ihre Vielfalt aus.
|
||||
|
||||
Unterschiedliche Distributionen verfolgen unterschiedliche Ziele und besitzen eigene Stärken. Sie unterscheiden sich beispielsweise in ihrer Systemarchitektur, den Paketformaten, den Desktopumgebungen oder ihren Veröffentlichungsmodellen.
|
||||
|
||||
Diese Vielfalt ist eine Stärke des Linux-Ökosystems.
|
||||
|
||||
Tuxflotte respektiert diese Vielfalt und bewahrt sie. Anstatt Distributionen zu vereinheitlichen, kapselt die Plattform distributionsspezifische Unterschiede bewusst in Backends.
|
||||
|
||||
Dadurch können identische Workspaces auf unterschiedlichen Linux-Distributionen bereitgestellt werden.
|
||||
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Ein Backend beschreibt die distributionsspezifische Umsetzung eines Workspace unter Berücksichtigung der organisatorischen Rahmenbedingungen.
|
||||
|
||||
Es übersetzt die fachlichen Anforderungen in distributionsspezifische Installationsdaten und nutzt dabei die nativen Installationsmechanismen der jeweiligen Distribution.
|
||||
|
||||
---
|
||||
|
||||
## Verantwortungsbereich
|
||||
|
||||
Ein Backend beschreibt beispielsweise
|
||||
|
||||
- die Zuordnung fachlicher Funktionen zu distributionsspezifischen Paketen,
|
||||
- distributionsspezifische Konfigurationen,
|
||||
- die Erstellung distributionsspezifischer Installationsdaten,
|
||||
- die Anbindung an native Installationswerkzeuge sowie
|
||||
- distributionsspezifische Besonderheiten.
|
||||
|
||||
Das Backend beschreibt die technische Umsetzung eines Workspace.
|
||||
|
||||
Die fachliche Beschreibung eines Arbeitsplatzes erfolgt durch den Workspace. Die organisatorischen Rahmenbedingungen werden durch die Organization beschrieben.
|
||||
|
||||
---
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Das Backend verbindet die distributionsunabhängigen Modelle von Tuxflotte mit den nativen Installationsmechanismen einer Linux-Distribution.
|
||||
|
||||
Dadurch bleibt der Kern von Tuxflotte distributionsneutral, während gleichzeitig die Vielfalt des Linux-Ökosystems vollständig erhalten bleibt.
|
||||
36
adr/0002-blueprint-merkmal-backend-realisierung.md
Normal file
36
adr/0002-blueprint-merkmal-backend-realisierung.md
Normal file
@ -0,0 +1,36 @@
|
||||
# ADR-0002: Blueprint als Merkmal-Backend-Realisierung über Ansible
|
||||
|
||||
**Status:** Beschlossen
|
||||
**Datum:** 17.07.2026
|
||||
|
||||
## Kontext
|
||||
|
||||
Der Begriff „Blueprint" war im Glossar bisher nur grob als „technische Beschreibung eines Workspace" definiert.
|
||||
|
||||
Mit wachsender Anzahl an Workspaces (zum Beispiel Schulcomputer, Entwickler) und Backends (Fedora, Linux Mint) musste geklärt werden, wie einzelne fachliche Merkmale eines Workspace unabhängig von der gewählten Distribution wiederverwendbar umgesetzt werden können, ohne dass jede Kombination aus Workspace und Backend eigenständig gepflegt werden muss.
|
||||
|
||||
Zusätzlich musste geklärt werden, ob diese Umsetzung zur Installationszeit (nativer Installer, Kickstart/Autoinstall) oder nach dem ersten Start (Ansible) erfolgen soll.
|
||||
|
||||
## Entscheidung
|
||||
|
||||
Ein Blueprint beschreibt die technische Umsetzung genau eines Merkmals für genau ein Backend.
|
||||
|
||||
Ein Blueprint ist im Regelfall eine Ansible-Rolle beziehungsweise -Aufgabe und wird nach dem ersten Start über den bestehenden Ansible-Pull-Mechanismus angewendet.
|
||||
|
||||
Der native Installer bleibt dadurch unabhängig von Workspace-Merkmalen. Er stellt lediglich das Basissystem sowie die Voraussetzungen für den Ansible-Pull-Mechanismus bereit (Netzwerk, Registrierung, Ansible-Repository).
|
||||
|
||||
Eigenschaften, die ausschließlich zur Installationszeit festgelegt werden können – insbesondere Partitionierung, Festplattenverschlüsselung sowie Secure-Boot- und TPM-Bindung – sind kein Bestandteil eines Blueprints. Sie werden als direkte Vorgabe der gewählten Bereitstellungsvorlage an `backend_generate_config()` übergeben.
|
||||
|
||||
## Konsequenzen
|
||||
|
||||
Für jedes Merkmal wird je unterstütztem Backend ein eigener Blueprint gepflegt.
|
||||
|
||||
Neue Merkmale erfordern Blueprints für alle bestehenden Backends. Neue Backends erfordern Blueprints für alle bestehenden Merkmale. Workspace-Definitionen selbst bleiben davon unberührt.
|
||||
|
||||
Der native Installer benötigt keine Kenntnis einzelner Workspace-Merkmale.
|
||||
|
||||
Workspace-Merkmale, die eine Änderung der Partitionierung oder andere installationszeitliche Eingriffe erfordern würden, sind mit diesem Modell nicht darstellbar und müssen stattdessen als Vorgabe der Bereitstellungsvorlage modelliert werden.
|
||||
|
||||
Der Glossar-Eintrag „Blueprint" wird entsprechend präzisiert.
|
||||
|
||||
Details zum Merkmal- und Blueprint-Modell: `architecture/12-feature-blueprint-model.md`.
|
||||
@ -46,6 +46,6 @@ Hardware-Fingerprint
|
||||
↓
|
||||
Geräteregistrierung oder Wiedererkennung
|
||||
↓
|
||||
Profil- beziehungsweise Workspace-Zuordnung
|
||||
Bereitstellungsvorlage-Zuordnung
|
||||
↓
|
||||
Runtime Blueprint
|
||||
|
||||
@ -0,0 +1,72 @@
|
||||
# Organization Model
|
||||
|
||||
**Status:** Stable
|
||||
**Datum:** 17.07.2026
|
||||
|
||||
## Zweck dieses Dokuments
|
||||
|
||||
Dieses Dokument beschreibt die Organization als organisatorischen Rahmen für die Bereitstellung von Workspaces.
|
||||
|
||||
Es definiert ihre Aufgabe innerhalb der Plattform und beschreibt ihre Verantwortung sowie ihre Abgrenzung zu den übrigen Komponenten der Architektur.
|
||||
|
||||
---
|
||||
|
||||
## Motivation
|
||||
|
||||
Workspaces beschreiben den gewünschten Arbeitsplatz.
|
||||
|
||||
Unterschiedliche Organisationen stellen jedoch unterschiedliche Anforderungen an die Bereitstellung desselben Workspace.
|
||||
|
||||
So kann ein Workspace beispielsweise auf einem einer Person fest zugeordneten Gerät oder auf einem gemeinsam genutzten Gerät bereitgestellt werden.
|
||||
|
||||
Die Organization beschreibt die organisatorischen Rahmenbedingungen, unter denen Workspaces bereitgestellt werden.
|
||||
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Die Organization beschreibt die organisatorischen Rahmenbedingungen, unter denen Workspaces bereitgestellt werden.
|
||||
|
||||
Sie ergänzt den Workspace um organisationsspezifische Anforderungen, die unabhängig vom eigentlichen Arbeitsplatz gelten.
|
||||
|
||||
Dadurch können identische Workspaces in unterschiedlichen Organisationen unter jeweils passenden Rahmenbedingungen bereitgestellt werden.
|
||||
|
||||
---
|
||||
|
||||
## Verantwortungsbereich
|
||||
|
||||
Eine Organization beschreibt beispielsweise
|
||||
|
||||
- organisatorische Richtlinien,
|
||||
- organisationsweite Sicherheitsanforderungen,
|
||||
- Standardkonfigurationen,
|
||||
- Anforderungen an Authentifizierung und Identitätsmanagement,
|
||||
- Zertifikate,
|
||||
- Softwarequellen,
|
||||
- Netzwerkanforderungen,
|
||||
- Branding sowie
|
||||
- Rahmenbedingungen für die Nutzung von Geräten.
|
||||
|
||||
Die Organization beschreibt den organisatorischen Rahmen der Bereitstellung.
|
||||
|
||||
Die technische Umsetzung dieser Rahmenbedingungen erfolgt durch die weiteren Komponenten der Plattform.
|
||||
|
||||
### Installationszeitliche Sicherheitsvorgaben
|
||||
|
||||
Vorgaben, die nur zur Installationszeit umgesetzt werden können, beispielsweise
|
||||
|
||||
- Datenträgerverschlüsselung,
|
||||
- Partitionierungsvorgaben sowie
|
||||
- Secure-Boot- beziehungsweise TPM-Pflicht,
|
||||
|
||||
werden nicht über Workspace-Merkmale beziehungsweise Blueprints umgesetzt (siehe `12-feature-blueprint-model.md`), sondern direkt als Vorgabe der gewählten Bereitstellungsvorlage an das Backend übergeben (siehe `06-backend-api.md`, `08-provisioning-api.md`).
|
||||
|
||||
Diese Vorgaben gelten je Bereitstellungsvorlage, nicht einheitlich für die gesamte Organisation — eine Organisation kann mehrere Bereitstellungsvorlagen mit unterschiedlichen Sicherheitsanforderungen anbieten (zum Beispiel eine unverschlüsselte Vorlage für Schulcomputer und eine verschlüsselungspflichtige für Entwickler-Notebooks).
|
||||
|
||||
---
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Die Organization ergänzt den Workspace um organisationsspezifische Rahmenbedingungen.
|
||||
|
||||
Gemeinsam beschreiben Workspace und Organization die fachliche Grundlage für die Bereitstellung eines Linux-Workspaces.
|
||||
@ -0,0 +1,55 @@
|
||||
# Backend Model
|
||||
|
||||
**Status:** Stable
|
||||
|
||||
## Zweck dieses Dokuments
|
||||
|
||||
Dieses Dokument beschreibt das Backend als distributionsspezifische Umsetzung der Workspaces von Tuxflotte.
|
||||
|
||||
Es definiert seine Aufgabe innerhalb der Plattform und beschreibt seine Verantwortung sowie seine Abgrenzung zu den übrigen Komponenten der Architektur.
|
||||
|
||||
---
|
||||
|
||||
## Motivation
|
||||
|
||||
Die Linux-Welt zeichnet sich durch ihre Vielfalt aus.
|
||||
|
||||
Unterschiedliche Distributionen verfolgen unterschiedliche Ziele und besitzen eigene Stärken. Sie unterscheiden sich beispielsweise in ihrer Systemarchitektur, den Paketformaten, den Desktopumgebungen oder ihren Veröffentlichungsmodellen.
|
||||
|
||||
Diese Vielfalt ist eine Stärke des Linux-Ökosystems.
|
||||
|
||||
Tuxflotte respektiert diese Vielfalt und bewahrt sie. Anstatt Distributionen zu vereinheitlichen, kapselt die Plattform distributionsspezifische Unterschiede bewusst in Backends.
|
||||
|
||||
Dadurch können identische Workspaces auf unterschiedlichen Linux-Distributionen bereitgestellt werden.
|
||||
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Ein Backend beschreibt die distributionsspezifische Umsetzung eines Workspace unter Berücksichtigung der organisatorischen Rahmenbedingungen.
|
||||
|
||||
Es übersetzt die fachlichen Anforderungen in distributionsspezifische Installationsdaten und nutzt dabei die nativen Installationsmechanismen der jeweiligen Distribution.
|
||||
|
||||
---
|
||||
|
||||
## Verantwortungsbereich
|
||||
|
||||
Ein Backend beschreibt beispielsweise
|
||||
|
||||
- die Zuordnung fachlicher Funktionen zu distributionsspezifischen Paketen,
|
||||
- distributionsspezifische Konfigurationen,
|
||||
- die Erstellung distributionsspezifischer Installationsdaten,
|
||||
- die Anbindung an native Installationswerkzeuge sowie
|
||||
- distributionsspezifische Besonderheiten.
|
||||
|
||||
Das Backend beschreibt die technische Umsetzung eines Workspace.
|
||||
|
||||
Die fachliche Beschreibung eines Arbeitsplatzes erfolgt durch den Workspace. Die organisatorischen Rahmenbedingungen werden durch die Organization beschrieben.
|
||||
|
||||
---
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Das Backend verbindet die distributionsunabhängigen Modelle von Tuxflotte mit den nativen Installationsmechanismen einer Linux-Distribution.
|
||||
|
||||
Dadurch bleibt der Kern von Tuxflotte distributionsneutral, während gleichzeitig die Vielfalt des Linux-Ökosystems vollständig erhalten bleibt.
|
||||
@ -77,7 +77,7 @@ Rückgabe:
|
||||
|
||||
## backend_validate()
|
||||
|
||||
Prüft, ob das Profil mit diesem Backend kompatibel ist.
|
||||
Prüft, ob das Runtime Blueprint mit diesem Backend kompatibel ist.
|
||||
|
||||
Beispiele:
|
||||
|
||||
@ -167,11 +167,14 @@ Der Orchestrator stellt dem Backend alle benötigten Informationen bereit.
|
||||
|
||||
Beispiele:
|
||||
|
||||
* ausgewähltes Profil
|
||||
* Runtime Blueprint
|
||||
* Zielsystem
|
||||
* Hardwareinformationen
|
||||
* Netzwerk
|
||||
* Laufzeitverzeichnis
|
||||
* Installationszeitliche Vorgaben der Bereitstellungsvorlage (zum Beispiel Partitionierung, Datenträgerverschlüsselung, Secure-Boot-Pflicht)
|
||||
|
||||
Diese Vorgaben fließen direkt in `backend_generate_config()` ein. Sie sind kein Bestandteil der Merkmal-Blueprints (siehe `12-feature-blueprint-model.md`), sondern Teil der gewählten Bereitstellungsvorlage selbst.
|
||||
|
||||
Backends greifen nicht direkt auf andere Module zu.
|
||||
|
||||
|
||||
@ -87,7 +87,7 @@ Bei einer erneuten erfolgreichen Aktivierung desselben Geräts bleibt die intern
|
||||
|
||||
### Response
|
||||
|
||||
Bei erfolgreicher Aktivierung antwortet der Provisioning-Server mit dem registrierten Gerät, der zugeordneten Organisation und den verfügbaren Provisioning-Profilen.
|
||||
Bei erfolgreicher Aktivierung antwortet der Provisioning-Server mit dem registrierten Gerät, der zugeordneten Organisation und den verfügbaren Bereitstellungsvorlagen.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -104,18 +104,20 @@ Bei erfolgreicher Aktivierung antwortet der Provisioning-Server mit dem registri
|
||||
"organization_id": "<organization-uuid>",
|
||||
"name": "Default Lab"
|
||||
},
|
||||
"profiles": [
|
||||
"templates": [
|
||||
{
|
||||
"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>"
|
||||
}
|
||||
"id": "schulcomputer-fedora",
|
||||
"label": "Schulcomputer (Fedora)",
|
||||
"workspace": {
|
||||
"id": "schulcomputer",
|
||||
"name": "Schulcomputer"
|
||||
},
|
||||
"backend": {
|
||||
"id": "fedora",
|
||||
"name": "Fedora",
|
||||
"version": "40"
|
||||
},
|
||||
"is_default": true
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -131,7 +133,9 @@ Der Wert `existing` bedeutet, dass ein bereits bekanntes Device anhand seines Ha
|
||||
|
||||
`device.hardware_snapshot_id` referenziert den für diesen Aktivierungsvorgang erzeugten Hardware-Snapshot.
|
||||
|
||||
Der Aktivierungscode bestimmt die zugeordnete Organisation und die für den Provisionierungsvorgang verfügbaren Profile.
|
||||
Der Aktivierungscode bestimmt die zugeordnete Organisation und die für den Provisionierungsvorgang verfügbaren Bereitstellungsvorlagen.
|
||||
|
||||
Jede Bereitstellungsvorlage referenziert genau einen Workspace und genau ein Backend. Höchstens eine Bereitstellungsvorlage je Organisation trägt `is_default: true`.
|
||||
|
||||
### Fehlerantwort
|
||||
|
||||
@ -144,3 +148,45 @@ Ist der Aktivierungscode ungültig, antwortet der Provisioning-Server mit:
|
||||
"message": "Der Aktivierungscode ist ungültig."
|
||||
}
|
||||
```
|
||||
|
||||
## Auflösung einer Bereitstellungsvorlage
|
||||
|
||||
### Endpoint
|
||||
|
||||
POST /api/v1/templates/{template_id}/resolve
|
||||
|
||||
### Zweck
|
||||
|
||||
Der Endpoint löst eine vom Benutzer gewählte Bereitstellungsvorlage zum vollständigen Runtime Blueprint auf. Erst mit diesem Aufruf endet die Provisioning API und beginnt der in `06-backend-api.md` beschriebene Backend-Lebenszyklus.
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"device_id": "<device-uuid>"
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"runtime_blueprint": {
|
||||
"workspace_id": "schulcomputer",
|
||||
"backend_id": "fedora",
|
||||
"blueprints": [
|
||||
{ "merkmal": "guest-session-ephemeral", "ansible_role": "guest-session" },
|
||||
{ "merkmal": "browser-brave", "ansible_role": "brave-fedora" }
|
||||
],
|
||||
"installation_directives": {
|
||||
"disk_encryption": false,
|
||||
"partitioning": "default"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`runtime_blueprint.blueprints` enthält die für jedes Merkmal des Workspace gegen das gewählte Backend aufgelöste Ansible-Rolle (siehe `12-feature-blueprint-model.md`).
|
||||
|
||||
`runtime_blueprint.installation_directives` enthält die installationszeitlichen Vorgaben der gewählten Bereitstellungsvorlage, die nicht Bestandteil eines Blueprints sind (siehe `03-organization-model.md`, `12-feature-blueprint-model.md`).
|
||||
|
||||
@ -14,11 +14,17 @@ Die konkrete SQL-Implementierung und das Migrationssystem werden getrennt von di
|
||||
- Network Interface
|
||||
- Storage Device
|
||||
- Workspace
|
||||
- Merkmal
|
||||
- Backend
|
||||
- Blueprint
|
||||
- Bereitstellungsvorlage
|
||||
- Assignment
|
||||
- Activation Code
|
||||
- Network Profile
|
||||
- Secret Reference
|
||||
|
||||
`Network Profile` und `Secret Reference` sind weiterhin nur benannt, aber fachlich noch nicht spezifiziert — das bleibt bewusst außerhalb des aktuellen Arbeitsschritts (Provisioning-Server-Datenmodell für Workspace/Merkmal/Backend/Blueprint/Bereitstellungsvorlage).
|
||||
|
||||
## Organization
|
||||
|
||||
Eine Organization beschreibt eine organisatorische Einheit innerhalb der Tuxflotte-Plattform.
|
||||
@ -35,7 +41,9 @@ Attribute:
|
||||
Beziehungen:
|
||||
|
||||
- besitzt mehrere Devices
|
||||
- besitzt mehrere Workspaces
|
||||
- besitzt optional eigene Workspaces (zusätzlich zu global bereitgestellten Workspaces, siehe Workspace)
|
||||
- besitzt mehrere Bereitstellungsvorlagen
|
||||
- besitzt mehrere Activation Codes
|
||||
- besitzt mehrere Network Profiles
|
||||
- referenziert Secrets
|
||||
|
||||
@ -131,6 +139,145 @@ Beziehungen:
|
||||
|
||||
- gehört zu genau einem Hardware Snapshot
|
||||
|
||||
## Workspace
|
||||
|
||||
Ein Workspace beschreibt einen distributionsunabhängigen Arbeitsplatz-Zielzustand aus einer Menge von Merkmalen (siehe `02-workspace-model.md`).
|
||||
|
||||
Ein Workspace steht zunächst global bereit. Eine Organization kann zusätzlich eigene Workspaces definieren.
|
||||
|
||||
Attribute:
|
||||
|
||||
- id
|
||||
- organization_id (optional; NULL bedeutet global bereitgestellt)
|
||||
- key
|
||||
- name
|
||||
- description
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- gehört optional zu genau einer Organization
|
||||
- besteht aus mehreren Merkmalen
|
||||
- wird in mehreren Bereitstellungsvorlagen referenziert
|
||||
|
||||
## Merkmal
|
||||
|
||||
Ein Merkmal ist eine einzelne fachliche Eigenschaft eines Workspace, distributionsunabhängig benannt (siehe `12-feature-blueprint-model.md`).
|
||||
|
||||
Attribute:
|
||||
|
||||
- id
|
||||
- key
|
||||
- name
|
||||
- description
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- gehört zu mehreren Workspaces
|
||||
- besitzt je Backend höchstens einen Blueprint
|
||||
|
||||
## Backend
|
||||
|
||||
Ein Backend beschreibt die distributionsspezifische Umsetzung eines Workspace (siehe `04-backend-model.md`).
|
||||
|
||||
Attribute:
|
||||
|
||||
- id
|
||||
- key
|
||||
- name
|
||||
- installer_type (zum Beispiel kickstart, autoinstall, calamares, preseed)
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- besitzt Blueprints für Merkmale
|
||||
- wird in mehreren Bereitstellungsvorlagen referenziert
|
||||
|
||||
## Blueprint
|
||||
|
||||
Ein Blueprint beschreibt die technische Umsetzung genau eines Merkmals für genau ein Backend (siehe `12-feature-blueprint-model.md`).
|
||||
|
||||
Attribute:
|
||||
|
||||
- id
|
||||
- merkmal_id
|
||||
- backend_id
|
||||
- ansible_role
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- gehört zu genau einem Merkmal
|
||||
- gehört zu genau einem Backend
|
||||
|
||||
Constraints:
|
||||
|
||||
- je Merkmal und Backend existiert höchstens ein Blueprint
|
||||
|
||||
## Bereitstellungsvorlage
|
||||
|
||||
Eine Bereitstellungsvorlage beschreibt eine von einer Organization vorkonfigurierte Kombination aus Workspace und Backend, einschließlich der installationszeitlichen Vorgaben, die kein Bestandteil eines Blueprints sind (siehe `03-organization-model.md`, `12-feature-blueprint-model.md`).
|
||||
|
||||
Attribute:
|
||||
|
||||
- id
|
||||
- organization_id
|
||||
- workspace_id
|
||||
- backend_id
|
||||
- label
|
||||
- is_default
|
||||
- disk_encryption
|
||||
- partitioning
|
||||
- secure_boot_required
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- gehört zu genau einer Organization
|
||||
- referenziert genau einen Workspace
|
||||
- referenziert genau ein Backend
|
||||
|
||||
Constraints:
|
||||
|
||||
- höchstens eine Bereitstellungsvorlage je Organization mit `is_default = true`
|
||||
|
||||
## Assignment
|
||||
|
||||
Ein Assignment beschreibt die konkrete Zuordnung eines Device zu der Bereitstellungsvorlage, mit der es provisioniert wurde.
|
||||
|
||||
Attribute:
|
||||
|
||||
- id
|
||||
- device_id
|
||||
- bereitstellungsvorlage_id
|
||||
- created_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- gehört zu genau einem Device
|
||||
- referenziert genau eine Bereitstellungsvorlage
|
||||
|
||||
Constraints:
|
||||
|
||||
- ein Device besitzt höchstens ein Assignment
|
||||
|
||||
## Activation Code
|
||||
|
||||
Ein Activation Code autorisiert den initialen Provisionierungsvorgang eines Geräts und bestimmt die zugeordnete Organization (siehe `08-provisioning-api.md`, `11-device-enrollment.md`).
|
||||
|
||||
Der Activation Code ist laut `11-device-enrollment.md` ein Übergangsmechanismus und wird langfristig durch Enrollment Sessions ersetzt.
|
||||
|
||||
Attribute:
|
||||
|
||||
- code
|
||||
- organization_id
|
||||
- active
|
||||
- created_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- gehört zu genau einer Organization
|
||||
|
||||
## Relationales Schema v1
|
||||
|
||||
### organizations
|
||||
@ -220,6 +367,147 @@ Beziehungen:
|
||||
|
||||
- hardware_snapshot_id referenziert hardware_snapshots.id
|
||||
|
||||
### workspaces
|
||||
|
||||
Spalten:
|
||||
|
||||
- id
|
||||
- organization_id (nullable)
|
||||
- key
|
||||
- name
|
||||
- description
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- organization_id referenziert organizations.id (optional)
|
||||
|
||||
Constraints:
|
||||
|
||||
- (organization_id, key) ist eindeutig
|
||||
|
||||
### merkmale
|
||||
|
||||
Spalten:
|
||||
|
||||
- id
|
||||
- key
|
||||
- name
|
||||
- description
|
||||
|
||||
Constraints:
|
||||
|
||||
- key ist eindeutig
|
||||
|
||||
### workspace_merkmale
|
||||
|
||||
Spalten:
|
||||
|
||||
- workspace_id
|
||||
- merkmal_id
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- workspace_id referenziert workspaces.id
|
||||
- merkmal_id referenziert merkmale.id
|
||||
|
||||
Constraints:
|
||||
|
||||
- (workspace_id, merkmal_id) ist Primärschlüssel
|
||||
|
||||
### backends
|
||||
|
||||
Spalten:
|
||||
|
||||
- id
|
||||
- key
|
||||
- name
|
||||
- installer_type
|
||||
|
||||
Constraints:
|
||||
|
||||
- key ist eindeutig
|
||||
|
||||
### blueprints
|
||||
|
||||
Spalten:
|
||||
|
||||
- id
|
||||
- merkmal_id
|
||||
- backend_id
|
||||
- ansible_role
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- merkmal_id referenziert merkmale.id
|
||||
- backend_id referenziert backends.id
|
||||
|
||||
Constraints:
|
||||
|
||||
- (merkmal_id, backend_id) ist eindeutig
|
||||
|
||||
### bereitstellungsvorlagen
|
||||
|
||||
Spalten:
|
||||
|
||||
- id
|
||||
- organization_id
|
||||
- workspace_id
|
||||
- backend_id
|
||||
- label
|
||||
- is_default
|
||||
- disk_encryption
|
||||
- partitioning
|
||||
- secure_boot_required
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- organization_id referenziert organizations.id
|
||||
- workspace_id referenziert workspaces.id
|
||||
- backend_id referenziert backends.id
|
||||
|
||||
Constraints:
|
||||
|
||||
- höchstens eine Zeile je organization_id mit is_default = true (partieller Unique-Index)
|
||||
|
||||
### assignments
|
||||
|
||||
Spalten:
|
||||
|
||||
- id
|
||||
- device_id
|
||||
- bereitstellungsvorlage_id
|
||||
- created_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- device_id referenziert devices.id
|
||||
- bereitstellungsvorlage_id referenziert bereitstellungsvorlagen.id
|
||||
|
||||
Constraints:
|
||||
|
||||
- device_id ist eindeutig
|
||||
|
||||
### activation_codes
|
||||
|
||||
Spalten:
|
||||
|
||||
- code
|
||||
- organization_id
|
||||
- active
|
||||
- created_at
|
||||
|
||||
Beziehungen:
|
||||
|
||||
- organization_id referenziert organizations.id
|
||||
|
||||
Constraints:
|
||||
|
||||
- code ist Primärschlüssel
|
||||
|
||||
## Beziehungskonsequenzen
|
||||
|
||||
Wird eine Organization gelöscht, dürfen zugehörige Devices nicht implizit mitgelöscht werden.
|
||||
@ -228,12 +516,29 @@ Wird ein Device gelöscht, werden zugehörige Hardware Snapshots mitgelöscht.
|
||||
|
||||
Wird ein Hardware Snapshot gelöscht, werden zugehörige Network Interfaces und Storage Devices automatisch mitgelöscht.
|
||||
|
||||
Wird eine Organization gelöscht, dürfen ihre Bereitstellungsvorlagen und Activation Codes nicht implizit erhalten bleiben — sie verlieren mit der Organization ihre Grundlage.
|
||||
|
||||
Wird ein Workspace, ein Backend oder ein Merkmal gelöscht, das noch von einer Bereitstellungsvorlage beziehungsweise einem Blueprint referenziert wird, muss das gesperrt werden, um Bereitstellungsvorlagen nicht unbemerkt ungültig zu machen.
|
||||
|
||||
Wird ein Device gelöscht, wird sein Assignment mitgelöscht. Wird eine Bereitstellungsvorlage gelöscht, auf die noch ein Assignment verweist, muss das gesperrt werden.
|
||||
|
||||
Für die relationale Umsetzung gilt daher:
|
||||
|
||||
- devices.organization_id → ON DELETE RESTRICT
|
||||
- hardware_snapshots.device_id → ON DELETE CASCADE
|
||||
- network_interfaces.hardware_snapshot_id → ON DELETE CASCADE
|
||||
- storage_devices.hardware_snapshot_id → ON DELETE CASCADE
|
||||
- workspaces.organization_id → ON DELETE CASCADE
|
||||
- workspace_merkmale.workspace_id → ON DELETE CASCADE
|
||||
- workspace_merkmale.merkmal_id → ON DELETE RESTRICT
|
||||
- blueprints.merkmal_id → ON DELETE CASCADE
|
||||
- blueprints.backend_id → ON DELETE CASCADE
|
||||
- bereitstellungsvorlagen.organization_id → ON DELETE CASCADE
|
||||
- bereitstellungsvorlagen.workspace_id → ON DELETE RESTRICT
|
||||
- bereitstellungsvorlagen.backend_id → ON DELETE RESTRICT
|
||||
- assignments.device_id → ON DELETE CASCADE
|
||||
- assignments.bereitstellungsvorlage_id → ON DELETE RESTRICT
|
||||
- activation_codes.organization_id → ON DELETE CASCADE
|
||||
|
||||
## ID-Erzeugung
|
||||
|
||||
|
||||
@ -29,9 +29,9 @@ Provisionierung fortsetzen?
|
||||
├── nein → kontrollierter Abbruch
|
||||
└── ja
|
||||
↓
|
||||
verfügbare Profile anzeigen
|
||||
verfügbare Bereitstellungsvorlagen anzeigen
|
||||
↓
|
||||
Profil auswählen
|
||||
Bereitstellungsvorlage auswählen
|
||||
↓
|
||||
Installationsplan anzeigen
|
||||
↓
|
||||
@ -117,40 +117,42 @@ Die Aktivierungsphase verwendet die bereits bestehende Server-Runtime:
|
||||
|
||||
`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.
|
||||
`response.json` enthält die erfolgreiche Antwort des Provisioning-Servers einschließlich Geräteinformationen, Organisation und verfügbarer Bereitstellungsvorlagen.
|
||||
|
||||
### Profilauswahl
|
||||
### Auswahl der Bereitstellungsvorlage
|
||||
|
||||
Die Auswahl eines Provisioning-Profils wird unter folgendem Pfad gespeichert:
|
||||
Die Auswahl einer Bereitstellungsvorlage wird unter folgendem Pfad gespeichert:
|
||||
|
||||
```text
|
||||
/run/tuxflotte/assignment/
|
||||
└── profile.json
|
||||
└── template.json
|
||||
```
|
||||
|
||||
`profile.json` enthält das vom Benutzer ausgewählte Profil.
|
||||
`template.json` enthält die vom Benutzer ausgewählte Bereitstellungsvorlage.
|
||||
|
||||
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>"
|
||||
}
|
||||
"template": {
|
||||
"id": "schulcomputer-fedora",
|
||||
"label": "Schulcomputer (Fedora)",
|
||||
"workspace": {
|
||||
"id": "schulcomputer",
|
||||
"name": "Schulcomputer"
|
||||
},
|
||||
"backend": {
|
||||
"id": "fedora",
|
||||
"name": "Fedora",
|
||||
"version": "40"
|
||||
},
|
||||
"is_default": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Die Profilauswahl darf ausschließlich Profile verwenden, die in der erfolgreichen Antwort des Provisioning-Servers für den aktuellen Aktivierungsvorgang enthalten sind.
|
||||
Die Auswahl darf ausschließlich Bereitstellungsvorlagen verwenden, die in der erfolgreichen Antwort des Provisioning-Servers für den aktuellen Aktivierungsvorgang enthalten sind.
|
||||
|
||||
### Installationsbestätigung
|
||||
|
||||
@ -281,13 +283,15 @@ Der Interactive Provisioning Flow wird durch folgende Module umgesetzt:
|
||||
|
||||
### 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 Profile,
|
||||
- zeigt die verfügbaren Profile an,
|
||||
- validiert die vom Server gelieferten Bereitstellungsvorlagen,
|
||||
- zeigt die verfügbaren Bereitstellungsvorlagen an,
|
||||
- erfasst die Auswahl des Benutzers,
|
||||
- speichert ausschließlich ein vom Server geliefertes Profil unter `/run/tuxflotte/assignment/profile.json`.
|
||||
- speichert ausschließlich eine vom Server gelieferte Bereitstellungsvorlage unter `/run/tuxflotte/assignment/template.json`.
|
||||
|
||||
Das Modul nimmt keine Änderungen an lokalen Datenträgern vor.
|
||||
|
||||
|
||||
@ -121,7 +121,7 @@ Eine Enrollment Session kann insbesondere auf folgende Eigenschaften begrenzt we
|
||||
- Organisation,
|
||||
- Gültigkeitszeitraum,
|
||||
- maximale Anzahl neuer Geräte,
|
||||
- erlaubte Provisioning-Profile.
|
||||
- erlaubte Bereitstellungsvorlagen.
|
||||
|
||||
Eine Enrollment Session ist widerrufbar und auditierbar.
|
||||
|
||||
@ -134,9 +134,9 @@ Organisation: Muster GmbH
|
||||
Maximale neue Geräte: 50
|
||||
Gültigkeit: 8 Stunden
|
||||
|
||||
Erlaubte Profile:
|
||||
- Fedora Workstation
|
||||
- Linux Mint Desktop
|
||||
Erlaubte Bereitstellungsvorlagen:
|
||||
- Schulcomputer (Fedora)
|
||||
- Entwickler (Mint)
|
||||
```
|
||||
|
||||
Der Installer kann neben der interaktiven Benutzeranmeldung die Verwendung einer Enrollment Session anbieten.
|
||||
|
||||
124
architecture/12-feature-blueprint-model.md
Normal file
124
architecture/12-feature-blueprint-model.md
Normal file
@ -0,0 +1,124 @@
|
||||
# Feature- und Blueprint-Modell
|
||||
|
||||
**Status:** Entwurf
|
||||
**Datum:** 17.07.2026
|
||||
|
||||
## Zweck dieses Dokuments
|
||||
|
||||
Dieses Dokument beschreibt, wie die Merkmale eines Workspace für ein konkretes Backend technisch umgesetzt werden.
|
||||
|
||||
Es ergänzt das Workspace-Modell (`02-workspace-model.md`) und das Backend-Modell um den bisher fehlenden Übersetzungsmechanismus und präzisiert den Begriff „Blueprint" aus dem Glossar.
|
||||
|
||||
---
|
||||
|
||||
## Motivation
|
||||
|
||||
Ein Workspace beschreibt einen Einsatzzweck, nicht seine technische Umsetzung.
|
||||
|
||||
Ein Backend beschreibt eine Distribution, nicht die einzelnen fachlichen Eigenschaften eines Workspace.
|
||||
|
||||
Zwischen beiden fehlt ein Bindeglied: die Frage, wie ein einzelnes Merkmal eines Workspace auf einem bestimmten Backend konkret realisiert wird.
|
||||
|
||||
Dieses Bindeglied ist der Blueprint.
|
||||
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
### Merkmal
|
||||
|
||||
Ein Merkmal ist eine einzelne fachliche Eigenschaft eines Workspace.
|
||||
|
||||
Ein Merkmal ist distributionsunabhängig benannt.
|
||||
|
||||
Beispiele:
|
||||
|
||||
- browser-brave
|
||||
- office-onlyoffice
|
||||
- guest-session-ephemeral
|
||||
- appstore
|
||||
|
||||
Ein Workspace besteht aus einer Menge von Merkmalen.
|
||||
|
||||
### Blueprint
|
||||
|
||||
Ein Blueprint beschreibt die technische Umsetzung genau eines Merkmals für genau ein Backend.
|
||||
|
||||
Ein Blueprint ist im Regelfall eine Ansible-Rolle bzw. -Aufgabe.
|
||||
|
||||
Für ein Merkmal existiert je unterstütztem Backend höchstens ein Blueprint.
|
||||
|
||||
Beispiel:
|
||||
|
||||
| Merkmal | Backend | Blueprint |
|
||||
|---|---|---|
|
||||
| browser-brave | fedora | Ansible-Rolle „brave-fedora" (dnf, Brave-Repository) |
|
||||
| browser-brave | mint | Ansible-Rolle „brave-mint" (apt, Brave-Repository) |
|
||||
| guest-session-ephemeral | fedora | Ansible-Rolle „guest-session" (tmpfs-Home, PAM) |
|
||||
| guest-session-ephemeral | mint | Ansible-Rolle „guest-session" (tmpfs-Home, PAM) |
|
||||
|
||||
Ein Blueprint kann von mehreren Backends wiederverwendet werden, wenn die Umsetzung identisch ist.
|
||||
|
||||
### Runtime Blueprint
|
||||
|
||||
Das Runtime Blueprint einer konkreten Installation entsteht, indem für jedes Merkmal des gewählten Workspace der zum gewählten Backend passende Blueprint aufgelöst wird.
|
||||
|
||||
Die Sammlung aller aufgelösten Blueprints wird nach dem ersten Start über den bestehenden Ansible-Pull-Mechanismus angewendet.
|
||||
|
||||
---
|
||||
|
||||
## Abgrenzung zu installationszeitlichen Vorgaben
|
||||
|
||||
Partitionierung, Festplattenverschlüsselung, Secure-Boot- und TPM-Bindung sowie weitere zur Installationszeit unveränderliche Eigenschaften sind kein Bestandteil eines Blueprints.
|
||||
|
||||
Sie werden als direkte Vorgabe der gewählten Bereitstellungsvorlage an `backend_generate_config()` übergeben und fließen unmittelbar in die native Installationskonfiguration ein (siehe `06-backend-api.md`, `08-provisioning-api.md`).
|
||||
|
||||
Blueprints setzen ausschließlich userspace-seitige Merkmale um, die nach der Installation angewendet werden können, ohne die Partitionierung oder die native Installationskonfiguration zu verändern.
|
||||
|
||||
---
|
||||
|
||||
## Erweiterbarkeit
|
||||
|
||||
Neue Merkmale erfordern Blueprints für jedes bereits unterstützte Backend.
|
||||
|
||||
Neue Backends erfordern Blueprints für jedes bereits bestehende Merkmal.
|
||||
|
||||
Workspace- und Merkmal-Definitionen bleiben davon unberührt.
|
||||
|
||||
---
|
||||
|
||||
## Beispiel
|
||||
|
||||
### Workspace: Schulcomputer
|
||||
|
||||
Merkmale:
|
||||
|
||||
- guest-session-ephemeral
|
||||
- browser-brave
|
||||
- office-onlyoffice
|
||||
|
||||
### Workspace: Entwickler
|
||||
|
||||
Merkmale:
|
||||
|
||||
- Programmiersprachen
|
||||
- Virtualisierung
|
||||
- Editoren
|
||||
- Entwicklungsumgebungen
|
||||
|
||||
### Unterstützte Backends
|
||||
|
||||
- Fedora
|
||||
- Linux Mint
|
||||
|
||||
---
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Ein Workspace besteht aus Merkmalen.
|
||||
|
||||
Ein Blueprint setzt genau ein Merkmal für genau ein Backend um, in der Regel als Ansible-Rolle.
|
||||
|
||||
Das Runtime Blueprint einer konkreten Installation entsteht aus der Auflösung aller Merkmale des gewählten Workspace gegen das gewählte Backend.
|
||||
|
||||
Installationszeitliche Vorgaben wie Partitionierung und Verschlüsselung bleiben ein direkter Kanal der Bereitstellungsvorlage und sind kein Bestandteil eines Blueprints.
|
||||
Loading…
x
Reference in New Issue
Block a user