Receptschema

OpenFactory-recept använder JSON i snake_case. Det kanoniska formatet har ett litet kuvert på topnivå, ett os-objekt för operativsystemkonfiguration och en scenarios-array för verifiering efter build.

Validering visar att kända fält har acceptabla former. Den visar inte att varje paket finns, att varje begärt beteende har återspeglats, eller att image och tester lyckas. Okända fält kan ignoreras för bakåtkompatibilitet; granska alltid det normaliserade recept som produkten returnerar.

Kanoniskt kuvert

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

Använd inte camelCase-fält som baseImage eller startupScripts. Kompatibilitets- validatorn accepterar vissa äldre platta recept, men normaliserad utdata nästlar OS-fält under os. Nya integrationer ska skicka det kanoniska formatet.

Fält på topnivå

Avancerade målspecifika fält finns för remastering av käll-ISO, Proxmox-gästpayloads, policy-provenance och deliveryintegrationer. Använd editorn eller API-kontraktet för den utrullade releasen i stället för att kopiera ett gammalt exempel.

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 är pc, phone eller raspberry_pi; stödda enhetsvärden är målspecifika. architecture är x86_64 eller aarch64. GPU-värden namnger en stödd leverantör eller kombination. Det här är deklarerade krav, inte bevis att en resulterande image testats på matchande fysisk hårdvara.

OS-objekt

Vanliga os-fält:

Närvaro av ett integrity- eller security-fält är konfigurationsavsikt. Det är inte bevis att mekanismen producerades, verkställdes vid runtime eller kvalificerades för ett compliance-regime. Kräv matchande build- och testbevis.

Användare

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

Användar- och gruppnamn begränsas till säkra Linux-kontotecken och längd. Om password inte sätts skapas ett lösenordslåst konto för endast-nyckel- eller credentials-vid- deployment-arbetsflöden. Undvik plaintext-credentials i sparade recept.

Tjänster

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

config är tjänstespecifik. En syntaktiskt giltig nyckel kan fortfarande ignoreras av en generator som inte implementerar den. Verifiera normaliserat recept, genererad konfiguration och gästbeteende.

Säkerhet och 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"
    }
  }
}

Installertyp beror på mål (calamares, anaconda eller elster-mobile). Aktivering av en installer ska följas av ett installationstest på engångsdisk; en ikon på ett live- skrivbord bevisar inte att installationen fungerar.

Startup-skript

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

Högst 32 startup-skript accepteras. Kommandon får inte vara tomma och får inte innehålla NUL-bytes. Behandla dem som root-kapabel shellkod om inte run_as säger annat; granska idempotens, quoting, nätverksfel och exponering av secrets.

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

Ett scenario kan också definiera en topology med VM:ar och nätverk, benchmark-formattester och CIS-inställningar. Utelämnad topology faller tillbaka till den normala single-VM-vägen. Assertions behöver en läsbar beskrivning och typespecifika params. Okända assertionstyper kan överleva schemaparsning; bekräfta att runnern stöder dem innan du behandlar dem som bevis.

Fullständigt minimalt exempel

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

Valideringsarbetsflöde

1. Validera JSON via aktuell recepteditor, API eller MCP-verktyget validate_recipe.
2. Jämför det returnerade normaliserade receptet med den ursprungliga begäran.
3. Behandla borttagna okända fält som ett receptfel, inte som lyckad konfiguration.
4. Bygg först när explicita krav är representerade.
5. Granska genererade bevis och kör assertions mot resulterande gäst.

Se Din första build för hjälp vid fel och återhämtning av nedladdningar.