holos v0.6.2

KVM 向けの Docker Compose。1 つの 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 ホストが必要です。

使い捨ての VM を 1 台、compose ファイルなしで:

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 チェックサムと、署名済みの来歴を示す GitHub アーティファクト証明が含まれています。本番ホストにバイナリをインストールする前に、両方を検証してください。

またはソースからビルドします:

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 Schema: 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 を開く際に permission denied が発生する

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 を参照してください。