Proxbase

Proxbase

ラボ、デモ、CI 向けの実際の Proxmox VE クラスターを、Linux マシン上で約 3 分で構築できます。

Proxbase は各ノードを QEMU/KVM 仮想マシンとして起動し、自動インストーラーを使って公式 Proxmox VE ISO からインストールした後、Proxmox API を通じてノードをクラスターに参加させます。ZFS または Ceph ストレージ、内部ネットワーク、Terraform や Ansible ですぐに使える API トークンを備えています。root 権限も、Docker も、手動操作も不要です。

$ proxbase create lab --nodes 3
…
created in 2m56s
Cluster lab: ready, quorate: yes, switch: running
NODE  VM       CLUSTER  IP           WEB UI                   SSH
pve1  running  online   10.10.10.11  https://127.0.0.1:18001  127.0.0.1:18101
pve2  running  online   10.10.10.12  https://127.0.0.1:18002  127.0.0.1:18102
pve3  running  online   10.10.10.13  https://127.0.0.1:18003  127.0.0.1:18103

機能

• 実際のノード： 各ノードは、標準の ISO からインストールされた独自のカーネルを持つ VM です。ネストされた仮想化により、クラスター内でゲストを実行できます。
• ストレージ： ノードごとの ZFS プール、または HEALTH_OK になるまで待機するハイパーコンバージド Ceph（RBD と CephFS）に対応しています。
• root 権限不要のネットワーク： 複数の内部ネットワークと役割（corosync link0/link1、Ceph public/cluster、移行）、VLAN 対応および L2 専用のブリッジ、ジャンボフレームに対応しています。
• ライフサイクル： 起動／停止、ノードの追加と削除（Ceph の退避処理を含む）、クラスター全体の整合性のあるスナップショット、実行中のクラスターを数秒で再開できるライブスナップショット、中断後に再開可能な作成に対応しています。
• 障害注入： 電源喪失、ノードのハング、ケーブルの切断、ネットワーク分断、遅延、パケット損失を発生させ、HA、フェンシング、Ceph の復旧をテストできます。
• 自動化に対応： API トークンと CA のエクスポート、シェル向けの proxbase env、JSON と bpg/proxmox Terraform プロバイダー、スクリプト向けの -o json と --progress json、および準備済みクラスターをテンプレートとしてキャッシュできる CI 用の GitHub Action を利用できます。
• AI エージェント向け： proxbase mcp は MCP サーバーです。エージェントはツールを通じて、クラスターの作成、API の呼び出し、ノード上でのコマンド実行、診断、スナップショットへのリセット、障害の注入を行えます。スキルがワークフローを案内します。Claude Code では、/plugin install proxbase --marketplace virtbase/proxbase を実行してください。
• 高速： --golden を使うと、キャッシュ済みのベースイメージからノードを複製できます。ノードごとに固有の ID を持つ 3 ノードクラスターを 1 分未満で（Ceph の場合は 1.5 分で）構築できます。
• 宣言的： JSON スキーマを備えた 1 つの YAML ファイルで設定でき、各フラグでフィールドを上書きできます。
• Docker Compose： proxbase up を実行すると、正常なシャットダウンとヘルスチェックに対応したフォアグラウンドでクラスターが動作します。

クイックスタート

必要条件：/dev/kvm がある amd64 の Linux、QEMU 7.2 以降（qemu-system-x86_64、qemu-img）、およびノードあたり約 4 GiB の RAM。ノード内でゲストを実行するには、ネストされた仮想化が必要です。

go install github.com/virtbase/proxbase/cmd/proxbase@latest   # or see docs/install.md
proxbase doctor                                               # checks KVM, QEMU, memory, ports
proxbase create lab --nodes 3

次に、https://127.0.0.1:18001 を開きます（ユーザーは root、パスワードは proxbase env lab で確認できます）。または、次のコマンドを実行します。

proxbase ssh lab pve2 -- pvecm status
eval "$(proxbase env lab)"            # PROXMOX_VE_ENDPOINT, PROXMOX_VE_API_TOKEN, …
proxbase destroy lab --yes            # removes everything

使い方

proxbase create ceph --nodes 3 --storage ceph       # hyperconverged Ceph
proxbase create fast --nodes 3 --golden             # clone from a cached base image
proxbase create -f examples/networks.yaml           # separate networks and VLANs
proxbase node add lab --count 1                     # grow the cluster
proxbase node remove lab pve2                       # shrink it again
proxbase stop lab && proxbase snapshot save lab base
proxbase snapshot restore lab base && proxbase start lab
proxbase env lab --format terraform                 # provider block for bpg/proxmox
proxbase fault partition lab pve3                   # isolate a node, then: fault clear
proxbase status lab --check                         # exit code for CI and health checks
claude mcp add proxbase -- proxbase mcp             # let an AI agent drive proxbase
proxbase upgrade                                    # install the latest release

GitHub Actions では、次のようにします。

- id: pve
  uses: virtbase/proxbase@v0          # KVM, QEMU, cache, create; outputs endpoint, api-token, env-file
- env: {PVE_ENV: "${{ steps.pve.outputs.env-file }}"}
  run: . "$PVE_ENV" && go test ./... -tags integration
- if: always()
  run: proxbase destroy ci --yes

クラスター設定ファイルは次のようになります（すべてにデフォルト値があります）。

apiVersion: proxbase.virtbase.com/v1alpha1
kind: Cluster
name: lab
nodes:
  count: 3
  defaults: {cpus: 4, memory: 4G, dataDisks: [{size: 32G}]}
networks:
  - {name: cluster, cidr: 10.10.10.0/24, roles: [corosync]}
storage:
  zfs: [{name: tank, raid: single}]

ドキュメント

トピック
はじめに	最初のクラスター、Web UI、認証情報
インストール	パッケージ、Homebrew、コンテナーイメージ、リリースの検証
設定	すべてのフィールド、デフォルト値、上限
ネットワーク · ストレージ · ライフサイクル	仕組みと想定される動作
障害注入 · ゴールデンイメージ	意図的にクラスターに障害を起こす方法、高速なクラスター作成
CI と自動化 · MCP サーバー	GitHub Action、JSON 進捗状況、AI エージェント
Docker · CLI リファレンス · トラブルシューティング
アーキテクチャ	パッケージ、作成フロー、ディスク上の状態
例	一般的な構成ですぐに使えるクラスター設定ファイル

ステータスと制限事項

Proxbase はまだ開発初期のため、v1.0 より前にファイル形式が変更される可能性があります。Debian 13 上の Proxmox VE 9.2（QEMU 10.0、AMD）でテストされています。クラスターには KVM を備えた Linux ホストが必要です。macOS ビルドは実験的なもので、Docker Desktop には /dev/kvm がありません。ノードには、127.0.0.1 の転送ポートを通じてホストからアクセスできます。ホストから到達可能なブリッジネットワークは設計済みですが、まだ実装されていません。Proxbase はラボを構築します。生成されたパスワードとキーは、状態ディレクトリに暗号化されずに保存されます。

貢献

Issue とプルリクエストを歓迎します。CONTRIBUTING.md および行動規範をご覧ください。セキュリティ上の問題は、SECURITY.md の説明に従って非公開で報告してください。

ライセンス

Apache-2.0