Skip to Content
Getting Started레시피 이해하기

레시피 이해하기

BuildRecipe는 OpenFactory가 이미지 파이프라인으로 보내는 정규화된 명세입니다. 채팅이 작성을 도울 수 있지만, 레시피, 소스 스냅샷, 생성 파일, 테스트 증거가 빌드를 정의합니다.

멘탈 모델

정규 레시피에는 주로 네 가지 계층이 있습니다:

  1. Identity and target: 이름, 설명, base image, 하드웨어 의도.
  2. Operating system: os 아래 feature, 패키지, 서비스, 사용자, 보안, desktop, installer, attachment, startup script.
  3. Verification: 내장 테스트와 custom assertion이 있는 하나 이상의 scenario.
  4. Delivery intent: 요청된 publication 대상과 선택적 delivery 설정.
{
  "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"]
}

snake_case를 사용하세요. 새 통합은 baseImage, 최상위 features, startupScripts 같은 legacy 형태를 보내지 마세요.

세 가지 검사, 세 가지 다른 답

스키마 검증

검증이 답하는 것은 “인식된 데이터가 허용 가능한 형태인가?”입니다. 패키지가 존재하거나 동작한다는 것을 증명하지 않습니다. 호환을 위해 알 수 없는 필드는 무시될 수 있어, 검증 성공 후에도 중요한 요청이 빠질 수 있습니다.

반환된 정규화 레시피를 원래 채팅과 요구사항과 항상 비교하세요. desktop, application, installer, attachment, test가 빠지면 검증이 valid라고 해도 레시피 결함입니다.

빌드 증거

성공한 빌드가 답하는 것은 “파이프라인이 artifact를 만들었는가?”입니다. 의도한 모든 feature가 이미지에 들어갔다는 것을 증명하지 않습니다. 패키지 inventory, 소스 provenance, 경고, 빌드 stage 증거를 검사하세요.

guest 검증

guest 테스트는 좁은 runtime 질문에 답합니다. VM이 부팅했는지, 서비스가 active인지, 포트가 listen하는지, 파일 내용이 예상과 같은지, application이 실행되었는지. 통과한 assertion은 실제로 관측한 동작만 뒷받침합니다.

보안 설정은 의도

허용되는 hardening_level 값은 minimal, standard, strict이지만, 이 레이블은 이식 가능한 compliance 프로필이 아닙니다. target generator마다 다르게 해석할 수 있습니다. benchmark가 필요하면 적용 가능한 benchmark를 정확히 선택하고 control별 결과를 보관하세요. strict에서 CIS 적합을 추론하지 마세요.

마찬가지로 disk_encryption, audit_logging, SELinux, fail2ban, Secure Boot, dm-verity, installer 설정에는 맞는 artifact 및 runtime 테스트가 필요합니다.

채팅과 레시피 소유

채팅으로 작성한 레시피를 검증하거나 편집할 때 기존 대화는 작성 컨텍스트의 일부로 남습니다. 검증은 현재 레시피를 다듬어야 하며, generic default로 조용히 바꾸면 안 됩니다. 그래도 정규화 레시피는 빌드 전 최종 checkpoint입니다.

각 중요 요구에 대해:

  • 해당 정규화 필드를 찾고;
  • 값과 대상 scope를 확인하고;
  • runtime 증명이 가능하면 assertion을 추가하고;
  • 배포 전용 작업은 이미지 빌드 중에 한 것처럼 가장하지 말고 명시적 경고로 남깁니다.

검토 체크리스트

  • base image와 architecture가 맞는가?
  • 요청한 desktop과 application feature가 모두 있는가?
  • 외부 소스가 pin되어 있고 의도 용도에 맞게 licensed되었는가?
  • 저장된 레시피 필드와 script에 secret이 없는가?
  • installer가 요청되었다면 일회용 디스크에서 구성되고 테스트되었는가?
  • scenario가 실제 acceptance criteria를 테스트하는가?
  • 지원되지 않거나 배포 시점 요구가 명시되었는가?

필드 reference는 Recipe Schema, 빌드 및 다운로드 workflow는 첫 빌드를 참고하세요.

첫 빌드빌드 가이드