k8s-pilot

Kubernetes クラスター群を統括する中央パイロット ✈️✈️

k8s_pilot は、複数の Kubernetes クラスターを一度に管理するための、軽量で一元化されたコントロールプレーンサーバーです。
強力なツールと直感的な API により、1 つのコックピットからすべてのクラスターを監視・操作できます。

---

🚀 概要

• 🔄 複数クラスターのコンテキスト切り替えに対応
• 🔧 一般的な Kubernetes リソースのほとんどで作成・読み取り・更新・削除（CRUD）操作が可能
• 🔒 クラスターを安全に調査できる読み取り専用モード
• ⚙️ Claude AI などに対応する MCP を基盤として使用
• 🌐 リモートアクセス用のストリーミング可能な HTTP トランスポートに対応
• 🤖 操作をガイドする MCP プロンプト
• 📝 書き込み操作のコンテキスト対応ログ

---

🧰 前提条件

• Python 3.13 以上
• uv パッケージマネージャー
• Kubernetes クラスターへのアクセス（~/.kube/config またはクラスター内設定）

# Install uv (if not installed)

# For MacOS
brew install uv

# For Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

インストール

# Clone the repository
git clone https://github.com/bourbonkk/k8s-pilot.git
cd k8s-pilot

# Launch with uv + MCP
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py

🆕 v2.0 の新機能

• ストリーミング可能な HTTP トランスポート：HTTP 経由でリモートクラスターを管理できます（stdio に加えて対応）
• MCP プロンプト：一般的な K8s 操作向けの組み込みプロンプトテンプレート
• コンテキスト対応ログ：書き込み操作の進行状況を MCP コンテキスト経由で報告するようになりました
• バグ修正：Ingress および RBAC リソース用の API クライアントが不足していた問題を修正しました
• セキュリティ：ノード変更操作に読み取り専用チェックを追加しました
• Dockerfile：uv パッケージマネージャーを使用するように更新し、ビルドを高速化しました

使い方

通常モード（フルアクセス）

# Start with full read/write access
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py

読み取り専用モード（安全な調査）

# Start in readonly mode - only read operations allowed
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py --readonly

ストリーミング可能な HTTP モード（リモートアクセス）

# Start with Streamable HTTP transport for remote access
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py --transport streamable-http

コマンドラインオプション

# Show help
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py --help

Docker で実行する

ローカルに uv をインストールせずに、公開済みの Docker イメージを使って k8s-pilot を直接実行できます。
コンテナからクラスターにアクセスできるように、~/.kube/config をマウントしてください。

docker run -i --rm \
  -v ~/.kube/config:/root/.kube/config \
  ghcr.io/bourbonkk/k8s-pilot:latest

読み取り専用モード

--readonly フラグを指定すると、Kubernetes クラスターへの書き込み操作をすべて防止する安全モードが有効になります。次のような用途に最適です。

• クラスターの調査：誤った変更を加えるリスクがありません
• 監査シナリオ：変更はせずに情報を確認できます
• 学習環境：安全に操作を試せます
• 本番環境の監視：変更のリスクがありません

保護される操作（読み取り専用モードではブロック）

• pod_create、pod_update、pod_delete
• deployment_create、deployment_update、deployment_delete
• service_create、service_update、service_delete
• configmap_create、configmap_update、configmap_delete
• secret_create、secret_update、secret_delete
• namespace_create、namespace_delete
• その他すべての作成・更新・削除操作

許可される操作（常に利用可能）

• pod_list、pod_detail、pod_logs
• deployment_list、deployment_get
• service_list、service_get
• configmap_list、configmap_get
• secret_list、secret_get
• namespace_list、namespace_get
• その他すべての一覧取得・取得操作

MCP プロンプト

k8s-pilot には、一般的な操作向けのプロンプトテンプレートが組み込まれています。

プロンプト	説明
troubleshoot_pod	Pod のトラブルシューティングを段階的に進めるガイド
deployment_guide	アプリケーションのデプロイをガイドするワークフロー
cluster_health_check	クラスターの包括的なヘルスチェック
namespace_cleanup	安全な Namespace クリーンアップ手順

Claude Desktop での使い方

この設定を使って、Claude 内から k8s_pilot MCP サーバーを実行します。

{
  "mcpServers": {
    "k8s_pilot": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-cloned-repo>/k8s-pilot",
        "run",
        "--with",
        "mcp[cli]>=1.28.0,<2",
        "python",
        "k8s_pilot.py"
      ]
    }
  }
}

読み取り専用モードでは、次の設定を使用します。

{
  "mcpServers": {
    "k8s_pilot_readonly": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-cloned-repo>/k8s-pilot",
        "run",
        "--with",
        "mcp[cli]>=1.28.0,<2",
        "python",
        "k8s_pilot.py",
        "--readonly"
      ]
    }
  }
}

Docker では、次の設定を使用します（YOUR_USERNAME を実際の Mac ユーザー名に置き換えてください）。

{
  "mcpServers": {
    "k8s_pilot_docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/YOUR_USERNAME/.kube/config:/root/.kube/config",
        "ghcr.io/bourbonkk/k8s-pilot:latest"
      ]
    }
  }
}

<path-to-cloned-repo> を、リポジトリをクローンした実際のディレクトリに置き換えてください。

シナリオ

pypy Namespace に nginx:latest イメージを使用する Deployment を作成し、それに接続する Service も作成します。

主な機能

マルチクラスタ管理

• 複数の Kubernetes クラスターをシームレスに操作できます
• コンテキストを認識した操作を実行できます
• MCP プロンプトを使用して、クラスターを簡単に切り替えられます

リソース管理

• 以下のリソースを表示、作成、更新、削除できます：
  • Deployments、Services、Pods
  • ConfigMaps、Secrets、Ingresses
  • StatefulSets、DaemonSets
  • Roles、ClusterRoles
  • PersistentVolumes と Claims

名前空間の操作

• 名前空間を作成、削除できます
• 名前空間内のすべてのリソースを一覧表示できます
• ラベルとリソースクォータを管理できます

ノード管理

• ノードの詳細と状態を表示できます
• ノードを Cordon／Uncordon し、ラベルや Taint を設定できます
• ノードごとに Pod を一覧表示できます

ライセンス

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