Esquema de recetas

Las recetas OpenFactory usan JSON snake_case. El formato canónico tiene un sobre de nivel superior pequeño, un objeto os para configuración del sistema operativo y un array scenarios para verificación post-compilación.

La validación prueba que los campos reconocidos tienen formas aceptables. No prueba que exista todo paquete, que todo comportamiento solicitado estuviera representado ni que la imagen y las pruebas tendrán éxito. Los campos desconocidos pueden ignorarse por compatibilidad hacia atrás; inspecciona siempre la receta normalizada devuelta por el producto.

Sobre canónico

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

No uses campos camelCase como baseImage o startupScripts. El validador de compatibilidad acepta algunas recetas planas antiguas, pero la salida normalizada anida campos OS bajo os. Las integraciones nuevas deben enviar el formato canónico.

Campos de nivel superior

Existen campos avanzados específicos del destino para remasterización source-ISO, payloads guest Proxmox, procedencia de política e integraciones de entrega. Usa el editor o contrato API de la versión desplegada en lugar de copiar un ejemplo antiguo.

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 es pc, phone o raspberry_pi; los valores de dispositivo admitidos son específicos del destino. architecture es x86_64 o aarch64. Los valores GPU nombran un vendor o combinación admitida. Son requisitos declarados, no prueba de que una imagen resultante se probó en hardware físico coincidente.

Objeto OS

Los campos habituales de os son:

La presencia de un campo de integridad o seguridad es intención de configuración. No es evidencia de que el mecanismo se produjo, se aplicó en runtime o se calificó para un régimen de cumplimiento. Exige evidencia de compilación y prueba acorde.

Users

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

Los nombres de usuario y grupo están limitados a caracteres seguros de cuenta Linux y longitud. Dejar password sin definir crea una cuenta bloqueada por contraseña para flujos solo con clave o credenciales en tiempo de despliegue. Evita credenciales en texto plano en recetas guardadas.

Services

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

config es específico del servicio. Una clave sintácticamente válida puede ignorarse aún por un generador que no la implementa. Verifica la receta normalizada, configuración generada y comportamiento del guest.

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

Los tipos de instalador dependen del destino (calamares, anaconda o elster-mobile). Habilitar un instalador debe ir seguido de una prueba de instalación en disco desechable; un icono en un escritorio en vivo no prueba que la instalación funcione.

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 aceptan como máximo 32 scripts de arranque. Los comandos deben ser no vacíos y no pueden contener bytes NUL. Trátalos como código shell con capacidad root salvo que run_as indique lo contrario; revisa idempotencia, comillas, fallo de red y exposición de secretos.

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

Un escenario también puede definir topology con VM y redes, pruebas en formato benchmark y ajustes CIS. Una topología omitida usa por defecto la ruta habitual de una sola VM. Las aserciones necesitan descripción legible y params específicos del tipo. Los tipos de aserción desconocidos pueden sobrevivir al parseo del esquema; confirma que el runner los admite antes de tratarlos como evidencia.

Complete Minimal Example

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

Validation Workflow

1. Valida el JSON mediante el editor de recetas actual, API o herramienta MCP validate_recipe.
2. Compara la receta normalizada devuelta con la solicitud original.
3. Trata campos desconocidos descartados como defecto de la receta, no como configuración exitosa.
4. Compila solo después de que los requisitos explícitos estén representados.
5. Inspecciona evidencia generada y ejecuta aserciones contra el guest resultante.

Consulta Tu primera compilación para orientación de recuperación ante fallos y descarga.