Thomas Stallinger
8ece25f954
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.
5.3 KiB
Provisioning API
Zweck
Die Provisioning API beschreibt die Kommunikation zwischen dem Tuxflotte-Installer und dem Provisioning-Server.
Sie ist distributionsunabhängig.
Die Backend API (06-backend-api.md) beginnt erst nach der Erstellung des Runtime Blueprints.
Aktivierung
Endpoint
POST /api/v1/activate
Zweck
Der Endpoint autorisiert einen initialen Provisionierungsvorgang und registriert oder erkennt ein Gerät anhand seines Hardware-Fingerprints wieder.
Request
{
"activation_code": "LAB-2026-START",
"device_fingerprint": "<sha256>",
"hostname": "enterprise",
"machine_id": "<machine-id>",
"client_version": "0.1.0",
"hardware": {
"schema_version": 1,
"identity": {
"device_fingerprint": "<sha256>",
"system_uuid": "<uuid>",
"system_serial": null,
"board_serial": "<serial>",
"machine_id": "<machine-id>"
},
"system": {
"manufacturer": null,
"product_name": null,
"product_version": null,
"architecture": "x86_64",
"cpu": {
"model": "<cpu-model>",
"logical_count": 8
},
"memory_bytes": 33446432768
},
"mainboard": {
"vendor": "Intel Corporation",
"name": "DH87MC"
},
"firmware": {
"bios_vendor": "Intel Corp.",
"bios_version": "<bios-version>",
"boot_mode": "bios",
"secure_boot": "unsupported"
},
"security": {
"tpm_version": "none"
},
"network_interfaces": [
{
"name": "eno1",
"type": "ethernet",
"mac": "<mac-address>"
}
],
"storage_devices": [
{
"name": "sda",
"model": "<model>",
"serial": "<serial>",
"size_bytes": 512110190592,
"transport": "sata"
}
]
}
}
Der `hardware`-Block enthält den während der Provisionierung erfassten Hardwarezustand.
Der Provisioning-Server registriert oder erkennt das Gerät anhand des `device_fingerprint` und speichert den übertragenen Hardwarezustand als zeitbezogenen Hardware-Snapshot.
Bei einer erneuten erfolgreichen Aktivierung desselben Geräts bleibt die interne Geräte-ID erhalten. Für den aktuellen Aktivierungsvorgang wird ein neuer Hardware-Snapshot erzeugt.
### Response
Bei erfolgreicher Aktivierung antwortet der Provisioning-Server mit dem registrierten Gerät, der zugeordneten Organisation und den verfügbaren Bereitstellungsvorlagen.
```json
{
"success": true,
"device": {
"id": "<device-uuid>",
"fingerprint": "<sha256>",
"hostname": "enterprise",
"registration_status": "existing",
"hardware_snapshot_id": "<hardware-snapshot-uuid>"
},
"customer": {
"id": "default",
"organization_id": "<organization-uuid>",
"name": "Default Lab"
},
"templates": [
{
"id": "schulcomputer-fedora",
"label": "Schulcomputer (Fedora)",
"workspace": {
"id": "schulcomputer",
"name": "Schulcomputer"
},
"backend": {
"id": "fedora",
"name": "Fedora",
"version": "40"
},
"is_default": true
}
]
}
device.id ist die interne, von Hardwaremerkmalen unabhängige Geräte-ID.
device.registration_status beschreibt den Registrierungszustand des Geräts für den aktuellen Aktivierungsvorgang.
Der Wert registered bedeutet, dass im Bootstrap-Modell ein neues Device registriert wurde.
Der Wert existing bedeutet, dass ein bereits bekanntes Device anhand seines Hardware-Fingerprints wiedererkannt wurde.
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 Bereitstellungsvorlagen.
Jede Bereitstellungsvorlage referenziert genau einen Workspace und genau ein Backend. Höchstens eine Bereitstellungsvorlage je Organisation trägt is_default: true.
Fehlerantwort
Ist der Aktivierungscode ungültig, antwortet der Provisioning-Server mit:
{
"success": false,
"error": "invalid_activation_code",
"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
{
"device_id": "<device-uuid>"
}
Response
{
"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).