k8s-pilot

Kubernetes 集群的中央驾驶舱 ✈️✈️

k8s_pilot 是一款轻量级的集中式控制平面服务，可同时管理多个 Kubernetes 集群。
借助强大的工具和直观的 API，你可以在一个驾驶舱中观察和控制所有集群。

---

🚀 概述

• 🔄 支持多集群上下文切换
• 🔧 支持对大多数常见 Kubernetes 资源执行 CRUD 操作
• 🔒 提供只读模式，安全地检查集群
• ⚙️ 由 MCP 提供支持，可用于 Claude AI 等
• 🌐 支持 Streamable 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 新功能

• Streamable 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

Streamable 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 运行

你可以直接使用已发布的 Docker 镜像运行 k8s-pilot，无需在本地安装 uv。 请务必挂载 ~/.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	安全清理命名空间的流程

在 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> 替换为你克隆仓库的实际目录。

场景

使用 nginx:latest 镜像在 pypy 命名空间中创建 Deployment，并创建一个与之连接的 Service。

核心功能

多集群管理

• 无缝连接多个 Kubernetes 集群
• 执行上下文感知操作
• 通过 MCP 提示词轻松切换集群

资源控制

• 查看、创建、更新和删除：
  • Deployments、Services、Pods
  • ConfigMaps、Secrets、Ingresses
  • StatefulSets、DaemonSets
  • Roles、ClusterRoles
  • PersistentVolumes 和 Claims

命名空间操作

• 创建/删除命名空间
• 列出命名空间中的所有资源
• 管理标签和资源配额

节点管理

• 查看节点详情和状态
• 封锁/解除封锁节点，为节点添加标签/污点
• 列出每个节点上的 Pod

许可证

本项目采用 MIT 许可证。详情请参阅 许可证 文件。