Receptes shēma

OpenFactory receptes izmanto snake_case JSON. Kanoniskajam formātam ir neliela augšējā līmeņa apvalks, os objekts operētājsistēmas konfigurācijai un scenarios masīvs pārbaudei pēc build.

Validācija pierāda, ka atpazītiem laukiem ir pieņemamas formas. Tā nepierāda, ka katrs pakotne pastāv, ka katra pieprasītā uzvedība ir attēlota, vai ka image un testi izdosies. Nezināmi lauki var tikt ignorēti atpakaļsaderībai, tāpēc vienmēr pārbaudiet produkta atgriezto normalizēto recepti.

Kanoniskais apvalks

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

Neizmantojiet camelCase laukus, piemēram, baseImage vai startupScripts. Saderības validators pieņem dažas vecākas plakanas receptes, bet normalizētā izeja ligzdo OS laukus zem os. Jaunām integrācijām jānosūta kanoniskais formāts.

Augšējā līmeņa lauki

Papildu mērķim specifiski lauki ir avota ISO pārstrādei, Proxmox viesa payload, policy izcelsmei un delivery integrācijām. Izmantojiet redaktoru vai API līgumu izvietotajai versijai, nevis kopējiet vecu piemēru.

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 ir pc, phone vai raspberry_pi; atbalstītās ierīces vērtības ir mērķim specifiskas. architecture ir x86_64 vai aarch64. GPU vērtības nosauc atbalstītu ražotāju vai kombināciju. Tās ir deklarētas prasības, ne pierādījums, ka iegūtais image tika testēts atbilstošā fiziskā aparatūrā.

OS objekts

Bieži os lauki:

Integrity vai security lauka klātbūtne ir konfigurācijas nodoms. Tā nav pierādījums, ka mehānisms tika izveidots, piemērots runtime vai kvalificēts atbilstības režīmam. Pieprasiet atbilstošus build un test pierādījumus.

Users

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

Lietotāju un grupu vārdi ir ierobežoti ar drošām Linux konta rakstzīmēm un garumu. Ja password nav iestatīts, tiek izveidots ar paroli bloķēts konts tikai atslēgām vai izvietošanas laika credentials. Izvairieties no credentials vienkāršā tekstā saglabātās receptēs.

Services

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

config ir pakalpojumam specifisks. Sintaktiski derīga atslēga joprojām var tikt ignorēta ģeneratora, kas to neimplementē. Pārbaudiet normalizēto recepti, ģenerēto konfigurāciju un viesa uzvedību.

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 tipi ir atkarīgi no mērķa (calamares, anaconda vai elster-mobile). Ieslēdzot installer, jāveic vienreizējs diska instalācijas tests; ikona live darbvirsmā nepierāda, ka instalācija darbojas.

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

Tiek pieņemti ne vairāk kā 32 startup_scripts. Komandām jābūt netukšām un tās nedrīkst saturēt NUL baitus. Uztveriet tās kā root līmeņa shell kodu, ja run_as nesaka citādi; pārskatiet idempotenci, pēdiņas, tīkla kļūdas un slepeno datu atklāšanu.

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

Scenārijs var definēt arī topology ar VM un tīkliem, benchmark formāta testus un CIS iestatījumus. Ja topoloģija nav norādīta, tiek izmantots parastais viena VM ceļš. Assertions vajag cilvēkam lasāmu aprakstu un tipam specifiskus params. Nezināmi assertion tipi var iziet shēmas parsēšanu, tāpēc pirms to uzskatīšanas par pierādījumu apstipriniet runner atbalstu.

Pilns minimāls piemērs

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

Validācijas plūsma

1. Validējiet JSON caur pašreizējo receptes redaktoru, API vai MCP rīku validate_recipe.
2. Salīdziniet atgriezto normalizēto recepti ar sākotnējo pieprasījumu.
3. Nezināmus atmestos laukus uzskatiet par receptes defektu, ne par veiksmīgu konfigurāciju.
4. Build sāciet tikai tad, kad skaidras prasības ir attēlotas.
5. Pārskatiet ģenerētos pierādījumus un palaidiet assertions pret iegūto viesi.

Skatiet Your First Build kļūdu un lejupielādes atjaunošanas norādēm.