Receptschema

OpenFactory-recepten gebruiken JSON in snake_case. Het canonieke formaat heeft een kleine envelope op het hoogste niveau, een os-object voor configuratie van het besturingssysteem en een scenarios-array voor verificatie na de build.

Validatie toont dat herkende velden aanvaardbare vormen hebben. Het bewijst niet dat elk pakket bestaat, dat elk gevraagd gedrag is vastgelegd, of dat image en tests slagen. Onbekende velden kunnen voor achterwaartse compatibiliteit worden genegeerd; controleer daarom altijd het genormaliseerde recept dat het product teruggeeft.

Canonieke envelope

{
  "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"]
}

Gebruik geen camelCase-velden zoals baseImage of startupScripts. De compatibiliteitsvalidator accepteert sommige oudere platte recepten, maar genormaliseerde output nestelt OS-velden onder os. Nieuwe integraties moeten het canonieke formaat sturen.

Velden op het hoogste niveau

Geavanceerde doelspecifieke velden bestaan voor source-ISO-remastering, Proxmox-guestpayloads, policy-provenance en delivery-integraties. Gebruik de editor of het API-contract van de uitgerolde release in plaats van een oud voorbeeld te kopiëren.

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 is pc, phone of raspberry_pi; ondersteunde apparaatwaarden zijn doelspecifiek. architecture is x86_64 of aarch64. GPU-waarden noemen een ondersteunde leverancier of combinatie. Dit zijn gedeclareerde vereisten, geen bewijs dat een resulterende image op passende fysieke hardware is getest.

OS-object

Veelgebruikte os-velden:

Aanwezigheid van een integrity- of security-veld is configuratie-intentie. Het is geen bewijs dat het mechanisme is geproduceerd, tijdens runtime wordt afgedwongen of geschikt is voor een compliance-regime. Eis passend build- en testbewijs.

Gebruikers

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

Gebruikers- en groepsnamen zijn beperkt tot veilige Linux-accounttekens en lengte. Als password niet is gezet, ontstaat een met wachtwoord vergrendeld account voor alleen-sleutel- of credentials-bij-deployment-workflows. Vermijd plaintext-credentials in opgeslagen recepten.

Services

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

config is servicespecifiek. Een syntactisch geldige sleutel kan nog worden genegeerd door een generator die die niet implementeert. Controleer het genormaliseerde recept, gegenereerde configuratie en gastgedrag.

Beveiliging en 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"
    }
  }
}

Installertypes hangen af van het doel (calamares, anaconda of elster-mobile). Een installer inschakelen moet gevolgd worden door een installatietest op een wegwerpschijf; een pictogram op een live desktop bewijst niet dat installatie werkt.

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"
      }
    ]
  }
}

Er worden hoogstens 32 startup-scripts geaccepteerd. Commando’s mogen niet leeg zijn en mogen geen NUL-bytes bevatten. Behandel ze als root-capabele shellcode tenzij run_as anders aangeeft; controleer idempotentie, quoting, netwerkfouten en blootstelling van secrets.

Scenario’s en 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}
            }
          ]
        }
      ]
    }
  ]
}

Een scenario kan ook een topology met VM’s en netwerken, benchmark-formaattests en CIS-instellingen definiëren. Een ontbrekende topology valt terug op het normale single-VM-pad. Assertions hebben een leesbare beschrijving en typespecifieke params nodig. Onbekende assertiontypes kunnen schema-parsing overleven; bevestig dat de runner ze ondersteunt voordat u ze als bewijs behandelt.

Volledig minimaal voorbeeld

{
  "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"]
}

Validatieworkflow

1. Valideer de JSON via de actuele recepteditor, API of MCP-tool validate_recipe.
2. Vergelijk het teruggegeven genormaliseerde recept met het oorspronkelijke verzoek.
3. Behandel weggelaten onbekende velden als een fout in het recept, niet als geslaagde configuratie.
4. Build pas nadat expliciete vereisten zijn vastgelegd.
5. Inspecteer gegenereerd bewijs en voer assertions uit tegen de resulterende gast.

Zie Je eerste build voor hulp bij fouten en het herstellen van downloads.