Oppskriftsskjema

OpenFactory-oppskrifter bruker JSON i snake_case. Det kanoniske formatet har en liten konvolutt på topnivå, et os-objekt for operativsystemkonfigurasjon og en scenarios-array for verifikasjon etter build.

Validering viser at gjenkjente felt har akseptable former. Den viser ikke at hver pakke finnes, at hver etterspurt oppførsel er representert, eller at image og tester lykkes. Ukjente felt kan ignoreres for bakoverkompatibilitet; gå alltid gjennom den normaliserte oppskriften produktet returnerer.

Kanonisk konvolutt

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

Ikke bruk camelCase-felt som baseImage eller startupScripts. Kompatibilitets- validatoren godtar noen eldre flate oppskrifter, men normalisert utdata nestler OS-felt under os. Nye integrasjoner bør sende det kanoniske formatet.

Felt på topnivå

Avanserte målspesifikke felt finnes for remastering av kilde-ISO, Proxmox-gjestpayloads, policy-provenance og deliveryintegrasjoner. Bruk editoren eller API-kontrakten for den utrullede releasen i stedet for å kopiere et gammelt eksempel.

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 er pc, phone eller raspberry_pi; støttede enhetsverdier er målspesifikke. architecture er x86_64 eller aarch64. GPU-verdier navngir en støttet leverandør eller kombinasjon. Dette er deklarerte krav, ikke bevis for at et resulterende image er testet på matchende fysisk maskinvare.

OS-objekt

Vanlige os-felt:

Tilstedeværelse av et integrity- eller security-felt er konfigurasjonsintent. Det er ikke bevis for at mekanismen ble produsert, håndhevet ved runtime eller kvalifisert for et compliance-regime. Krev matchende build- og testbevis.

Brukere

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

Bruker- og gruppenavn er begrenset til trygge Linux-kontotegn og lengde. Hvis password ikke settes, opprettes en passordlåst konto for kun-nøkkel- eller credentials-ved- deployment-arbeidsflyter. Unngå plaintext-credentials i lagrede oppskrifter.

Tjenester

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

config er tjenestespesifikk. En syntaktisk gyldig nøkkel kan fortsatt ignoreres av en generator som ikke implementerer den. Verifiser normalisert oppskrift, generert konfigurasjon og gjesteadferd.

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

Installertyper avhenger av mål (calamares, anaconda eller elster-mobile). Aktivering av en installer må følges av en installasjonstest på engangsdisk; et ikon på et live- skrivebord beviser ikke at installasjonen fungerer.

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øyst 32 startup-skript godtas. Kommandoer må ikke være tomme og kan ikke inneholde NUL-bytes. Behandle dem som root-kapabel shellkode med mindre run_as sier noe annet; gjennomgå idempotens, quoting, nettverksfeil og eksponering av secrets.

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

Et scenario kan også definere en topology med VM-er og nettverk, benchmark-formattester og CIS-innstillinger. Utelatt topology faller tilbake til den normale single-VM-stien. Assertions trenger en lesbar beskrivelse og typespesifikke params. Ukjente assertionstyper kan overleve schemaparsing; bekreft at runneren støtter dem før du behandler dem som bevis.

Fullstendig minimalt eksempel

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

Valideringsarbeidsflyt

1. Valider JSON via gjeldende oppskrifteditor, API eller MCP-verktøyet validate_recipe.
2. Sammenlign den returnerte normaliserte oppskriften med den opprinnelige forespørselen.
3. Behandle droppet ukjente felt som en feil i oppskriften, ikke som vellykket konfigurasjon.
4. Bygg først når eksplisitte krav er representert.
5. Gå gjennom generert bevis og kjør assertions mot resulterende gjest.

Se Din første build for hjelp ved feil og gjenoppretting av nedlastinger.