Opskriftsskema

OpenFactory-opskrifter bruger JSON i snake_case. Det kanoniske format har en lille konvolut på topniveau, et os-objekt til operativsystemkonfiguration og et scenarios-array til verifikation efter build.

Validering viser, at genkendte felter har acceptable former. Den viser ikke, at hver pakke findes, at hver anmodet adfærd er repræsenteret, eller at image og tests lykkes. Ukendte felter kan ignoreres af hensyn til bagudkompatibilitet; gennemgå altid den normaliserede opskrift, produktet returnerer.

Kanonisk konvolut

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

Brug ikke camelCase-felter som baseImage eller startupScripts. Kompatibilitets- validatoren accepterer nogle ældre flade opskrifter, men normaliseret output indlejrer OS-felter under os. Nye integrationer bør sende det kanoniske format.

Felter på topniveau

Avancerede målspecifikke felter findes til remastering af kilde-ISO, Proxmox-gæstpayloads, policy-provenance og deliveryintegrationer. Brug editoren eller API-kontrakten for den udrullede release i stedet for at 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; understøttede enhedsværdier er målspecifikke. architecture er x86_64 eller aarch64. GPU-værdier navngiver en understøttet leverandør eller kombination. Det er deklarerede krav, ikke bevis for, at et resulterende image er testet på matchende fysisk hardware.

OS-objekt

Almindelige os-felter:

Tilstedeværelse af et integrity- eller security-felt er konfigurationsintent. Det er ikke bevis for, at mekanismen blev produceret, håndhævet ved runtime eller kvalificeret til et compliance-regime. Kræv matchende build- og testbevis.

Brugere

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

Bruger- og gruppenavne er begrænset til sikre Linux-kontotegn og længde. Hvis password ikke sættes, oprettes en adgangskodelåst konto til kun-nøgle- eller credentials-ved- deployment-workflows. Undgå plaintext-credentials i gemte opskrifter.

Services

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

config er servicespecifik. En syntaktisk gyldig nøgle kan stadig ignoreres af en generator, der ikke implementerer den. Verificer normaliseret opskrift, genereret konfiguration og gæsteadfærd.

Sikkerhed 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 afhænger af mål (calamares, anaconda eller elster-mobile). Aktivering af en installer skal følges af en installationstest på engangsdisk; et ikon på et live- skrivebord beviser ikke, at installationen virker.

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

Højst 32 startup-scripts accepteres. Kommandoer må ikke være tomme og må ikke indeholde NUL-bytes. Behandl dem som root-kapabel shellkode, medmindre run_as siger andet; gennemgå idempotens, quoting, netværksfejl og eksponering af 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 netværk, benchmark-formattests og CIS-indstillinger. Udeladt topology falder tilbage til den normale single-VM-sti. Assertions kræver en læsbar beskrivelse og typespecifikke params. Ukendte assertionstyper kan overleve schemaparsning; bekræft at runneren understøtter dem, før du behandler dem som bevis.

Fuldstændigt 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"]
}

Valideringsworkflow

1. Valider JSON via den aktuelle opskrifteditor, API eller MCP-værktøjet validate_recipe.
2. Sammenlign den returnerede normaliserede opskrift med den oprindelige anmodning.
3. Behandl droppede ukendte felter som en fejl i opskriften, ikke som vellykket konfiguration.
4. Byg først når eksplicitte krav er repræsenteret.
5. Gennemgå genereret bevis og kør assertions mod den resulterende gæst.

Se Din første build for hjælp ved fejl og genopretning af downloads.