Skip to Content
Getting StartedEntendendo receitas

Entendendo receitas

Um BuildRecipe é a especificação normalizada que o OpenFactory envia ao pipeline de imagem. O chat pode ajudar a autoria, mas a receita, snapshots de origem, arquivos gerados e evidências de teste são o que definem um build.

O modelo mental

A receita canônica tem quatro camadas principais:

  1. Identidade e alvo: nome, descrição, imagem base e intenção de hardware.
  2. Sistema operacional: features, pacotes, serviços, usuários, segurança, desktop, instalador, anexos e scripts de startup em os.
  3. Verificação: um ou mais cenários com testes embutidos e asserções personalizadas.
  4. Intenção de entrega: destinos de publicação solicitados e configurações opcionais de entrega.
{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Small Debian image with explicit smoke tests.",
  "base_image": "debian-trixie",
  "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"],
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {"port": 22, "disable_password_auth": true}
      }
    ],
    "security": {
      "hardening_level": "standard",
      "audit_logging": true
    }
  },
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"]
    }
  ],
  "publish_to": ["local"]
}

Use snake_case. Novas integrações não devem enviar formatos legados como baseImage, features no top level ou startupScripts.

Três verificações, três respostas diferentes

Validação de schema

A validação responde: “Os dados reconhecidos têm formato aceitável?” Não prova que pacotes existem ou que o comportamento funciona. Alguns campos desconhecidos são ignorados por compatibilidade; sucesso na validação ainda pode omitir um pedido importante.

Sempre compare a receita normalizada retornada com o chat e requisitos originais. Desktop, aplicativo, instalador, anexo ou teste faltando é defeito de receita mesmo se a validação disser valid.

Evidência de build

Um build bem-sucedido responde: “O pipeline produziu um artefato?” Não prova que todo feature pretendido entrou na imagem. Inspecione inventário de pacotes, proveniência de origem, avisos e evidências por estágio de build.

Verificação no guest

Testes no guest respondem perguntas estreitas de runtime: se a VM inicializou, um serviço está ativo, uma porta escuta, um arquivo tem conteúdo esperado ou um aplicativo foi lançado. Uma asserção aprovada sustenta apenas o comportamento que de fato observou.

Configurações de segurança são intenção

Os valores aceitos de hardening_level são minimal, standard e strict, mas esses rótulos não são perfis de conformidade portáveis. Geradores de alvo podem interpretá-los de forma diferente. Se você exige um benchmark, selecione o benchmark aplicável exato e retenha resultados por controle; não infira conformidade CIS a partir de strict.

Da mesma forma, disk_encryption, audit_logging, SELinux, fail2ban, Secure Boot, dm-verity e configurações de instalador exigem testes correspondentes de artefato e runtime.

Chat e propriedade da receita

Quando você valida ou edita uma receita autoria via chat, a conversa existente permanece parte do contexto de autoria. A validação deve refinar a receita atual, não substituí-la silenciosamente por um default genérico. Ainda assim, a receita normalizada é o checkpoint final antes do build.

Para cada requisito material:

  • encontre o campo normalizado correspondente;
  • confirme valor e escopo de alvo;
  • adicione uma asserção onde prova em runtime for possível; e
  • preserve trabalho só de implantação como aviso explícito em vez de fingir que ocorreu durante o build da imagem.

Checklist de revisão

  • A imagem base e a arquitetura estão corretas?
  • Todos os features de desktop e aplicativo solicitados estão presentes?
  • Fontes externas estão fixadas e licenciadas para o uso pretendido?
  • Segredos estão ausentes de campos e scripts salvos na receita?
  • O instalador está configurado e testado em disco descartável se solicitado?
  • Os cenários testam os critérios de aceitação reais?
  • Requisitos não suportados ou só na hora da implantação estão explicitados?

Veja Recipe Schema para a referência de campos e Seu primeiro build para o fluxo de build e download.

Seu primeiro buildGuias de build