Shema recepta

Recepti OpenFactory koriste JSON u snake_case. Kanonski format ima malu ovojnicu na vrhu, objekt os za konfiguraciju operacijskog sustava i polje scenarios za provjeru nakon gradnje.

Validacija pokazuje da prepoznata polja imaju prihvatljiv oblik. Ne dokazuje da svaki paket postoji, da je svako traženo ponašanje uključeno, niti da će slika i testovi uspjeti. Nepoznata polja mogu se zbog kompatibilnosti unatrag ignorirati; uvijek provjerite normalizirani recept koji proizvod vrati.

Kanonska 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 koristite polja camelCase poput baseImage ili startupScripts. Validator kompatibilnosti prihvaća neke starije ravne recepte, ali normalizirani izlaz ugnijezdi polja OS pod os. Nove integracije trebaju slati kanonski format.

Polja na vrhu

Napredna polja ovisna o cilju postoje za remasteriranje izvornog ISO-a, payloade Proxmox gosta, provenijenciju pravila i integracije isporuke. Koristite uređivač ili API ugovor uvedene verzije umjesto kopiranja starog primjera.

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 ili raspberry_pi; podržane vrijednosti uređaja ovise o cilju. architecture je x86_64 ili aarch64. Vrijednosti GPU imenuju podržanog dobavljača ili kombinaciju. To su deklarirani zahtjevi, a ne dokaz da je nastala slika testirana na odgovarajućem fizičkom hardveru.

Objekt OS

Uobičajena polja os:

Prisutnost polja integrity ili security izražava namjeru konfiguracije. Nije dokaz da je mehanizam proizveden, proveden u runtimeu ili kvalificiran za režim usklađenosti. Tražite odgovarajuće dokaze gradnje i testova.

Korisnici

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

Imena korisnika i grupa ograničena su na sigurne znakove i duljinu linux računa. Bez postavljenog password nastaje račun zaključan lozinkom za tijek rada samo s ključem ili s vjerodajnicama pri implementaciji. Izbjegavajte nešifrirane vjerodajnice u spremljenim receptima.

Usluge

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

config ovisi o usluzi. Sintaktički valjan ključ generator koji ga ne implementira može ignorirati. Provjerite normalizirani recept, generiranu konfiguraciju i ponašanje gosta.

Sigurnost i 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"
    }
  }
}

Tipovi installer-a ovise o cilju (calamares, anaconda ili elster-mobile). Nakon uključivanja installer-a slijedi test instalacije na jednokratni disk; ikona na live desktopu ne dokazuje da instalacija radi.

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

Prihvaća se najviše 32 startup skripte. Naredbe moraju biti neprazne i ne smiju sadržavati NUL bajtove. Tretirajte ih kao shell kod s root ovlastima, osim ako run_as ne kaže drugače; provjerite idempotentnost, quoting, kvar mreže i izlaganje tajni.

Scenariji i 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 može definirati i topology s VM-ovima i mrežama, testove u benchmark formatu i CIS postavke. Nedostajuća topologija zadano ide normalnim putem s jednom VM. Assertions trebaju ljudski čitljiv description i parametre prema tipu. Nepoznati tipovi assertions mogu proći parsiranje sheme; potvrdite podršku u runneru prije nego ih smatrate dokazom.

Potpuni minimalni primjer

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

Tijek validacije

1. Validirajte JSON u trenutnom uređivaču recepta, API-ju ili MCP alatu validate_recipe.
2. Usporedite vraćeni normalizirani recept s izvornim zahtjevom.
3. Odbačena nepoznata polja tretirajte kao grešku recepta, a ne kao uspješnu konfiguraciju.
4. Gradite tek kad su eksplicitni zahtjevi uključeni.
5. Pregledajte generirane dokaze i pokrenite assertions protiv nastalog gosta.

Pogledajte Vaša prva gradnja za upute pri kvaru i oporavku preuzimanja.