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.
193 lines
5.3 KiB
Markdown
193 lines
5.3 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```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`).
|