Schemat receptury

Receptury OpenFactory używają JSON w snake_case. Format kanoniczny ma małą obwolutę na najwyższym poziomie, obiekt os do konfiguracji systemu operacyjnego oraz tablicę scenarios do weryfikacji po buildzie.

Walidacja pokazuje, że rozpoznane pola mają dopuszczalne kształty. Nie dowodzi, że każdy pakiet istnieje, że każde żądane zachowanie zostało odwzorowane, ani że obraz i testy się powiodą. Nieznane pola mogą być ignorowane dla wstecznej kompatybilności; zawsze sprawdzaj znormalizowaną recepturę zwróconą przez produkt.

Obwoluta kanoniczna

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

Nie używaj pól camelCase, takich jak baseImage czy startupScripts. Walidator zgodności akceptuje niektóre starsze płaskie receptury, ale znormalizowane wyjście zagnieżdża pola OS pod os. Nowe integracje powinny wysyłać format kanoniczny.

Pola najwyższego poziomu

Zaawansowane pola zależne od celu dotyczą remasteringu ISO źródłowego, ładunków gościa Proxmox, pochodzenia polityk i integracji dostawy. Użyj edytora lub kontraktu API wdrożonej wersji zamiast kopiować stary przykład.

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 to pc, phone lub raspberry_pi; obsługiwane wartości urządzeń zależą od celu. architecture to x86_64 lub aarch64. Wartości GPU nazywają obsługiwanego dostawcę lub kombinację. To zadeklarowane wymagania, a nie dowód, że wynikowy obraz testowano na pasującym sprzęcie fizycznym.

Obiekt OS

Typowe pola os:

Obecność pola integrity lub security to intencja konfiguracji. Nie jest dowodem, że mechanizm został wyprodukowany, egzekwowany w runtime ani kwalifikowany do reżimu zgodności. Wymagaj pasujących dowodów buildu i testów.

Użytkownicy

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

Nazwy użytkowników i grup są ograniczone do bezpiecznych znaków kont Linux i długości. Pozostawienie password nieset tworzy konto zablokowane hasłem dla workflow tylko-klucz lub poświadczeń w czasie wdrożenia. Unikaj poświadczeń w plaintext w zapisanych recepturach.

Usługi

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

config zależy od usługi. Składniowo poprawny klucz może być ignorowany przez generator, który go nie implementuje. Sprawdź znormalizowaną recepturę, wygenerowaną konfigurację i zachowanie gościa.

Bezpieczeństwo i 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"
    }
  }
}

Typy installera zależą od celu (calamares, anaconda lub elster-mobile). Włączenie installera musi być poparte testem instalacji na dysku jednorazowym; ikona na live pulpicie nie dowodzi, że instalacja działa.

Skrypty startowe

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

Akceptowanych jest co najwyżej 32 skryptów startowych. Polecenia muszą być niepuste i nie mogą zawierać bajtów NUL. Traktuj je jako kod shell z uprawnieniami root, chyba że run_as mówi inaczej; sprawdź idempotentność, quoting, awarie sieci i ujawnienie sekretów.

Scenariusze i asercje

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

Scenariusz może też definiować topology z VM i sieciami, testy w formacie benchmark oraz ustawienia CIS. Pominięta topologia domyślnie używa zwykłej ścieżki single-VM. Asercje wymagają czytelnego opisu i params specyficznych dla typu. Nieznane typy asercji mogą przejść parsowanie schematu; potwierdź wsparcie runnera, zanim potraktujesz je jako dowód.

Pełny minimalny przykład

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

1. Waliduj JSON przez aktualny edytor receptur, API lub narzędzie MCP validate_recipe.
2. Porównaj zwróconą znormalizowaną recepturę z pierwotnym żądaniem.
3. Traktuj odrzucone nieznane pola jako wadę receptury, a nie udaną konfigurację.
4. Buduj dopiero po odwzorowaniu jawnych wymagań.
5. Sprawdź wygenerowane dowody i uruchom asercje względem wynikowego gościa.

Zobacz Twój pierwszy build, aby odzyskać po błędach i problemach z pobieraniem.