업데이트로 돌아가기
New releaseAug 14, 2026

holos v0.6.2

YAML compose 파일을 사용하는 선언적 KVM/QEMU VM 오케스트레이션 도구입니다. cloud-init, SSH, PCI 패스스루, 이미지 검증을 통해 libvirt나 XML 없이 멀티 VM 스택을 관리합니다.

공유
holos

KVM을 위한 Docker compose. 하나의 YAML 파일에서 멀티 VM 스택을 정의합니다. libvirt도, XML도, 분산 제어 플레인이 필요 없습니다.

웹사이트 및 문서: https://zeroecco.github.io/holos/

기본 단위는 컨테이너가 아니라 VM입니다. 모든 워크로드 인스턴스는 자체 커널 경계, qcow2 오버레이, cloud-init 시드, 그리고 생성된 SSH 접근 권한을 갖습니다.

빠른 시작

Linux + /dev/kvm이 필요합니다. macOS 빌드는 validate, import, images, pull 같은 오프라인 명령을 실행할 수 있지만, up과 run은 KVM 호스트가 필요합니다.

compose 파일 없이 일회용 VM 하나:

holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>

curl로 사용할 수 있는 단일 서비스 스택입니다. holos.yaml로 저장하세요:

name: hello

services:
  web:
    image: ubuntu:noble
    ports:
      - "8080:80"
    cloud_init:
      packages:
        - nginx
      write_files:
        - path: /var/www/html/index.html
          content: "hello from holos\n"
      runcmd:
        - systemctl restart nginx

holos up
curl localhost:8080
holos down hello

실제 VM이 클라우드 이미지를 부팅하고, 패키지를 설치하고, 설정을 작성하고, 호스트 포트를 포워딩하는 것입니다.

일상적인 사용

프로젝트 디렉터리 안에서:

holos exec web       # open a guest shell
holos logs           # read project boot logs
holos stop web       # keep its disk
holos start web
holos up --dry-run   # preview configuration changes
holos help exec      # command syntax and options

서비스에 여러 레플리카가 있을 때는 web-0과 같은 인스턴스 이름을 사용하세요.

설치

미리 빌드된 바이너리는 모든 GitHub 릴리스에 첨부되어 있습니다:

TAG=v0.6.3
ASSET=holos_${TAG#v}_Linux_x86_64.tar.gz
BASE=https://github.com/zeroecco/holos/releases/download/$TAG
curl -LO $BASE/$ASSET
curl -LO $BASE/checksums.txt
grep " $ASSET$" checksums.txt | sha256sum -c -
gh attestation verify $ASSET --repo zeroecco/holos
sudo tar -xz -C /usr/local/bin -f $ASSET holos
holos version
holos doctor

릴리스 페이지에는 SHA-256 체크섬과 서명된 출처(provenance)를 위한 GitHub 아티팩트 증명(attestation)이 포함되어 있습니다. 프로덕션 호스트에 바이너리를 설치하기 전에 두 가지를 모두 검증하십시오.

또는 소스에서 빌드하십시오:

go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor

CLI

holos up [-f holos.yaml] [--dry-run] [--recreate] [--strict] [--locked] [--lockfile path] [--lock-timeout 5m|--no-wait]
                                     start all services
holos run [flags] <image> [-- cmd...] launch a one-off VM
holos down <project>                 stop and remove a project
holos ps [-f holos.yaml]             list running projects
holos start [-f holos.yaml] [svc]    start a stopped service or all services
holos stop [-f holos.yaml] [svc]     stop a service or all services
holos console <project> [<inst>]     attach serial console
holos exec <project> [<inst>] [-- cmd...]
                                     SSH into an instance
holos logs <project> [<svc|inst>]    show console logs
holos inspect [-f holos.yaml] [project|instance]
                                     inspect state as JSON
holos validate [-f holos.yaml] [--strict]
                                     validate compose file (--capacity/--network)
holos pull <image>                   pull a cloud image
holos verify <image>|--all           verify cached image checksums
holos images                         list available images
holos images lock -f holos.yaml [-o holos.images.lock]
                                     write project image lockfile
holos snapshots {create|list|rm|restore|export} ... manage root snapshots
holos volumes [-f holos.yaml] [--json]
                                     list named volumes
holos volumes rm <project> <volume>  remove a detached named volume
holos volumes export <project> <volume> <path>
                                     export a detached named volume
holos volumes snapshot <project> <volume> <snapshot>
                                     snapshot a detached named volume
holos volumes snapshots <project> <volume>
                                     list volume snapshots
holos volumes snapshot-rm <project> <volume> <snapshot>
                                     remove a volume snapshot
holos volumes snapshot-restore <project> <volume> <snapshot>
                                     restore a volume snapshot
holos volumes snapshot-export <project> <volume> <snapshot> <path>
                                     export a volume snapshot
holos volumes resize [--shrink] <project> <volume> <size>
                                     resize a detached named volume
holos devices [--gpu]                list PCI devices and IOMMU groups
holos completion <bash|zsh|fish>      print shell completion script
holos doctor [--json]                check host dependencies
holos install [-f holos.yaml] [--system] [--enable]
                                     install a systemd unit
holos uninstall [-f holos.yaml] [--system]
                                     remove the systemd unit
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
                                     convert virsh VMs into holos.yaml

문서

  • 웹사이트: 랜딩 페이지 및 렌더링된 문서.
  • CLI 가이드: 임시 VM, exec, systemd 설치, virsh 가져오기, 그리고 doctor.
  • Compose 파일: 서비스, 볼륨, 헬스체크, 네트워킹, PCI 패스스루, Dockerfile 프로비저닝, 그리고 기본값.
  • JSON 스키마: holos.yaml에 대한 에디터 자동 완성 및 유효성 검사.
  • 예제: README 스타일 설명이 포함된 실행 가능한 스택 및 템플릿 스택.
  • 누락된 기능: holos의 단일 호스트 KVM compose 목표에 부합하는 우선순위가 지정된 격차.
  • 개발: 빌드, 테스트, 호스트 요구 사항, 그리고 릴리스 프로세스.
  • 보안 정책: 지원 버전 및 비공개 신고.
  • 위협 모델 / 하드닝: 이미지 검증, 상태 권한, 잠금, 그리고 운영 지침.
  • 기여: 빌드, 테스트, 스타일, 그리고 PR 규칙.

예제

작은 nginx 예제부터 시작하세요:

holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx

examples 디렉터리에는 Dockerfile 프로비저닝, GPU 패스스루, 그리고 depends_on, 생성된 구성, 레플리카를 보여주는 멀티 서비스 스택도 포함되어 있습니다.

호스트 요구 사항

  • /dev/kvm이 있는 Linux
  • qemu-system-x86_64
  • qemu-img
  • cloud-localds, genisoimage, mkisofs, xorriso 중 하나
  • UEFI 또는 PCI 패스스루를 위한 OVMF / edk2-ovmf 펌웨어
  • holos exec 및 헬스체크를 위한 ssh

holos doctor를 실행하여 호스트를 점검하세요.

문제 해결

/dev/kvm을 열 때 권한 거부됨

id -nG와 ls -l /dev/kvm을 확인하세요. 장치가 kvm 그룹에 속한 호스트에서는 sudo usermod -aG kvm "$USER"로 사용자를 추가한 뒤 로그아웃하고 다시 접속하세요. 기존 셸은 이전 그룹 멤버십을 유지합니다. 새 세션에서 holos doctor를 다시 실행하세요.

첫 부팅 시 SSH 연결이 재설정됨

kex_exchange_identification: read: Connection reset by peer는 보통 cloud-init이 아직 호스트 키를 재생성하고 sshd를 재시작하는 중임을 의미합니다. holos exec는 기본적으로 최대 60초까지 대기하지만, 첫 부팅이 매우 느린 경우 한 번 더 재시도하거나 holos exec -w 5m <project>를 사용해야 할 수 있습니다.

콘솔에 Login incorrect가 표시됨

시리얼 콘솔이 cloud-init이 사용자를 생성하기 전에 자동 로그인을 시도할 수 있습니다. 콘솔 로그에서 cloud-init ... finished가 표시될 때까지 기다린 후 holos exec를 사용하세요. 클라우드 이미지는 일반적으로 콘솔 비밀번호와 함께 제공되지 않으며, holos는 비밀번호를 추가하지 않습니다.

macOS에서 up이 실패함

KVM은 Linux 커널 기능입니다. macOS 바이너리는 작성 및 오프라인 명령에 유용하지만, holos up과 holos run은 Linux KVM 호스트에서 실행해야 합니다.

비목표

holos는 Kubernetes가 아닙니다. 멀티 호스트 클러스터링, 라이브 마이그레이션, 서비스 메시, 오버레이 네트워크, 스케줄러, CRD, 컨트롤 플레인 쿼럼을 해결하려고 하지 않습니다.

목표는 Kubernetes의 운영 형태를 도입하지 않고도 단일 호스트 스택에서 KVM을 사용할 수 있게 만드는 것입니다.

라이선스

Apache License, Version 2.0에 따라 라이선스가 부여됩니다. 저작자 표시는 NOTICE를 참조하세요.

더 읽기

카테고리

Cloud Infrastructure SecurityGeneral Purpose UtilitiesScripting & AutomationSecurity VirtualizationDevSecOpsHardware Security