Schema rețetei

Rețetele OpenFactory folosesc JSON în snake_case. Formatul canonic are o învelitoare mică la nivel superior, un obiect os pentru configurarea sistemului de operare și un tablou scenarios pentru verificarea după build.

Validarea arată că câmpurile recunoscute au forme acceptabile. Nu dovedește că fiecare pachet există, că fiecare comportament cerut a fost reprezentat, sau că imaginea și testele vor reuși. Câmpurile necunoscute pot fi ignorate pentru compatibilitate înapoi; inspectați mereu rețeta normalizată returnată de produs.

Învelitoarea canonică

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

Nu folosiți câmpuri camelCase precum baseImage sau startupScripts. Validatorul de compatibilitate acceptă unele rețete plate mai vechi, dar ieșirea normalizată imbrică câmpurile OS sub os. Integrările noi ar trebui să trimită formatul canonic.

Câmpuri de nivel superior

Există câmpuri avansate specifice țintei pentru remasterizarea ISO sursă, payload-uri guest Proxmox, proveniența politicilor și integrări de livrare. Folosiți editorul sau contractul API al versiunii implementate în loc să copiați un exemplu vechi.

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 este pc, phone sau raspberry_pi; valorile de dispozitiv suportate depind de țintă. architecture este x86_64 sau aarch64. Valorile GPU numesc un furnizor suportat sau o combinație. Acestea sunt cerințe declarate, nu dovadă că imaginea rezultată a fost testată pe hardware fizic potrivit.

Obiectul OS

Câmpuri uzuale os:

Prezența unui câmp integrity sau security exprimă intenția de configurare. Nu este dovadă că mecanismul a fost produs, aplicat la runtime sau calificat pentru un regim de conformitate. Cereți dovezi de build și test potrivite.

Utilizatori

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

Numele de utilizator și grup sunt limitate la caractere sigure și lungime pentru conturi Linux. Fără password setat se creează un cont blocat cu parolă pentru fluxuri doar cu cheie sau cu credențiale la implementare. Evitați credențialele în clar în rețetele salvate.

Servicii

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

config depinde de serviciu. O cheie sintactic validă poate fi ignorată de un generator care nu o implementează. Verificați rețeta normalizată, configurația generată și comportamentul guest.

Securitate ș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"
    }
  }
}

Tipurile de installer depind de țintă (calamares, anaconda sau elster-mobile). Activarea installerului trebuie urmată de un test de instalare pe disc de unică folosință; o pictogramă pe desktopul live nu dovedește că instalarea funcționează.

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

Se acceptă cel mult 32 de startup scripturi. Comenzile trebuie să fie nevide și nu pot conține octeți NUL. Tratați-le ca cod shell cu drepturi root, dacă run_as nu spune altfel; revizuiți idempotența, quoting, eșecul rețelei și expunerea secretelor.

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

Un scenariu poate defini și topology cu VM-uri și rețele, teste în format benchmark și setări CIS. O topologie omisă folosește implicit calea obișnuită cu un singur VM. Assertions necesită un description lizibil și parametri specifici tipului. Tipurile necunoscute de assertions pot trece parsarea schemei; confirmați suportul runnerului înainte să le tratați ca dovadă.

Exemplu minimal complet

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

Flux de validare

1. Validați JSON-ul prin editorul de rețete actual, API sau instrumentul MCP validate_recipe.
2. Comparați rețeta normalizată returnată cu cererea originală.
3. Tratați câmpurile necunoscute eliminate ca defect al rețetei, nu ca configurare reușită.
4. Construiți doar după ce cerințele explicite sunt reprezentate.
5. Inspectați dovezile generate și rulați assertions pe guestul rezultat.

Consultați Primul build pentru ghid la eșec și recuperarea descărcării.