Schema de receita

Receitas OpenFactory usam JSON snake_case. O formato canônico tem envelope top-level pequeno, objeto os para configuração de sistema operacional e array scenarios para verificação pós-build.

Validação prova que campos reconhecidos têm formatos aceitáveis. Não prova que todo pacote existe, todo comportamento solicitado foi representado, ou imagem e testes succeederão. Campos desconhecidos podem ser ignorados por compatibilidade retroativa; inspecione sempre receita normalizada retornada pelo produto.

Envelope canônico

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

Não use campos camelCase como baseImage ou startupScripts. Validador de compatibilidade aceita algumas receitas flat antigas, mas saída normalizada aninha campos OS em os. Novas integrações devem enviar formato canônico.

Campos top-level

Campos avançados específicos de alvo existem para remasterização de ISO de origem, payloads guest Proxmox, proveniência de política e integrações de entrega. Use editor ou contrato API da release implantada em vez de copiar exemplo antigo.

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 é pc, phone ou raspberry_pi; valores de device suportados são específicos de alvo. architecture é x86_64 ou aarch64. Valores GPU nomeiam vendor suportado ou combinação. São requisitos declarados, não prova de imagem testada em hardware físico correspondente.

Objeto OS

Campos comuns de os:

Presença de campo integrity ou security é intenção de configuração. Não é evidência de mecanismo produzido, aplicado em runtime ou qualificado para regime de conformidade. Exija evidência de build e teste correspondente.

Usuários

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

Nomes de usuário e grupo limitam-se a caracteres seguros de conta Linux e comprimento. Deixar password unset cria conta com senha bloqueada para workflows só com chave ou credencial na hora do deployment. Evite credenciais em texto claro em receitas salvas.

Serviços

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

config é específico de serviço. Chave sintaticamente válida ainda pode ser ignorada por gerador que não implementa. Verifique receita normalizada, configuração gerada e comportamento no guest.

Segurança e instalador

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

Tipos de instalador dependem de alvo (calamares, anaconda ou elster-mobile). Habilitar instalador deve ser seguido de teste install-to-disk em disco descartável; ícone em desktop ao vivo não prova que instalação funciona.

Scripts de startup

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

No máximo 32 scripts de startup são aceitos. Comandos devem ser não vazios e não podem conter bytes NUL. Trate como código shell com capacidade root salvo run_as dizer o contrário; revise idempotência, quoting, falha de rede e exposição de segredo.

Cenários e asserções

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

Cenário também pode definir topology com VMs e redes, testes formato benchmark e configurações CIS. Topologia omitida default para caminho single-VM normal. Asserções precisam descrição legível e params específicos de tipo. Tipos de asserção desconhecidos podem sobreviver parsing de schema; confirme suporte do runner antes de tratá-los como evidência.

Exemplo mínimo completo

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

Fluxo de validação

1. Valide JSON pelo editor de receita atual, API ou ferramenta MCP validate_recipe.
2. Compare receita normalizada retornada com pedido original.
3. Trate campos desconhecidos descartados como defeito na receita, não configuração bem-sucedida.
4. Construa só depois que requisitos explícitos estiverem representados.
5. Inspecione evidência gerada e rode asserções contra guest resultante.

Veja Seu primeiro build para orientação de recovery em falha e download.