platform-docs/architecture/08-provisioning-api.md

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 Provisioning-Profilen.

```json
{
  "success": true,
  "device": {
    "id": "<device-uuid>",
    "fingerprint": "<sha256>",
    "hostname": "enterprise",
    "created": false,
    "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.created gibt an, ob das Gerät während dieses Aktivierungsvorgangs neu registriert 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:

{
  "success": false,
  "error": "invalid_activation_code",
  "message": "Der Aktivierungscode ist ungültig."
}