Docker Compose 形式による KVM: はじめに

複数の仮想マシン（VM）のスタックを、libvirt や XML、分散制御プレーンを使用せず、単一の YAML ファイルで定義します。基本単位はコンテナではなく、すべてのワークロードインスタンスに対して独自のカーネル境界、独自の qcow2 オーバーレイ、そして独自の cloud-init シードを提供する「仮想マシン」が採用されています。

クイックスタート

holos.yaml

name: my-stack

services:
  db:
    image: ubuntu:noble
    vm:
      vcpu: 2
      memory_mb: 1024
    cloud_init:
      packages:
        - postgresql
      runcmd:
        - systemctl enable postgresql
        - systemctl start postgresql

  web:
    image: ubuntu:noble
    replicas: 2
    depends_on:
      - db
    ports:
      - "8080:80"
    volumes:
      - ./www:/srv/www:ro
    cloud_init:
      packages:
        - nginx
      write_files:
        - path: /etc/nginx/sites-enabled/default
          content: |
            server {
                listen 80;
                location / { proxy_pass http://db:5432; }
            }
      runcmd:
        - systemctl restart nginx

起動するだけで済みます。これにより、ホスト上の同じ場所で、お互いの名前を使って通信し合う 2 つの Nginx VM と 1 つの PostgreSQL VM が立ち上がります。

コマンドラインインターフェース（CLI）

holos up [-f holos.yaml]

holos down [-f holos.yaml]

holos ps

holos start [-f holos.yaml] [svc]

holos stop [-f holos.yaml] [svc]

holos console [-f holos.yaml] <inst>

holos exec [-f holos.yaml] <inst> [cmd...]

holos logs [-f holos.yaml] <svc>

holos validate [-f holos.yaml]

holos pull <image>

holos images

holos devices [--gpu]

holos install [-f holos.yaml] [--system] [--enable]

holos uninstall [-f holos.yaml] [--system]

holos install

holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]

Compose ファイル構成

holos.yaml

• services: 各サービスは、独自のイメージ、リソース、および cloud-init 設定を持つ VM です。
• depends_on: サービスは依存関係の順序に従って起動します。
• ports:

  "ホスト:ゲスト"

  シNTAX を使用し、レプリカ間では自動増番されます。
• volumes: バインドマウントには

  ./source:/target:ro

  、トップレベルの名前付きボリュームには

  name:/target

  を使用します。
• replicas: サービスを N インスタンス実行します。
• cloud_init: パッケージ、write_files、runcmd — 標準的な cloud-init の機能です。
• stop_grace_period: ACPI シャットダウン後に SIGTERM/SIGKILL を発行するまでの待ち時間（例：

  "30s"

  、

  "2m"

  ）；デフォルトは 30s です。
• healthcheck: 依存項を制御するためのテスト、interval、retries、start_period、timeout です。
• トップレベルの volumes ブロック:

  holos down

  を実行しても持続する名前付きデータボリュームを宣言します。

例：

name: demo
services:
  db:
    image: ubuntu:noble
    stop_grace_period: 60s # ハード停止前に DB バッファをフラッシュする
    volumes:
      - pgdata:/var/lib/postgresql

volumes:
  pgdata:
    size: 20G

データボリューム

トップレベルのボリュームは、

state_dir/volumes/<プロジェクト>/<名前>.qcow2

holos down

name: demo
services:
  db:
    image: ubuntu:noble
    volumes:
      - pgdata:/var/lib/postgresql

volumes:
  pgdata:
    size: 20G

ボリュームは安定したシリアル番号

vol-<名前>

/dev/disk/by-id/virtio-vol-pgdata

mkfs.ext4

/etc/fstab

ヘルスチェックと depends_on

ヘルスチェックを備えたサービスは、チェックが通るまで依存項の起動をブロックします。プローブは SSH（

holos exec

services:
  db:
    image: postgres-cloud.qcow2
    healthcheck:
      test: ["pg_isready", "-U", "postgres"]
      interval: 2s
      retries: 30
      start_period: 10s
      timeout: 3s
  api:
    image: api.qcow2
    depends_on: [db] # db が健全になるまで待機する

test

sh -c

HOLOS_HEALTH_BYPASS=1

holos exec

各

holos up

state_dir/ssh/<プロジェクト>/

• holos exec web-0

  : インタラクティブなシェル

• holos exec db-0 -- pg_isready

  : ワンショットコマンド

-u <ユーザー>

cloud_init.user

再起動時の耐性

ホストが再起動した後にもプロジェクトが復元されるよう、systemd ユニットを生成します：

• holos install --enable

  : ユーザー固有であり、sudo を必要としない

• holos install --system --enable

  : ログイン前のシステム全体レベル

• holos install --dry-run

  : ユニットを出力し終了する

ユーザーユニットは

~/.config/systemd/user/holos-<プロジェクト>.service

/etc/systemd/system/

holos uninstall

ネットワーキング

各サービスは名前で他のすべてのサービスに到達できます。その裏側では：

• 各 VM は 2 つの NIC を持っています：ユーザモード（ホストポートの転送用）とソケットマルチキャスト（VM 間での L2 通信用）。
• 静的 IP アドレスは、内部

  10.10.0.0/24

  セグメントで自動的に割り当てられます。

• /etc/hosts

  は cloud-init を介して填充され、

  db

  、

  web-0

  、

  web-1

  などすべてが解決されます。
• libvirt の使用はありません。ブリッジの設定も不要です。VM 間のネットワーキングに root アクセスは必要ありません。

GPU パススルー

VFIO を介して物理的な GPU（または任意の PCI デバイス）を直接 VM に渡します：

services:
  ml:
    image: ubuntu:noble
    vm:
      vcpu: 8
      memory_mb: 16384
    devices:
      - pci: "01:00.0" # GPU
      - pci: "01:00.1" # GPU オーディオ
    ports:
      - "8888:8888"

holos が担当する処理

• デバイスが存在する場合、UEFI 起動が自動的に有効になります（OVMF ファームウェア）。
• NVIDIA 互換性のためにマシンの

  kernel-irqchip=on

  が設定されます。
• 各 VM に独自の EFI 変数ストアを持つよう、インスタンスタイプごとの OVMF_VARS コピーを行います。
• カスタム VBIOS ROM 用のオプションの rom_file

ユーザーが担当する処理（ホストセットアップ）

• BIOS およびカーネルで IOMMU を有効にする（

  intel_iommu=on

  または

  amd_iommu=on

  ）。
• GPU を vfio-pci ドライバーにバインドする。
• PCI アドレスと IOMMU グループを探すために

  holos devices --gpu

  を実行する。

イメージ

独自の構築ではなく、事前に用意されたクラウドイメージを使用します：

services:
  web:
    image: alpine # 自動プルおよびキャッシュされる
  api:
    image: ubuntu:noble # 特定のタグ
  db:
    image: debian # デフォルトは debian:12

利用可能なもの：

alpine

arch

debian

ubuntu

fedora

holos images

Dockerfile

VM のプロビジョニングに Dockerfile を使用します。RUN、COPY、ENV、WORKDIR 指令は、cloud-init が実行するシェルスクリプトに変換されます：

FROM ubuntu:noble

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y nodejs npm
COPY server.js /opt/app/
WORKDIR /opt/app
RUN npm init -y && npm install express

イメージが省略された場合、ベースイメージは Dockerfile の

FROM

cloud_init.runcmd

• サポートされているもの：FROM, RUN, COPY, ENV, WORKDIR
• サポートされていない指令（CMD, ENTRYPOINT, EXPOSE など）は静かにスキップされます。
• COPY のソースは Dockerfile のディレクトリ相対で解決され、ディレクトリではなくファイルである必要があります — ディレクトリマウントにはボリュームを使用してください。

追加の QEMU アーギュメント

extra_args

services:
  gpu:
    image: ubuntu:noble
    vm:
      vcpu: 4
      memory_mb: 8192
      extra_args:
        - "-device"
        - "virtio-gpu-pci"
        - "-display"
        - "egl-headless"

アーギュメントは、holos が管理するすべてのフラグの後に付加されます。検証はありません — あなたの責任です。

リソースデフォルト

libvirt からインポート

libvirt 下ですでに実行中の VM はありますか？

holos import

holos import web-prod db-prod                # `virsh dumpxml` を介して
holos import --all -o holos.yaml             # 定義されたすべてのドメイン
holos import --xml ./web.xml                 # オフラインで、virsh が不要
holos import --connect qemu:///system api    # デフォルトではない libvirt URI

マッピングは、holos に直接相当するフィールドをカバーしています：

<vcpu>

vm.vcpu

<memory>

<currentMemory>

vm.memory_mb

<os><type machine="pc-q35-…">

vm.machine

<cpu mode="host-passthrough">

vm.cpu_model: host

<os><loader>

vm.uefi: true

<disk type="file">

image:

image_format:

<hostdev type="pci">

devices: [{pci: …}]

holos がきれいに変換できないもの — 追加のディスク、ブリッジ NIC、USB パススルー、カスタムエミュレーターなど — は stderr で警告として報告され、

holos up

-o

holos import vm > holos.yaml

インストール

プリビルトの実行バイナリ（Linux および macOS、amd64 および arm64）は、すべての GitHub リリースに添付されています：

TAG=v0.1.0
curl -L https://github.com/zeroecco/holos/releases/download/$TAG/holos_${TAG#v}_Linux_x86_64.tar.gz \
  | sudo tar -xz -C /usr/local/bin holos
holos version

または、ソースから構築することもできます（下記参照）。

• Linux だけが実行目標です —

  holos up

  は

  /dev/kvm

  および

  qemu-system-x86_64

  を必要とします。
• macOS のビルドは存在しており、オフラインサブコマンド（

  validate

  、

  import

  、

  images

  ）がラップトップ上の Compose ファイル作成のために機能します。

ビルド

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

リリースの作成

GoReleaser がすべての

v*

.github/workflows/release.yml

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

このワークフローでは 4 つのターゲットをクロスコンパイルし、LICENSE/NOTICE/README.md と一緒にパッケージ化し、SHA-256 チェックサムを計算し、コミットログからリリースノートドラフトを作成し、GitHub リリースを公開します。

ローカルで公開せずに練習するには：

goreleaser release --snapshot --clean --skip=publish
ls dist/

ゲストイメージの構築（mkosi が必要）

ホスト要件

• /dev/kvm

• qemu-system-x86_64

• qemu-img

• cloud-localds、genisoimage、mkisofs のうちの一つ、または xorriso
• mkosi （ベースイメージの構築用のみ）

目的外（Non-Goals）

これは Kubernetes ではありません。解決しようとするものではありません：

• マルチホストクラスタリング
• ライブマイグレーション
• サービスメッシュ
• オーバーレイネットワーク
• スケジューラ、CRD、または制御プレーンのクォーラム

目標は、Kubernetes の運用形状を輸入することなく、シングルホストスタックに対して KVM を機能させることです。

ライセンス

Apache License Version 2.0 に基づいています。帰属については NOTICE を参照してください。