Schéma de recette

Les recettes OpenFactory utilisent du JSON en snake_case. Le format canonique a une petite enveloppe de premier niveau, un objet os pour la configuration du système d’exploitation et un tableau scenarios pour la vérification post-build.

La validation prouve que les champs reconnus ont des formes acceptables. Elle ne prouve pas que chaque paquet existe, que chaque comportement demandé a été représenté, ni que l’image et les tests réussiront. Les champs inconnus peuvent être ignorés pour compatibilité ascendante ; inspectez donc toujours la recette normalisée renvoyée par le produit.

Enveloppe canonique

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

N’utilisez pas de champs camelCase comme baseImage ou startupScripts. Le validateur de compatibilité accepte certaines anciennes recettes plates, mais la sortie normalisée imbrique les champs OS sous os. Les nouvelles intégrations doivent envoyer le format canonique.

Champs de premier niveau

Des champs avancés propres à la cible existent pour remasterisation ISO source, charges invité Proxmox, provenance politique et intégrations de livraison. Utilisez l’éditeur ou le contrat API de la version déployée plutôt que de copier un ancien exemple.

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 est pc, phone ou raspberry_pi ; les valeurs d’appareil supportées dépendent de la cible. architecture est x86_64 ou aarch64. Les valeurs GPU nomment un fournisseur ou une combinaison supportée. Ce sont des exigences déclarées, pas une preuve qu’une image résultante a été testée sur du matériel physique correspondant.

Objet OS

Les champs os courants sont :

La présence d’un champ integrity ou security est une intention de configuration. Ce n’est pas une preuve que le mécanisme a été produit, appliqué à l’exécution ou qualifié pour un régime de conformité. Exigez des preuves de build et de test correspondantes.

Utilisateurs

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

Les noms d’utilisateur et de groupe sont limités à des caractères de compte Linux sûrs et à une longueur. Laisser password non défini crée un compte verrouillé par mot de passe pour workflows clé seule ou identifiants au déploiement. Évitez identifiants en clair dans recettes enregistrées.

Services

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

config est propre au service. Une clé syntaxiquement valide peut encore être ignorée par un générateur qui ne l’implémente pas. Vérifiez recette normalisée, configuration générée et comportement invité.

Sécurité et installateur

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

Les types d’installateur dépendent de la cible (calamares, anaconda ou elster-mobile). Activer un installateur doit être suivi d’un test d’installation sur disque jetable ; une icône sur un bureau live n’est pas une preuve que l’installation fonctionne.

Scripts de démarrage

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

Au plus 32 scripts de démarrage sont acceptés. Les commandes doivent être non vides et ne peuvent pas contenir d’octets NUL. Traitez-les comme du code shell capable root sauf si run_as indique le contraire ; relisez idempotence, quoting, échec réseau et exposition de secrets.

Scénarios et 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 scénario peut aussi définir une topology avec VM et réseaux, tests au format benchmark et paramètres CIS. Une topologie omise revient au chemin single-VM normal. Les assertions ont besoin d’une description lisible et de params propres au type. Des types d’assertion inconnus peuvent survivre au parsing de schéma ; confirmez que le runner les supporte avant de les traiter comme preuve.

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

Workflow de validation

1. Validez le JSON via l’éditeur de recette courant, l’API ou l’outil MCP validate_recipe.
2. Comparez la recette normalisée renvoyée avec la demande d’origine.
3. Traitez les champs inconnus abandonnés comme un défaut de recette, pas comme une configuration réussie.
4. Ne construisez qu’après représentation des exigences explicites.
5. Inspectez les preuves générées et exécutez des assertions contre l’invité résultant.

Voir Votre premier build pour la reprise en cas d’échec et de téléchargement.