レシピスキーマ

OpenFactory レシピでは、snake_case JSON を使用します。正規フォーマットには小さいトップレベルのエンベロープ、オペレーティングシステム構成用の os オブジェクト、およびビルド後の検証用の scenarios 配列。

検証により、認識されたフィールドが許容可能な形状であることが証明されます。そうではありませんすべてのパッケージが存在すること、要求されたすべての動作が表現されたことを証明する、またはイメージとテストは成功します。未知のフィールドは逆方向では無視される可能性があります互換性があるため、常に、によって返される正規化されたレシピを検査してください。製品。

正規エンベロープ


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

baseImage や startupScripts などのキャメルケースフィールドは使用しないでください。の互換性バリデータは一部の古いフラットレシピを受け入れますが、出力は正規化されます OS フィールドを os の下にネストします。新しい統合では正規形式を送信する必要があります。

最上位フィールド

|フィールド |タイプ |必須/デフォルト |意味 | |------|------|------||------| | name |文字列 |必須; 3 ～ 100 文字 |安定した内部レシピ名 | | display_name |文字列またはnull |オプション。 1 ～ 100 文字 |人に面した名前 | | description |文字列 | "" |意図した結果と境界 | | base_image |文字列 | debian-trixie |配布/ビルドターゲット。現在のコンソールリストを使用する | | task |文字列またはnull |オプション |運用目標 | | executor |文字列またはnull |オプション |タスクの実行が期待されるテクノロジー | | use_case |文字列 | General |主な使用例 | | hardware |オブジェクト |デフォルトを以下に示します |導入要件 | | os |オブジェクト |空/デフォルトのオブジェクト | OS パッケージ、ユーザー、サービス、セキュリティ、デスクトップ、インストーラー、スクリプト | | scenarios |配列 | [] |テストのトポロジと目的 | | publish_to |文字列配列 | ["local"] |要求された出力先 | | delivery |オブジェクト | {} |追加の宣言された配信構成 | | community |ブール値 | false |コミュニティとマーケットプレイスの可視性を要求します。出版ポリシーは引き続き適用されます。

ソース ISO リマスタリング、Proxmox ゲスト用の高度なターゲット固有フィールドが存在します。ペイロード、ポリシーの来歴、配信の統合。エディターまたは API を使用する古い例をコピーするのではなく、デプロイされたリリースの契約を締結します。

ハードウェア


{
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "gpu": null,
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  }
}

platform は、pc、phone、または raspberry_pi です。サポートされているデバイスの値は、ターゲット固有。 architecture は x86_64 または aarch64 です。 GPU 値の名前 a サポートされているベンダーまたはベンダーの組み合わせ。これらは宣言された要件ではなく、結果のイメージが一致する物理ハードウェアでテストされたことを証明します。

OS オブジェクト

共通の os フィールドは次のとおりです。

フィールド	タイプ	目的
`features`	文字列配列	登録された機能モジュール
`packages`	文字列配列	リクエストするネイティブパッケージ
`excluded_packages`	文字列配列	機能拡張後に存在しない必要があるパッケージ
`custom_packages`	配列	サポートされているビルドパスを通じてパッケージ化するソースリポジトリ
`package_overrides`	配列	明示的な追加、削除、または置換操作
`extra_repos`	文字列配列	追加のリポジトリ。信頼とキーの処理はまだ検討が必要です。
`services`	配列	名前付きサービスの有効化と構成
`users`	配列	イメージローカルアカウントとグループ
`security`	オブジェクト	強化、暗号化、監査、SELinux、fail2ban の選択肢を宣言
`networking`	オブジェクト	インターフェイスとネットワークの目的
`desktop_settings`	オブジェクト	デスクトップの外観と動作
`branding`	オブジェクト	ディストリビューションのアイデンティティと資産
`runtime`	オブジェクト	初期化/サービス/パッケージマネージャー ID
`boot`	オブジェクト	カーネル引数と GRUB の選択
`installer`	オブジェクト	ディスクへのインストール構成
`persistence`	オブジェクト	ライブ永続性とゾーンポリシー
`integrity`	オブジェクト	要求された dm-verity、セキュアブート、および IMA/EVM 設定
`file_attachments`	配列	以前にアップロードされたファイルは `file_id`
`startup_scripts`	配列	制限された systemd ワンショットスクリプト
`time_zone`	文字列またはnull	画像のタイムゾーン設定

整合性フィールドまたはセキュリティフィールドの存在は、構成の意図によるものです。それはメカニズムが作成された、実行時に強制された、または認定されたという証拠ではないコンプライアンス体制のために。一致するビルドとテストの証拠が必要です。

ユーザー


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

ユーザー名とグループ名は、安全な Linux アカウントの文字と長さに制限されます。 password を未設定のままにすると、キーのみのパスワードロックされたアカウントが作成されます。導入時の認証情報ワークフロー。保存されたファイルに平文の認証情報を使用しないようにするレシピ。

サービス


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

config はサービス固有です。構文的に有効なキーは依然として無視される可能性がありますそれを実装していないジェネレーター。生成された正規化されたレシピを確認します構成とゲストの動作。

セキュリティとインストーラー


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

インストーラーのタイプはターゲットに依存します (calamares、anaconda、または elster-mobile)。インストーラーを有効にした後、使い捨てディスクを有効にする必要がありますインストールテスト;ライブデスクトップのアイコンは、インストールが機能していることを証明するものではありません。

起動スクリプト


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

最大 32 個の起動スクリプトが受け入れられます。コマンドは空であってはなりません。 NUL バイトが含まれています。 run_as が指定しない限り、それらを root 対応のシェルコードとして扱います。それ以外の場合。冪等性、引用、ネットワーク障害、秘密漏洩を確認します。

シナリオとアサーション


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

シナリオでは、VM とネットワークを使用した topology をベンチマーク形式で定義することもできますテストと CIS 設定。省略されたトポロジはデフォルトで通常の単一 VM になります。パス。アサーションには、人間が読める説明と型固有のパラメータが必要です。不明なアサーションタイプはスキーマ解析で生き残る可能性があるため、ランナーを確認してください証拠として扱う前に、それらをサポートします。

完全な最小限の例


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

検証ワークフロー

現在のレシピエディター、API、または MCP を通じて JSON を検証します。 validate_recipe ツール。
返された正規化されたレシピを元のリクエストと比較します。
ドロップされた未知のフィールドは成功したものとしてではなく、レシピの欠陥として扱います。構成。
明示的な要件が示された後にのみビルドします。
生成された証拠を検査し、結果のゲストに対してアサーションを実行します。

失敗とダウンロードについては、Your First Build を参照してください。回復指導。