Reseptikaavio

OpenFactory-reseptit käyttävät snake_case-JSONia. Kanoninen muoto sisältää pienen ylätason kuoren, os-objektin käyttöjärjestelmän asetuksille ja scenarios-taulukon buildin jälkeiseen varmistukseen.

Validointi osoittaa, että tunnistetuilla kentillä on hyväksyttävät muodot. Se ei osoita, että jokainen paketti on olemassa, että jokainen pyydetty käyttäytyminen on kuvattu, tai että image ja testit onnistuvat. Tuntemattomat kentät voidaan ohittaa taaksepäin yhteensopivuuden vuoksi; tarkista aina tuotteen palauttama normalisoitu resepti.

Kanoninen kuori

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

Älä käytä camelCase-kenttiä kuten baseImage tai startupScripts. Yhteensopivuus- validaattori hyväksyy joitakin vanhempia tasaisia reseptejä, mutta normalisoitu tuloste sisentää OS-kentät os- alle. Uusien integraatioiden tulisi lähettää kanoninen muoto.

Ylätason kentät

Edistyneitä kohdekohtaisia kenttiä on lähde-ISO-remasterointiin, Proxmox-vieraspayloadiin, policy-provenienceen ja delivery-integraatioihin. Käytä editoria tai API-sopimusta käyttöönotetusta versiosta vanhan esimerkin kopioimisen sijaan.

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 on pc, phone tai raspberry_pi; tuetut laitearvot ovat kohdekohtaisia. architecture on x86_64 tai aarch64. GPU-arvot nimeävät tuetun toimittajan tai yhdistelmän. Nämä ovat ilmoitettuja vaatimuksia, eivät todiste siitä, että syntynyt image on testattu vastaavalla fyysisellä laitteistolla.

OS-objekti

Yleisiä os-kenttiä:

Integrity- tai security-kentän olemassaolo on konfiguraatio-intentio. Se ei ole todiste siitä, että mekanismi tuotettiin, että sitä valvottiin ajon aikana tai että se kelpaa compliance-ympäristöön. Vaadi vastaava build- ja testitodiste.

Käyttäjät

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

Käyttäjä- ja ryhmänimet on rajoitettu turvallisiin Linux-tilin merkkeihin ja pituuteen. Jos password jätetään asettamatta, syntyy salasanalla lukittu tili avain- tai käyttöönoton aikaisten tunnusten työnkuluille. Vältä plaintext-tunnuksia tallennetuissa resepteissä.

Palvelut

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

config on palvelukohtainen. Syntaktisesti kelvollinen avain voidaan silti ohittaa generaattorissa, joka ei toteuta sitä. Tarkista normalisoitu resepti, generoitu konfiguraatio ja vieraskäyttäytyminen.

Turvallisuus ja 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-tyypit riippuvat kohteesta (calamares, anaconda tai elster-mobile). Installerin käyttöönoton jälkeen tarvitaan kertalevyasennustesti; live-työpöydän kuvake ei osoita, että asennus toimii.

Käynnistysskriptit

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

Enintään 32 käynnistysskriptiä hyväksytään. Komennot eivät saa olla tyhjiä eivätkä sisältää NUL-tavuja. Kohtele niitä root-oikeuksilla ajettavana shell-koodina, ellei run_as sano muuta; tarkista idempotenssi, quoting, verkkovirheet ja salaisuuksien paljastuminen.

Skenaariot ja assertionit

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

Skenaario voi myös määrittää topology-rakenteen VM:illä ja verkoilla, benchmark-muotoisia testejä ja CIS-asetuksia. Puuttuva topology palautuu tavalliseen single-VM-polkuun. Assertionit tarvitsevat luettavan kuvauksen ja tyyppikohtaiset params-arvot. Tuntemattomat assertion-tyypit voivat selvitä skeeman jäsentämisestä; varmista runnerin tuki ennen kuin käsittelet niitä todisteena.

Täydellinen minimaalinen esimerkki

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

Validointityönkulku

1. Validoi JSON nykyisen reseptieditorin, API:n tai MCP-työkalun validate_recipe kautta.
2. Vertaa palautettua normalisoitua reseptiä alkuperäiseen pyyntöön.
3. Kohtele pudotettuja tuntemattomia kenttiä reseptivikana, älä onnistuneena konfiguraationa.
4. Rakenna vasta kun eksplisiittiset vaatimukset on kuvattu.
5. Tarkista generoitu todiste ja aja assertionit syntynyttä vierasta vastaan.

Katso Ensimmäinen buildisi ohjeita virheiden ja latausten palauttamiseen.