Skip to Content
Getting StartedCapire le ricette

Capire le ricette

Un BuildRecipe è la specifica normalizzata che OpenFactory invia alla pipeline immagini. La chat può aiutare a scriverla, ma ricetta, snapshot sorgente, file generati ed evidenze test definiscono una build.

Il modello mentale

La ricetta canonica ha quattro strati principali:

  1. Identità e target: nome, descrizione, immagine base e intento hardware.
  2. Sistema operativo: feature, pacchetti, servizi, utenti, sicurezza, desktop, installer, allegati e script di avvio sotto os.
  3. Verifica: uno o più scenari con test integrati e asserzioni personalizzate.
  4. Intento di consegna: destinazioni di pubblicazione richieste e impostazioni di delivery opzionali.
{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Small Debian image with explicit smoke tests.",
  "base_image": "debian-trixie",
  "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"],
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {"port": 22, "disable_password_auth": true}
      }
    ],
    "security": {
      "hardening_level": "standard",
      "audit_logging": true
    }
  },
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"]
    }
  ],
  "publish_to": ["local"]
}

Usa snake_case. Le nuove integrazioni non devono inviare forme legacy come baseImage, features a livello top o startupScripts.

Tre controlli, tre risposte diverse

Validazione schema

La validazione risponde: «I dati riconosciuti hanno una forma accettabile?» Non dimostra che i pacchetti esistano o che il comportamento funzioni. Alcuni campi sconosciuti sono ignorati per compatibilità, quindi un successo di validazione può comunque omettere una richiesta importante.

Confronta sempre la ricetta normalizzata restituita con chat e requisiti originali. Un desktop, applicazione, installer, allegato o test mancante è un difetto di ricetta anche se la validazione dice valid.

Evidenza build

Una build riuscita risponde: «La pipeline ha prodotto un artefatto?» Non dimostra che ogni feature prevista sia finita nell’immagine. Ispeziona inventario pacchetti, provenienza sorgente, avvisi ed evidenze degli stage di build.

Verifica guest

I test guest rispondono a domande runtime strette: se la VM ha avviato, un servizio è attivo, una porta è in ascolto, un file ha contenuto atteso o un’applicazione si è avviata. Un’asserzione superata supporta solo il comportamento che ha osservato davvero.

Le impostazioni di sicurezza sono intento

I valori hardening_level accettati sono minimal, standard e strict, ma queste etichette non sono profili di conformità portabili. I generatori target possono interpretarli in modo diverso. Se serve un benchmark, seleziona il benchmark applicabile esatto e conserva i risultati per controllo; non inferire conformità CIS da strict.

Allo stesso modo, disk_encryption, audit_logging, SELinux, fail2ban, Secure Boot, dm-verity e impostazioni installer richiedono test artefatto e runtime corrispondenti.

Chat e ownership della ricetta

Quando validi o modifichi una ricetta scritta in chat, la conversazione esistente resta parte del contesto di authoring. La validazione deve affinare la ricetta corrente, non sostituirla silenziosamente con un default generico. Comunque, la ricetta normalizzata è l’ultimo checkpoint prima della build.

Per ogni requisito materiale:

  • trova il campo normalizzato corrispondente;
  • conferma valore e scope target;
  • aggiungi un’asserzione dove la prova runtime è possibile; e
  • conserva lavoro solo-deploy come avviso esplicito invece di fingere che sia avvenuto durante la build immagine.

Checklist di revisione

  • Immagine base e architettura sono corrette?
  • Tutte le feature desktop e applicazione richieste sono presenti?
  • Le sorgenti esterne sono pin e con licenza per l’uso previsto?
  • I segreti sono assenti da campi ricetta e script salvati?
  • L’installer è configurato e testato su disco usa e getta se richiesto?
  • Gli scenari testano i criteri di accettazione reali?
  • Requisiti non supportati o solo al momento del deploy sono evidenziati?

Vedi Schema ricetta per il riferimento campi e La tua prima build per il flusso build e download.

La tua prima buildGuide di build