Schema ricetta

Le ricette OpenFactory usano JSON snake_case. Il formato canonico ha piccola envelope top-level, oggetto os per configurazione sistema operativo e array scenarios per verifica post-build.

La validazione prova che campi riconosciuti abbiano forme accettabili. Non prova che ogni pacchetto esista, ogni comportamento richiesto sia rappresentato o immagine e test riescano. Campi sconosciuti possono essere ignorati per compatibilità backward, quindi ispeziona sempre ricetta normalizzata restituita dal prodotto.

Envelope canonica

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

Non usare campi camelCase come baseImage o startupScripts. Il validator compatibilità accetta alcune ricette flat più vecchie, ma output normalizzato annida campi OS sotto os. Nuove integrazioni devono inviare formato canonico.

Campi top-level

Campi avanzati specifici target esistono per remastering ISO sorgente, payload guest Proxmox, provenienza policy e integrazioni delivery. Usa editor o contratto API per release deployata invece di copiare esempio vecchio.

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 è pc, phone o raspberry_pi; valori device supportati sono specifici target. architecture è x86_64 o aarch64. Valori GPU nominano vendor supportato o combinazione vendor. Sono requisiti dichiarati, non prova che immagine risultante sia testata su hardware fisico corrispondente.

Oggetto OS

Campi os comuni sono:

Presenza campo integrity o security è intento configurazione. Non è evidenza che meccanismo sia prodotto, applicato a runtime o qualificato per regime conformità. Richiedi evidenza build e test corrispondente.

Utenti

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

Nomi utente e gruppo sono limitati a caratteri account Linux sicuri e lunghezza. Lasciare password non impostato crea account bloccato password per workflow chiave-only o credenziale al deploy. Evita credenziali plaintext in ricette salvate.

Servizi

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

config è specifico servizio. Chiave sintatticamente valida può essere ignorata da generatore che non la implementa. Verifica ricetta normalizzata, configurazione generata e comportamento guest.

Sicurezza e 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"
    }
  }
}

Tipi installer dipendono da target (calamares, anaconda o elster-mobile). Abilitare installer deve essere seguito da test install su disco usa e getta; icona in desktop live non prova che installazione funzioni.

Script di avvio

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

Sono accettati al massimo 32 script di avvio. Comandi devono essere non vuoti e non possono contenere byte NUL. Trattali come codice shell con capacità root salvo diversa indicazione in run_as; rivedi idempotenza, quoting, fallimento rete ed esposizione secret.

Scenari e asserzioni

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

Uno scenario può anche definire topology con VM e reti, test formato benchmark e impostazioni CIS. Topologia omessa default al normale percorso single-VM. Asserzioni richiedono descrizione leggibile e params specifici tipo. Tipi asserzione sconosciuti possono sopravvivere parsing schema, quindi conferma supporto runner prima di trattarli come evidenza.

Esempio minimo completo

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

Flusso validazione

1. Valida JSON tramite editor ricetta corrente, API o tool MCP validate_recipe.
2. Confronta ricetta normalizzata restituita con richiesta originale.
3. Tratta campi unknown scartati come difetto ricetta, non configurazione riuscita.
4. Builda solo dopo che requisiti espliciti sono rappresentati.
5. Ispeziona evidenza generata ed esegui asserzioni sul guest risultante.

Vedi La tua prima build per guida recovery fallimento e download.