147 lines
3.9 KiB
Markdown
147 lines
3.9 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 Provisioning-Profilen.
|
|
|
|
```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"
|
|
},
|
|
"profiles": [
|
|
{
|
|
"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>"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`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 Profile.
|
|
|
|
### Fehlerantwort
|
|
|
|
Ist der Aktivierungscode ungültig, antwortet der Provisioning-Server mit:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "invalid_activation_code",
|
|
"message": "Der Aktivierungscode ist ungültig."
|
|
}
|
|
```
|