목표 계약 + 현재 구현 구분 · 2026-10-29상세 계약 읽기

제어는 VM 밖에서.
레이어는 공유 저장소에서.

클라우드 목표는 외부 Palimpsest 제어가 레이어를 고르고, Manila 관리 CephFS의 읽기 전용 바이트를 워크로드 VM에 연결하는 구조입니다. Hub DB는 메타데이터를, VM은 최소 마운트와 실행만 맡습니다.

목표와 현재 구현을 구분하세요Manila 기반 실행 경로는 아직 구현·라이브 검증되지 않았습니다. 현재 HTTPS 게스트 경로와 Cinder 프로토타입은 별도입니다. 로컬 CLI·Lima/VZ·KVM은 계속 제공하는 선택 모드입니다.

전체 구조의 읽는 순서

주 경로는 클라우드 목표입니다. DB의 기록과 공유 저장소의 실제 바이트를 분리해 읽으세요.

주 경로 · 클라우드 목표

외부 제어 → 공유 RO → 워크로드

클라이언트 · Hub APIVM 밖에서 선택·명세·권한·lease·Nova 수명주기 결정
Hub DB · 메타데이터digest·size·레이어 순서·runtime·job/provenance의 권위
Manila 관리 CephFS실제 바이트. worker는 새 digest RW 발행, 소비자는 RO
워크로드 VM최소 helper → RO lower + 개인 upper/work → 실행

위 네 칸은 책임을 읽는 순서이며 DB를 통과해 바이트가 흐른다는 뜻은 아닙니다. 아래 전체 구조도와 시퀀스에 실제 관계와 RW/RO 경계를 표시했습니다.

기준: 소유자 목표 계약 · 현재 구현 차이

별도 선택 모드 · 내 컴퓨터에서 실행

클라우드 목표와 혼동하지 않는 기존 로컬 경로

로컬 CLI · 웹내 컴퓨터에서 요청과 실행 관리
로컬 저장소이미지·레이어·로컬 상태 기록
Lima/VZ 또는 KVM호스트·이미지에 맞는 로컬 런타임 선택
로컬 게스트 VM일반 cloud-image 또는 별도 OCI-root 실행

Hub 없이도 로컬 기능은 사용할 수 있습니다. 이 선택성은 클라우드 목표의 Hub DB·외부 제어 경계를 없앤다는 뜻이 아닙니다.

현재 소스: CLI · 플랫폼 선택 · 런타임 분기

핵심은 바뀌지 않는 재료와
VM별 변경분의 분리

VM을 통째로 복사하는 대신, 어떤 파일이 원본이고 어떤 파일이 실행 중 바뀌는지 구분합니다.

이미지와 레이어

이미지는 게스트의 출발점입니다. 레이어는 별도로 보관하는 파일 집합으로, 일반 VM 경로에서는 SquashFS 형식의 읽기 전용 계층입니다. 여러 VM에서 같은 입력을 참조할 수 있습니다.

저장소의 sha256:… digest는 바이트의 식별자입니다. 이름이나 태그만 신뢰하는 대신 실제 내용이 예상한 digest와 맞는지 확인합니다.

읽기 전용 + 쓰기 가능

OverlayFS는 읽기 전용 lower 레이어와 별도의 쓰기 가능한 upper를 합쳐 하나의 파일 트리처럼 보여줍니다. 변경은 upper에 남고 원본 lower는 그대로 유지됩니다.

로컬 상태에는 아티팩트뿐 아니라 VM 실행 기록, 프로젝트, 빌드 기록도 있습니다. 콘텐츠 바이트와 실행 상태는 같은 것이 아닙니다.

읽을 때 주의: 같은 “레이어”라도 어디에 합쳐지는지는 실행 방식에 따라 다릅니다. 일반 cloud-image에서는 애플리케이션 경로이고, OCI-root에서는 게스트의 실제 루트 파일시스템입니다.

선택적 로컬 모드의
두 가지 VM 실행 방식

아래는 현재 로컬 구현입니다. 클라우드 Manila 목표의 구현 증거가 아닙니다. 탭을 바꿔 게스트 파일시스템의 차이를 보세요.

운영체제와 앱 계층을 나란히

Ubuntu 같은 부팅 가능한 cloud image로 VM을 시작합니다. 실행별 쓰기 가능한 디스크가 OS 변경을 담고, 별도로 연결한 SquashFS 레이어는 게스트 안에서 합쳐집니다.

게스트의 /와 레이어가 합쳐지는 /opt/layers/merged는 서로 다른 경로입니다. libvirt 경로는 cloud-init으로 레이어 활성화와 준비 신호를 설정합니다. Lima는 VM 시작 후 레이어를 복사·마운트합니다.

근거: kvm.pycloudinit.pylima.pyVM workflow
게스트 내부
쓰기 계층 · upper / work애플리케이션 변경분
읽기 전용 SquashFS 레이어하나 이상의 lower
/opt/layers/merged레이어와 변경분을 합친 뷰
/ · cloud image별도 OS 루트와 실행별 디스크

클라우드 목표:
VM 밖에서 제어하기

외부 클라이언트·Hub API·오케스트레이터가 레이어 선택, mount 명세, 접근권한·lease와 Nova 수명주기를 맡습니다. 아래 그림은 목표 계약이며 아직 Manila 기반 구현·실기 검증은 아닙니다.

아래 두 그림은 기존 Archify JSON에서 정식 생성·SVG export한 동일 산출물입니다. 작은 화면에서는 그림 안만 좌우로 이동할 수 있습니다.

클라이언트와 Hub API는 VM 밖에 있고 Hub DB는 digest, size, 레이어 순서, runtime, job과 provenance를 관리합니다. 별도 빌드 worker만 Manila 관리 CephFS에 staging과 새 digest를 RW 발행합니다. 소비자는 공유를 RO로 읽고 최소 helper로 SquashFS RO lower를 조립합니다. 워크로드는 VM 전용 upper와 work를 사용합니다.
대화형 전체 구조도 열기 · 원본 JSON. 생성 도구 UI와 생성 HTML의 언어 표시는 영어 기본값이며, 설명 내용은 한국어입니다.
  • 메타데이터와 바이트: Hub DB가 digest·size·레이어 순서·runtime·job/provenance의 권위입니다. 실제 SquashFS 바이트는 Manila가 노출·관리하는 CephFS에 둡니다. 클라우드의 권위를 VM별 로컬 catalog나 다운로드 저장소로 옮기지 않습니다.
  • 쓰기 권한: 빌드 worker의 RW는 staging과 새 digest 발행을 위한 것입니다. 이미 발행된 digest의 바이트는 불변입니다. 소비자는 공유와 SquashFS lower를 모두 RO로 사용하고 copy-up은 VM 전용 upper·work에만 남깁니다.
  • 외부 결정·게스트 적용: 외부 제어가 명세와 권한을 확정하고 최소 guest mount helper가 게스트 커널에서 마운트합니다. helper는 Palimpsest CLI나 제어면이 아니며, 워크로드 VM 안에서 이미지 획득·빌드·변환·오케스트레이션을 하지 않습니다.
  • 아직 확정하지 않은 부분: 운영으로 확정할 Manila 공유 경로·RO 접근권한. export 프로토콜·자격증명 방식은 미선정입니다. tenant/workload 격리, lease 해제·접근권한 회수와 실제 RO 강제는 전환 전 구현 및 라이브 검증이 필요합니다.

예시 · 파일 하나가 실행 VM에 보이기까지

외부 클라이언트가 빌드를 요청하면 별도 worker가 레시피를 실행하고 /opt/hello-vm/message.txt를 포함한 새 SquashFS를 검증·발행합니다. Hub DB에는 digest·size·순서·출처를 기록합니다. 외부 제어는 실행 요청에 맞는 공유 RO 접근과 mount 명세를 확정합니다. 게스트 helper가 해당 lower들을 RO로 조립하면 워크로드가 병합 뷰에서 파일을 읽습니다. 실행 중 파일 변경은 VM 전용 upper로 갑니다. 이는 의미를 설명하는 예시이며 새 API 이름이나 실행 성공을 주장하지 않습니다.

목표 시퀀스 · 빌드 발행 → 공유 RO → 실행

아래로 갈수록 시간이 흐릅니다. Hub DB는 메타데이터, CephFS는 바이트입니다. 끝의 helper와 워크로드는 같은 VM 안에 있습니다.

외부 요청, Hub DB의 job 기록, 별도 worker의 빌드 검증과 CephFS 새 digest RW 발행, 메타데이터 확정 순서입니다. 이후 외부에서 레이어와 lease, RO 접근권한, Nova와 mount 명세를 정합니다. 게스트는 지정 공유를 RO로 읽고 SquashFS RO lower와 개인 upper/work를 조립하여 워크로드를 실행합니다.
대화형 시퀀스 열기 · 원본 JSON. 그림과 SVG export는 런타임 증거가 아닙니다.
현재 구현 / 역사적 프로토타입: 별도 작업트리의 미게시 구현(base 977c4f2) 중 hub/src/palimpsest_hub/services/instance_bootstrap.py의 게스트 bootstrap은 레이어를 HTTPS로 내려받은 뒤 RO loop mount합니다. 이미 게스트 Palimpsest CLI는 없지만 Manila 공유 기반 실행 경로는 아닙니다. 이 체크아웃의 Nova capture/Cinder ext4 RW → 별도 봉인·RO 연결 프로토타입도 별개입니다. 과거 소스와 벤치마크는 보존하며 새 목표의 구현·성능 검증으로 보지 않습니다. 목표와 현재 구현 차이에서 근거와 남은 전환을 확인하세요.

기준: 2026-10-29 소유자 목표 계약 · 역사적 별도 경로: Nova capture · 외부 계층 마운트. Torch·TensorFlow·CUDA 파일을 담을 수 있다는 설명은 GPU·드라이버·프레임워크 동작 증거가 아닙니다.

현재 소스의 별도 빌드 경로

아래는 기존 로컬·Hub 구현의 소스 안내입니다. 위 클라우드 목표의 Manila 전환이나 실제 RO 권한 검증을 뜻하지 않습니다.

로컬 레이어 빌드

Palimpsestfile에서 시작하는 대표 경로

  1. 레시피와 입력 확인base 이미지·부모 레이어·RUN을 해석합니다.
  2. 일회성 빌드 게스트 실행선택된 로컬 백엔드에서 레시피를 실행합니다.
  3. SquashFS 결과 등록결과와 digest, 빌드 기록을 로컬 저장소에 남깁니다.

근거: build.py · Hello VM 예제

Hub 작업과 아티팩트

서버에 별도로 구성된 경우의 경로

  1. API가 요청과 권한 확인업로드는 시작·추가·완료로 나뉘며 완료 시 digest를 검증합니다.
  2. 빌드 요청을 SQL에 기록API의 접수와 실제 게스트 빌드는 서로 다른 단계입니다.
  3. 독립 worker가 처리작업을 claim하고 결과를 저장합니다. export worker는 필요 시 Glance와 통신합니다.

근거: 업로드 API · 빌드 API · 빌드 작업

다른 입력 경로: Dockerfile 빌드는 BuildKit을 사용해 OCI 출력을 만드는 별도 경로입니다. --executor nova 역시 명시적으로 선택하는 클라우드 빌드 경로이며 위 로컬 게스트 빌드와 동일하지 않습니다. Hub는 Docker/OCI /v2 레지스트리가 아닌 별도의 /v1 API입니다.

소스는 여기서부터

각 경로를 열어 실제 구현을 확인할 수 있습니다. 링크는 이 HTML과 같은 체크아웃의 파일을 가리킵니다.

pyproject.toml패키지와 palimpsest CLI 진입점
src/.../cli.py사용자 명령의 파싱과 분기
src/.../oci_layout.pydigest 기반 로컬 콘텐츠 저장소
src/.../platforms.py호스트·아키텍처별 백엔드 선택
src/.../cloudinit.pylibvirt cloud-init 초기화 · libvirt·Lima·Nova 공통 빌드 캡처 worker
guest/stage1/init.cOCI-root 게스트의 초기화와 워크로드 감독
hub/src/.../main.pyFastAPI와 /v1 라우터 구성
hub/src/.../services/Hub 저장·빌드·이미지 export 처리
src/.../webui/로컬 대시보드 화면
deploy/kolla/.../palimpsest/Kolla-Ansible 배포 역할의 소스