KVM MCP Server

KVM MCP サーバー

シンプルで直感的なインターフェースを通じて KVM 仮想マシンを管理する、強力な JSON-RPC サーバーです。このサーバーを使うと、標準化されたプロトコルを通じて KVM 仮想マシンを一元的に制御・監視できます。

このプロジェクトの目的

KVM 仮想マシンの管理には通常、virsh、virt-install、qemu-system などの複数のコマンドラインツールを使う必要があります。このプロジェクトは、以下を実現することを目的としています。

1. VM 管理の簡素化：すべての VM 操作に対して、統一された単一のインターフェースを提供します
2. リモート制御の実現：JSON-RPC を通じて VM をリモート管理できるようにします
3. VM 操作の自動化：VM 管理タスクのスクリプト化と自動化を容易にします
4. VM 設定の標準化：インフラストラクチャ全体で一貫した VM セットアップを実現します
5. パフォーマンスの最適化：効率的なリソース管理とキャッシュ戦略を実装します

特長

• VM ライフサイクル管理：

  • カスタマイズ可能なパラメーターで新しい VM を作成
  • VM の起動／停止／再起動
  • 利用可能なすべての VM とその状態を一覧表示
  • 状態の自動追跡と復旧

• ネットワーク管理：

  • ブリッジを使用して VM のネットワークを設定
  • brforvms ブリッジに対応
  • ネットワークインターフェースを自動設定
  • IP アドレスの追跡と管理

• ストレージ管理：

  • VM ディスクの保存先を設定可能
  • 各種ディスク形式（qcow2）に対応
  • ディスクサイズを設定可能
  • ディスクの自動クリーンアップと管理

• ディスプレイ管理：

  • グラフィカルアクセス用の VNC に対応
  • VNC ポートを自動割り当て
  • VM ディスプレイの検出と接続用ツール
  • ディスプレイ状態の追跡と復旧

• インストール対応：

  • ISO イメージからのネットワークインストール
  • CDROM からのローカルインストール
  • 各種 OS バリアントに対応
  • インストール設定の自動化

• パフォーマンスの最適化：

  • libvirt の接続プーリングにより、接続のオーバーヘッドを削減
  • VM 情報をキャッシュして応答性を向上
  • 非同期処理により並行性を向上
  • 診断とトラブルシューティングのための高度なロギング
  • リソースを適切に解放するためのグレースフルシャットダウン処理
  • 接続の自動復旧と検証
  • API 操作のレート制限
  • パフォーマンスメトリクスの収集

パフォーマンス上の利点

接続プーリング

• レイテンシの低減：libvirt 接続を繰り返し開閉するオーバーヘッドを解消します
• リソース効率の向上：再利用可能な接続プールを維持し、システムリソースの使用量を削減します
• 自動復旧：切断された接続を自動的に検出して置き換えます
• プールサイズの設定：ワークロードに応じて接続数を調整できます

キャッシュ

• 応答時間の短縮：一般的な操作で libvirt への問い合わせを繰り返す回数を減らします
• TTL の設定：ニーズに応じてキャッシュの有効期限を設定できます
• 選択的なバイパス：最新データが必要な操作では、キャッシュをバイパスできます
• 自動無効化：VM の状態が変わると、キャッシュは自動的に無効化されます

非同期処理

• 並行性の向上：複数のリクエストを同時に処理します
• リソース利用の向上：システムリソースを効率的に使用します
• ノンブロッキング操作：時間のかかる操作によってサーバーがブロックされません
• グレースフルシャットダウン：シャットダウン時にリソースを適切に解放します

監視と診断

• 構造化ログ：分析しやすいログ形式
• パフォーマンスメトリクス：操作時間とリソース使用量を追跡
• エラー追跡：トラブルシューティングのための詳細なエラーログ
• リソース監視：接続プールの使用状況とキャッシュの有効性を追跡

設定

サーバーは、デフォルト値とパスを保存するために JSON 設定ファイル（config.json）を使用します。これにより、サーバーの移植性が高まり、カスタマイズしやすくなります。設定には以下が含まれます。

{
    "vm": {
        "disk_path": "/vm",                    // Base directory for VM disk storage
        "default_iso": "/iso/ubuntu-24.04.2-live-server-amd64.iso",  // Default installation media for Ubuntu-based VMs
        "default_master_image": "/iso/fedora-coreos-41-qemu.x86_64.qcow2",  // Default base image for Fedora CoreOS VMs
        "default_name": "newvmname",           // Default VM name
        "default_memory": 2048,                // Default memory allocation in MB
        "default_vcpus": 2,                    // Default number of virtual CPUs
        "default_disk_size": 20,               // Default disk size in GB
        "default_os_variant": "generic",       // Default OS variant for virt-install
        "default_network": "brforvms",         // Default network bridge for VM networking
        "ignition": {                          // Fedora CoreOS specific configuration
            "default_hostname": "coreos",      // Default hostname for CoreOS VMs
            "default_user": "core",            // Default user for CoreOS VMs
            "default_ssh_key": "~/.ssh/id_rsa.pub",  // Default SSH public key path
            "default_timezone": "UTC",         // Default timezone
            "default_locale": "en_US.UTF-8",   // Default system locale
            "default_password_hash": null      // Optional: Default password hash for user
        }
    }
}

これらの値は、環境の要件に合わせて変更できます。以下の形式で環境変数による上書きが可能です。

• disk_path に対する VM_DISK_PATH
• default_iso に対する VM_DEFAULT_ISO
• default_master_image に対する VM_DEFAULT_MASTER_IMAGE
• default_name に対する VM_DEFAULT_NAME
• default_memory に対する VM_DEFAULT_MEMORY
• default_vcpus に対する VM_DEFAULT_VCPUS
• default_disk_size に対する VM_DEFAULT_DISK_SIZE
• default_os_variant に対する VM_DEFAULT_OS_VARIANT
• default_network に対する VM_DEFAULT_NETWORK
• ignition.default_hostname に対する VM_IGNITION_DEFAULT_HOSTNAME
• ignition.default_user に対する VM_IGNITION_DEFAULT_USER
• ignition.default_ssh_key に対する VM_IGNITION_DEFAULT_SSH_KEY
• ignition.default_timezone に対する VM_IGNITION_DEFAULT_TIMEZONE
• ignition.default_locale に対する VM_IGNITION_DEFAULT_LOCALE
• ignition.default_password_hash に対する VM_IGNITION_DEFAULT_PASSWORD_HASH

パフォーマンスの調整

接続プールの設定

connection_pool = LibvirtConnectionPool(
    max_connections=5,     # Maximum number of connections in the pool
    timeout=30,            # Timeout for getting a connection (seconds)
    uri='qemu:///system'   # Libvirt connection URI
)

キャッシュの設定

vm_info_cache = VMInfoCache(
    max_size=50,           # Maximum number of VMs to cache
    ttl=60                 # Time-to-live for cache entries (seconds)
)

ロギングの設定

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        RotatingFileHandler(
            'kvm_mcp.log',
            maxBytes=10485760,  # 10MB
            backupCount=5
        ),
        logging.StreamHandler()
    ]
)

はじめに

前提条件

• Python 3.6 以降
• ホストシステムに KVM と libvirt がインストールされていること
• ネットワークブリッジが設定されていること（デフォルト：brforvms）
• VM ストレージディレクトリが作成されていること（デフォルト：/vm/）
• VM のワークロードに十分なシステムリソースがあること

インストール

1. このリポジトリをクローンします。

   git clone https://github.com/yourusername/kvm-mcp.git
   cd kvm-mcp
   

2. 仮想環境を作成して有効化します。

   python3 -m venv .venv
   source .venv/bin/activate
   

3. 依存関係をインストールします。

   pip install -r requirements.txt
   

4. サーバーを設定します。

   • config.json を環境に合わせて編集します
   • 必要なディレクトリがすべて存在することを確認します
   • ネットワークブリッジの設定を確認します
   • 必要に応じてパフォーマンス設定を調整します

使用方法

1. サーバーを起動します。

   python3 kvm_mcp_server.py
   

2. JSON-RPC を使用してコマンドを送信します。サンプルスクリプトが用意されています。

   • create_vm.sh：デフォルト設定を使用して新しい VM を作成します
   • get_vnc_ports.sh：実行中の VM の VNC ポートを確認します

コマンドの例

新しい VM の作成

./create_vm.sh

これにより、config.json のデフォルト設定を使用して新しい VM が作成されます。リクエストで値を指定することで、これらのデフォルト値を任意に上書きできます。

VNC ポートの確認

./get_vnc_ports.sh

これにより、実行中のすべての VM とその VNC ポートが表示され、ディスプレイに簡単に接続できます。

キャッシュをバイパスして VM を一覧表示

echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_vms", "arguments": {"no_cache": true}}, "id": 1}' | python3 kvm_mcp_server.py

監視とトラブルシューティング

ログファイル

• kvm_mcp.log：現在のログファイル
• kvm_mcp.log.1：前回のログファイル（ローテーション済み）
• ログには、処理時間、接続プールの状態、キャッシュヒット／ミスの情報が含まれます

パフォーマンス指標

• 接続プールの使用状況
• キャッシュヒット／ミス率
• 操作の処理時間
• リソース使用状況

よくある問題と解決策

1. 接続プールの枯渇

   • 症状：応答が遅い、または接続エラーが発生する
   • 解決策：接続プール設定の max_connections を増やします

2. キャッシュ無効化の問題

   • 症状：VM 情報が古い
   • 解決策：no_cache パラメーターを使用するか、キャッシュ TTL を短くします

3. リソースのクリーンアップ

   • 症状：リソースリークまたは接続の問題
   • 解決策：SIGTERM または SIGINT を使用して適切にシャットダウンします

プロジェクト構成

• kvm_mcp_server.py：メインのサーバー実装
• config.json：設定ファイル
• requirements.txt：Python の依存関係
• ルートディレクトリにあるサンプルスクリプト
• tests/ ディレクトリにあるテストスイート

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。