Schéma receptúry

Receptúry OpenFactory používajú JSON v snake_case. Kanonický formát má malú obálku na najvyššej úrovni, objekt os pre konfiguráciu operačného systému a pole scenarios na overenie po zostavení.

Validácia ukazuje, že rozpoznané polia majú prijateľný tvar. Nedokazuje, že každý balík existuje, že každé požadované správanie bolo zohľadnené, ani že obraz a testy uspejú. Neznáme polia môžu byť kvôli spätnej kompatibilite ignorované; vždy skontrolujte normalizovanú receptúru vrátenú produktom.

Kanonická obálka

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

Nepoužívajte polia camelCase ako baseImage alebo startupScripts. Validátor kompatibility prijme niektoré staršie ploché receptúry, ale normalizovaný výstup vnorí polia OS pod os. Nové integrácie by mali posielať kanonický formát.

Polia najvyššej úrovne

Pokročilé polia závislé od cieľa existujú pre remasterovanie zdrojového ISO, payloady hosta Proxmox, provenienciu politík a integrácie doručenia. Použite editor alebo kontrakt API nasadenej verzie namiesto kopírovania starého príkladu.

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 je pc, phone alebo raspberry_pi; podporované hodnoty zariadení závisia od cieľa. architecture je x86_64 alebo aarch64. Hodnoty GPU pomenúvajú podporovaného dodávateľa alebo kombináciu. Ide o deklarované požiadavky, nie o dôkaz, že výsledný obraz bol testovaný na zodpovedajúcom fyzickom hardvéri.

Objekt OS

Bežné polia os:

Prítomnosť poľa integrity alebo security vyjadruje zámer konfigurácie. Nie je dôkazom, že mechanizmus bol vytvorený, vynútený za behu alebo kvalifikovaný pre režim compliance. Vyžadujte zodpovedajúce dôkazy zo zostavenia a testov.

Používatelia

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

Menná používateľov a skupín sú obmedzené na bezpečné znaky a dĺžku linuxových účtov. Bez nastaveného password vznikne účet uzamknutý heslom pre workflow len s kľúčom alebo s prihlasovacími údajmi až pri nasadení. Vyhnite sa nešifrovaným prihlasovacím údajom v uložených receptúrach.

Služby

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

config závisí od služby. Syntakticky platný kľúč môže generátor, ktorý ho neimplementuje, ignorovať. Overte normalizovanú receptúru, vygenerovanú konfiguráciu a správanie hosta.

Zabezpečenie a 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"
    }
  }
}

Typy installeru závisia od cieľa (calamares, anaconda alebo elster-mobile). Po zapnutí installeru nasleduje test inštalácie na jednorazový disk; ikona na live desktope nedokazuje, že inštalácia funguje.

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

Prijme sa najviac 32 startup skriptov. Príkazy musia byť neprázdne a nesmú obsahovať bajty NUL. Považujte ich za shell kód s právami root, ak run_as nehovorí inak; kontrolujte idempotenciu, quoting, zlyhanie siete a únik tajomstiev.

Scenáre a 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}
            }
          ]
        }
      ]
    }
  ]
}

Scenár môže tiež definovať topology s VM a sieťami, testy vo formáte benchmark a nastavenia CIS. Chýbajúca topológia defaultuje na bežnú cestu s jednou VM. Assertions potrebujú ľudsky čitateľný description a parametre podľa typu. Neznáme typy assertions môžu prejsť parsovaním schémy; overte podporu v runneri, kým ich beriete ako dôkaz.

Úplný minimálny príklad

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

Workflow validácie

1. Validujte JSON v aktuálnom editore receptúr, API alebo MCP nástroji validate_recipe.
2. Porovnajte vrátenú normalizovanú receptúru s pôvodnou požiadavkou.
3. Zahodené neznáme polia považujte za chybu receptúry, nie za úspešnú konfiguráciu.
4. Zostavujte až potom, keď sú explicitné požiadavky zohľadnené.
5. Prezrite vygenerované dôkazy a spustite assertions proti výslednému hostu.

Pozrite Váš prvý build pre postup pri zlyhaní a obnovení sťahovania.