# 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`).