Shema recepta

Recepti OpenFactory uporabljajo JSON v snake_case. Kanonična oblika ima majhno ovojnico na vrhu, objekt os za konfiguracijo operacijskega sistema in polje scenarios za preverjanje po gradnji.

Validacija pokaže, da imajo prepoznana polja sprejemljivo obliko. Ne dokazuje, da vsak paket obstaja, da je bilo vsako zahtevano obnašanje upoštevano, ali da bosta slika in testi uspeli. Neznana polja se lahko zaradi združljivosti nazaj ignorirajo; vedno preverite normaliziran recept, ki ga vrne produkt.

Kanonična ovojnica

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

Ne uporabljajte polj camelCase, kot sta baseImage ali startupScripts. Validator združljivosti sprejme nekatere starejše ravne recepte, vendar normaliziran izhod gnezdi polja OS pod os. Nove integracije naj pošiljajo kanonično obliko.

Polja na vrhu

Napredna polja, odvisna od cilja, obstajajo za remastering izvornega ISO, payloade gosta Proxmox, provenienco pravil in integracije dostave. Uporabite urejevalnik ali API pogodbo uvedene različice namesto kopiranja starega primera.

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 ali raspberry_pi; podprte vrednosti naprav so odvisne od cilja. architecture je x86_64 ali aarch64. Vrednosti GPU poimenujejo podprtega prodajalca ali kombinacijo. To so deklarirane zahteve, ne dokaz, da je bila nastala slika testirana na ustrezni fizični strojni opremi.

Objekt OS

Pogosta polja os:

Prisotnost polja integrity ali security izraža namen konfiguracije. Ni dokaz, da je bil mehanizem ustvarjen, uveljavljen med izvajanjem ali kvalificiran za režim skladnosti. Zahtevajte ustrezne dokaze gradnje in testov.

Uporabniki

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

Imena uporabnikov in skupin so omejena na varne znake in dolžino linuxovskih računov. Brez nastavljenega password nastane račun, zaklenjen z geslom, za potek dela samo s ključem ali s poverilnicami ob namestitvi. Izogibajte se nešifriranim poverilnicam v shranjenih receptih.

Storitve

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

config je odvisen od storitve. Sintaktično veljaven ključ lahko generator, ki ga ne implementira, ignorira. Preverite normaliziran recept, ustvarjeno konfiguracijo in obnašanje gosta.

Varnost in 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"
    }
  }
}

Tipi installerja so odvisni od cilja (calamares, anaconda ali elster-mobile). Po omogočitvi installerja sledi test namestitve na enkratni disk; ikona na live namizju ne dokazuje, da namestitev deluje.

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

Spreje se največ 32 startup skript. Ukazi morajo biti neprazni in ne smejo vsebovati bajtov NUL. Obnašajte se do njih kot do shell kode z root pravicami, razen če run_as pravi drugače; preverite idempotentnost, quoting, okvaro omrežja in izpostavljenost skrivnosti.

Scenariji in 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}
            }
          ]
        }
      ]
    }
  ]
}

Scenarij lahko definira tudi topology z VM in omrežji, teste v formatu benchmark in nastavitve CIS. Manjkajoča topologija privzeto uporabi običajno pot z eno VM. Assertions potrebujejo človeku berljiv description in parametre glede na tip. Neznani tipi assertions lahko preživijo parsiranje sheme; preverite podporo v runnerju, preden jih obravnavate kot dokaz.

Popoln minimalni primer

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

Potek validacije

1. Validirajte JSON v trenutnem urejevalniku receptov, API-ju ali MCP orodju validate_recipe.
2. Primerjajte vrnjen normaliziran recept z izvirno zahtevo.
3. Zavržena neznana polja obravnavajte kot napako recepta, ne kot uspešno konfiguracijo.
4. Gradite šele, ko so eksplicitne zahteve upoštevane.
5. Preglejte ustvarjene dokaze in zaženite assertions proti nastalem gostu.

Glej Vaša prva gradnja za navodila ob napaki in obnovi prenosa.