Recepto schema

OpenFactory receptai naudoja snake_case JSON. Kanoninis formatas turi nedidelį viršutinio lygio apvalkalą, os objektą operacinės sistemos konfigūracijai ir scenarios masyvą patikrai po build.

Validacija įrodo, kad atpažinti laukai turi priimtinas formas. Ji neįrodo, kad kiekvienas paketas egzistuoja, kad kiekvienas pageidautas elgesys buvo atspindėtas, ar kad image ir testai pavyks. Nežinomi laukai gali būti ignoruojami atgaliniam suderinamumui, todėl visada peržiūrėkite produkto grąžintą normalizuotą receptą.

Kanoninis apvalkalas

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

Nenaudokite camelCase laukų, pvz. baseImage ar startupScripts. Suderinamumo validatorius priima kai kuriuos senesnius plokščius receptus, bet normalizuota išvestis įdėtina OS laukus po os. Naujos integracijos turėtų siųsti kanoninį formatą.

Viršutinio lygio laukai

Išplėstiniai tikslui specifiniai laukai skirti šaltinio ISO perdirbimui, Proxmox svečio payload, policy kilmės duomenims ir delivery integracijoms. Naudokite redaktorių arba API sutartį diegiamai versijai, o ne kopijuokite seną pavyzdį.

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 reikšmės: pc, phone arba raspberry_pi; palaikomos įrenginio reikšmės priklauso nuo tikslo. architecture yra x86_64 arba aarch64. GPU reikšmės nurodo palaikomą gamintoją ar kombinaciją. Tai deklaruoti reikalavimai, ne įrodymas, kad gautas image buvo testuotas atitinkamoje fizinėje aparatūroje.

OS objektas

Dažni os laukai:

Integrity arba security lauko buvimas reiškia konfigūracijos ketinimą. Tai ne įrodymas, kad mechanizmas buvo sukurtas, vykdomas runtime arba kvalifikuotas atitikties režimui. Reikalaukite atitinkamų build ir test įrodymų.

Users

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

Vartotojo ir grupės vardai ribojami saugiais Linux paskyros simboliais ir ilgiu. Jei password nenustatytas, sukuriama slaptažodžiu užrakinta paskyra tik raktams ar diegimo metu teikiamoms credentials. Venkite credentials gryname tekste išsaugotuose receptuose.

Services

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

config priklauso nuo paslaugos. Sintaksiškai galiojantis raktas vis tiek gali būti ignoruojamas generatoriaus, kuris jo neimplementuoja. Patikrinkite normalizuotą receptą, sugeneruotą konfigūraciją ir svečio elgseną.

Security and 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 tipai priklauso nuo tikslo (calamares, anaconda arba elster-mobile). Įjungus installer reikia vienkartinio disko diegimo testo; piktograma live darbalaukyje neįrodo, kad diegimas veikia.

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

Priimama ne daugiau kaip 32 startup_scripts. Komandos turi būti ne tuščios ir negali turėti NUL baitų. Laikykite jas root lygio shell kodu, nebent run_as nurodo kitaip; peržiūrėkite idempotenciją, kabutes, tinklo klaidas ir slaptų duomenų atskleidimą.

Scenarios and 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}
            }
          ]
        }
      ]
    }
  ]
}

Scenarijus gali apibrėžti ir topology su VM ir tinklais, benchmark formato testus bei CIS nustatymus. Jei topologija praleista, naudojamas įprastas vieno VM kelias. Assertions reikalauja žmogui skaitomo aprašymo ir tipui specifinių params. Nežinomi assertion tipai gali praeiti schemos analizę, todėl prieš laikydami juos įrodymu patvirtinkite, kad runner juos palaiko.

Pilnas minimalus pavyzdys

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

Validacijos eiga

1. Validuokite JSON per dabartinį recepto redaktorių, API ar MCP įrankį validate_recipe.
2. Palyginkite grąžintą normalizuotą receptą su pradine užklausa.
3. Nežinomus atmestus laukus laikykite recepto defektu, o ne sėkminga konfigūracija.
4. Build pradėkite tik tada, kai aiškūs reikalavimai atspindėti.
5. Peržiūrėkite sugeneruotus įrodymus ir paleiskite assertions prieš gautą svečią.

Žr. Your First Build dėl klaidų ir atsisiuntimo atkūrimo.