Rezept-Schema

OpenFactory-Rezepte nutzen snake_case JSON. Das kanonische Format hat eine kleine Top-Level-Hülle, ein os-Objekt für Betriebssystem-Konfiguration und ein scenarios-Array für Verifikation nach dem Build.

Validierung beweist, dass erkannte Felder akzeptable Formen haben. Sie beweist nicht, dass jedes Paket existiert, jedes angeforderte Verhalten abgebildet wurde oder Image und Tests erfolgreich sind. Unbekannte Felder können aus Abwärtskompatibilität ignoriert werden; prüfen Sie stets das vom Produkt zurückgegebene normalisierte Rezept.

Kanonische Hülle

{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Small Debian image with explicit smoke tests.",
  "base_image": "debian-trixie",
  "use_case": "Server evaluation",
  "hardware": {},
  "os": {},
  "scenarios": [],
  "publish_to": ["local"]
}

Nutzen Sie keine camelCase-Felder wie baseImage oder startupScripts. Der Kompatibilitätsvalidator akzeptiert manche älteren flachen Rezepte, aber normalisierte Ausgabe nestet OS-Felder unter os. Neue Integrationen sollten das kanonische Format senden.

Top-Level-Felder

Fortgeschrittene zielspezifische Felder existieren für Source-ISO-Remastering, Proxmox-Guest-Payloads, Policy-Provenienz und Delivery-Integrationen. Nutzen Sie Editor oder API-Contract der ausgerollten Version statt eines alten Beispiels zu kopieren.

Hardware

{
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "gpu": null,
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  }
}

platform ist pc, phone oder raspberry_pi; unterstützte Device-Werte sind zielspezifisch. architecture ist x86_64 oder aarch64. GPU-Werte benennen einen unterstützten Vendor oder Vendor-Kombination. Das sind deklarierte Anforderungen, kein Nachweis, dass ein resultierendes Image auf passender physischer Hardware getestet wurde.

OS-Objekt

Häufige os-Felder:

Präsenz eines Integrity- oder Security-Felds ist Konfigurationsabsicht. Es ist kein Nachweis, dass der Mechanismus erzeugt, zur Laufzeit durchgesetzt oder für ein Compliance-Regime qualifiziert wurde. Passenden Build- und Test-Nachweis verlangen.

Users

{
  "os": {
    "users": [
      {
        "username": "deploy",
        "full_name": "Deployment Operator",
        "groups": ["sudo"],
        "shell": "/bin/bash"
      }
    ]
  }
}

User- und Gruppennamen sind auf sichere Linux-Account-Zeichen und Länge begrenzt. Ohne password entsteht ein passwort-gesperrtes Konto für Key-only- oder Deployment-Zeit-Credential-Workflows. Vermeiden Sie Klartext-Credentials in gespeicherten Rezepten.

Services

{
  "os": {
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {
          "port": 22,
          "disable_password_auth": true
        }
      }
    ]
  }
}

config ist service-spezifisch. Ein syntaktisch gültiger Key kann vom Generator ignoriert werden, der ihn nicht implementiert. Normalisiertes Rezept, generierte Konfiguration und Gast-Verhalten prüfen.

Security und Installer

{
  "os": {
    "security": {
      "hardening_level": "standard",
      "disk_encryption": false,
      "audit_logging": true,
      "selinux": false,
      "fail2ban": true
    },
    "installer": {
      "enabled": false,
      "type": "calamares",
      "desktop_launcher": true,
      "bootloader": "grub",
      "delivery": [],
      "user_setup": "build_time"
    }
  }
}

Installer-Typen sind zielabhängig (calamares, anaconda oder elster-mobile). Installer aktivieren muss von einem Install-Test auf Wegwerf-Disk gefolgt werden; ein Icon im Live-Desktop beweist keine funktionierende Installation.

Startup Scripts

{
  "os": {
    "startup_scripts": [
      {
        "name": "write-build-marker",
        "description": "Create a local marker after networking is available.",
        "command": "install -m 0644 /dev/null /var/lib/example-ready",
        "packages": [],
        "run_as": "root",
        "after": "network.target"
      }
    ]
  }
}

Höchstens 32 Startup Scripts werden akzeptiert. Befehle müssen nicht leer sein und dürfen keine NUL-Bytes enthalten. Behandeln Sie sie als root-fähigen Shell-Code, sofern run_as nichts anderes sagt; Idempotenz, Quoting, Netzwerkfehler und Secret-Exposure prüfen.

Szenarien und Assertions

{
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"],
      "custom_tests": [
        {
          "description": "Confirm SSH is enabled on the configured port.",
          "assertions": [
            {
              "type": "service_enabled",
              "description": "The SSH service starts at boot.",
              "params": {"service": "ssh"}
            },
            {
              "type": "port_listening",
              "description": "The guest listens on TCP port 22.",
              "params": {"port": 22}
            }
          ]
        }
      ]
    }
  ]
}

Ein Szenario kann auch topology mit VMs und Netzwerken, Benchmark-Format-Tests und CIS-Einstellungen definieren. Fehlende Topology defaultet zum normalen Single-VM-Pfad. Assertions brauchen lesbare description und typspezifische params. Unbekannte Assertion-Typen können Schema-Parsing überleben; bestätigen Sie Runner-Support, bevor Sie sie als Evidenz behandeln.

Vollständiges Minimalbeispiel

{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Debian image with SSH, curl, and explicit smoke tests.",
  "base_image": "debian-trixie",
  "use_case": "Server evaluation",
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  },
  "os": {
    "features": ["ssh"],
    "packages": ["curl"],
    "users": [
      {
        "username": "deploy",
        "groups": ["sudo"],
        "shell": "/bin/bash"
      }
    ],
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {"port": 22, "disable_password_auth": true}
      }
    ],
    "security": {
      "hardening_level": "standard",
      "audit_logging": true
    },
    "installer": {"enabled": false}
  },
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"]
    }
  ],
  "publish_to": ["local"]
}

Validierungs-Workflow

1. JSON über aktuellen Rezept-Editor, API oder MCP-Tool validate_recipe validieren.
2. Zurückgegebenes normalisiertes Rezept mit der ursprünglichen Anfrage vergleichen.
3. Verworfene unbekannte Felder als Rezeptfehler behandeln, nicht als erfolgreiche Konfiguration.
4. Erst bauen, wenn explizite Anforderungen abgebildet sind.
5. Generierten Nachweis inspizieren und Assertions gegen den resultierenden Gast ausführen.

Siehe Ihr erster Build für Failure- und Download-Recovery-Hinweise.