Kubeadm MCP服务器
一个模型上下文协议(MCP)服务器,用于使用Calico网络在Ubuntu系统上使用kubeadm管理Kubernetes集群。
🚀 快速开始AI集成
想在5分钟内开始使用人工智能驱动的Kubernetes管理吗?
👉 请参阅《入门指南》→
非常适合 VS代码与GitHub Copilot 和 光标 需要AI协助进行集群管理的用户!
🎯 单线设置```bash
./start.sh
🎉 **新**:服务器现在提供 **两个HTTP REST API** 和 **MCP协议**!
**✅ 快速测试** (无需设置):```bash
curl http://localhost:3000/ # API discovery
curl http://localhost:3000/tools # Available tools
curl -X POST http://localhost:3000/health/check # Health check
VS代码/光标:添加到 settings.json:```json
{
"mcpServers": {
"kubeadm-mcp": {
"command": "node",
"args": ["-e", "require('child_process').spawn('python3', ['-m', 'src.stdio_main'], {stdio: 'inherit'})"],
"cwd": "/path/to/mcp-kubeadm"
}
}
}
**测试**:打开AI聊天并尝试: `Help me set up a Kubernetes cluster`
______________________________________________________________________
## 🌐 HTTP REST API
MCP服务器现在提供 **完整HTTP REST API** 与MCP协议一起实现最大可访问性:
### 📋 可用端点
端点 · 方法 · 描述
`/` · 获取 · API发现-显示所有终结点
`/health` · GET · 基本健康检查
`/tools` · GET · 列出所有具有模式的MCP工具
`/resources` · GET · 列出所有MCP资源
`/docs/search?q=query` · GET · 搜索文档
`/kubeadm/commands` · GET · 可用的kubeadm命令
`/tools/{tool_name}` · POST · 执行任何MCP工具
`/resources/{uri}` · GET · 获取MCP资源内容
`/health/check` · POST · 运行全面的健康检查
`/health/checklist` · 获取健康检查清单
`/cluster/validate` · POST · 验证群集运行状况
`/troubleshoot` · POST · 获取故障排除指南
### 🚀 快速示例```bash
# API Discovery
curl http://localhost:3000/
# List Available Tools
curl http://localhost:3000/tools
# Search Documentation
curl "http://localhost:3000/docs/search?q=calico&limit=5"
# Run Health Check
curl -X POST http://localhost:3000/health/check \
-H "Content-Type: application/json" \
-d '{"check_type": "basic", "include_ssh_tests": true}'
# Get Health Checklist
curl "http://localhost:3000/health/checklist?section=networking&format=commands"
# Validate Cluster
curl -X POST http://localhost:3000/cluster/validate \
-H "Content-Type: application/json" \
-d '{"auto_fix": false, "severity_threshold": "high"}'
# Troubleshoot Issues
curl -X POST http://localhost:3000/troubleshoot \
-H "Content-Type: application/json" \
-d '{"issue_type": "networking", "error_message": "pods pending"}'
# Execute MCP Tools Directly
curl -X POST http://localhost:3000/tools/search_docs \
-H "Content-Type: application/json" \
-d '{"query": "cluster init", "limit": 3}'
🔧 集成示例
Shell脚本:```bash
!/bin/bash
Check cluster health in CI/CD
HEALTH=$(curl -s -X POST http://localhost:3000/health/check)
echo "Cluster Health: $HEALTH"
**Python集成:**```python
import requests
# Run health check
response = requests.post('http://localhost:3000/health/check',
json={'check_type': 'full'})
health_data = response.json()
print(f"Health Status: {health_data['health_check']['total_categories']} checks")
监控/警报:```bash
Nagios/Zabbix health check
curl -f http://localhost:3000/health || exit 1
______________________________________________________________________
## 快速开始
### 先决条件
- Ubuntu 20.04+(推荐:Ubuntu 22.04 LTS)
- Docker已安装并正在运行
- Root或sudo访问权限
- 至少2个CPU内核,2GB RAM
### 1.Docker设置(推荐)```bash
# Build the MCP server
docker build -t kubeadm-mcp-server .
# Run the MCP server
docker run -it --rm \
--name kubeadm-mcp \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ~/.kube:/root/.kube \
--network host \
kubeadm-mcp-server
2.直接安装```bash
Install Python 3.8+ and pip
sudo apt update
sudo apt install -y python3 python3-pip python3-venv
Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
Install dependencies
pip3 install -r requirements.txt
Start the MCP server
python3 src/main.py start
Or use npm scripts (if you prefer)
npm run start
## Kubernetes集群设置检查表
### 第一阶段:系统准备
- \[ \] **更新Ubuntu系统**```bash
sudo apt update && sudo apt upgrade -y
- [ ] 安装所需的软件包```bash
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
- \[ \] **禁用交换(Kubernetes需要)**```bash
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
- [ ] 配置内核模块```bash
cat < /dev/null
sudo apt-get update
sudo apt-get install -y containerd.io
- \[ \] **为Kubernetes配置containerd**```bash
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl enable containerd
第三阶段:Kubernetes安装
- [ ] 添加Kubernetes APT存储库```bash
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
- \[ \] **安装Kubernetes组件**```bash
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
阶段4:初始化Kubernetes集群
- [ ] 使用自定义CIDR初始化集群```bash
sudo kubeadm init \
--pod-network-cidr=172.100.10.0/24 \
--service-cidr=10.96.0.0/12 \
--apiserver-advertise-address=$(hostname -I | awk '{print $1}')
- \[ \] **为普通用户配置kubectl**```bash
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
第5阶段:安装Calico CNI
- [ ] 下载Calico清单```bash
curl https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml -O
- \[ \] **为Calico配置自定义CIDR(172.100.10.0/24)**```bash
# Edit the calico.yaml file to match our CIDR
sed -i 's|# - name: CALICO_IPV4POOL_CIDR| - name: CALICO_IPV4POOL_CIDR|g' calico.yaml
sed -i 's|# value: "192.168.0.0/16"| value: "172.100.10.0/24"|g' calico.yaml
- [ ] 应用Calico网络```bash
kubectl apply -f calico.yaml
- \[ \] **验证Calico吊舱是否正在运行**```bash
kubectl get pods -n kube-system -l k8s-app=calico-node
kubectl get pods -n kube-system -l k8s-app=calico-kube-controllers
第6阶段:验证
- [ ] 检查集群状态```bash
kubectl get nodes -o wide
kubectl get pods -A
- \[ \] **验证网络配置**```bash
# Check if CIDR is correctly configured
kubectl cluster-info dump | grep -m 1 cluster-cidr
kubectl get ippool -o yaml
- [ ] 测试吊舱联网```bash
Deploy test pod
kubectl run test-pod --image=nginx --restart=Never
kubectl get pod test-pod -o wide
Verify pod gets IP from 172.100.10.0/24 range
kubectl exec test-pod -- ip addr show eth0
Cleanup
kubectl delete pod test-pod
### 第7阶段:可选-删除Taint(单节点)
- \[ \] **删除单节点群集的主污染**```bash
kubectl taint nodes --all node-role.kubernetes.io/control-plane-
网络配置详细信息
Calico与自定义CIDR(172.100.10.0/24)
- Pod网络CIDR:
172.100.10.0/24 - 服务网络CIDR:
10.96.0.0/12 - CNI插件:Calico v3.26.1
- 专利联盟:
172.100.10.0/24
验证命令```bash
Check IP pool configuration
kubectl get ippool default-ipv4-ippool -o yaml
Verify Calico status
sudo calicoctl node status
Check networking
kubectl get nodes -o wide
kubectl describe node $(hostname)
## 故障排除
### 常见问题
1. **Pod卡在待定状态**```bash
kubectl describe pod
kubectl logs -n kube-system -l k8s-app=calico-node
- 节点未就绪状态```bash
kubectl describe node $(hostname)
systemctl status kubelet
journalctl -xeu kubelet
1. **网络问题**```bash
# Check Calico status
kubectl get pods -n kube-system | grep calico
# Verify IP assignment
kubectl get pods -o wide
🏥 健康检查和监测
MCP服务器包括全面的健康检查功能:
快速健康检查:```bash
Basic cluster health
curl -X POST http://localhost:3000/health/check
Full health check with SSH tests
curl -X POST http://localhost:3000/health/check \
-d '{"check_type": "full", "include_ssh_tests": true}'
**健康检查类别:**
- ✅ **SSH连接** -测试对主节点/工作节点的访问权限
- ✅ **核心组件** -API服务器等、调度程序、控制器管理器
- ✅ **节点运行状况** -节点状态、资源、条件
- ✅ **网络** -Calico Pod、IP池、DNS解析
- ✅ **工作量** -Pod状态、部署、服务
- ✅ **安全** -RBAC、网络策略、PSP
- ✅ **演出** -资源使用情况、响应时间
**获取具体清单:**```bash
# Get connectivity checklist
curl "http://localhost:3000/health/checklist?section=connectivity"
# Get networking commands only
curl "http://localhost:3000/health/checklist?section=networking&format=commands"
使用自动修复进行验证:```bash
Validate and get recommendations
curl -X POST http://localhost:3000/cluster/validate \
-d '{"severity_threshold": "medium", "auto_fix": false}'
### 🔧 自动故障排除
**常见问题解决:**```bash
# Network troubleshooting
curl -X POST http://localhost:3000/troubleshoot \
-d '{"issue_type": "networking", "error_message": "CoreDNS pods pending"}'
# Node issues
curl -X POST http://localhost:3000/troubleshoot \
-d '{"issue_type": "node_not_ready", "error_message": "kubelet stopped posting"}'
# Join failures
curl -X POST http://localhost:3000/troubleshoot \
-d '{"issue_type": "join_failure", "error_message": "connection refused"}'
重置群集(如果需要)```bash
sudo kubeadm reset -f
sudo rm -rf /etc/kubernetes/
sudo rm -rf ~/.kube/
sudo rm -rf /var/lib/etcd/
## 测试覆盖
我们的MCP Kubeadm服务器经过全面测试 **100%通过率(56/56次测试)**:
### ✅ 单元测试(38/38通过)
- **数据库管理器**:文档存储、搜索、配置管理
- **文档获取器**:内容解析、命令提取、错误处理
- **MCP服务器**:工具调用、错误处理、服务器操作
- **KubeadmManager**:集群运营和管理
### ✅ 集成测试(12/12通过)
- **数据库+Fetcher集成**:端到端文档工作流
- **MCP服务器+数据库集成**:具有真实数据库操作的工具调用
- **MCP服务器+Kubeadm集成**:完成群集管理工作流
- **完整的工作流集成**:完整用户场景和错误恢复
### ✅ 性能测试(6/6通过)
- **数据库性能**:329个文档/秒插入,589次搜索/秒
- **MCP服务器性能**:平均响应时间2ms,699个呼叫/秒并发
- **内存效率**:每份文档0.004MB,未检测到内存泄漏
### 运行测试```bash
# Run all tests (56 total)
pytest tests/ -v
# Run specific test categories
pytest tests/test_mcp_server.py -v # Unit tests (38)
pytest tests/test_integration.py -v # Integration tests (12)
pytest tests/test_performance.py -v # Performance tests (6)
# Run with coverage
pytest tests/ --cov=src --cov-report=html
性能基准
- 搜索响应时间:平均29ms(目标:\<100ms)✅ 快3.4倍
- 工具调用响应:平均2ms(目标:\<500ms)✅ 速度提高250倍
- 并发处理:699次呼叫/秒✅ 70倍目标性能
- 内存使用:每份文件0.004MB✅ 极其有效
看 测试报告.md 进行详细的性能分析。
🛠️ MCP服务器功能
🎯 核心能力
集群管理:
- ✅ 交互式集群设置 有指导的步骤
- ✅ 健康监测 进行全面检查
- ✅ 故障排除帮助 进行根本原因分析
- ✅ 配置验证 最佳实践
- ✅ 网络故障排除 (加州特定)
文档与学习:
- ✅ 21+策划文档 来自kubernetes.io
- ✅ 语义搜索 在所有文档中
- ✅ 命令帮助 以现实世界为例
- ✅ 最佳实践 适用于Ubuntu+Calico部署
集成与自动化:
- ✅ HTTP REST API 用于CI/CD集成
- ✅ MCP协议 用于AI编辑器集成
- ✅ 健康检查端点 用于监控
- ✅ API故障排除 用于自动分辨率
🔧 可用工具
| 工具 | 目的 | 示例使用 |
|---|---|---|
search_docs |
搜索kubeadm文档 | 查找CNI设置说明 |
get_command_help |
获取特定命令的帮助 | 学习 kubeadm init 选项 |
generate_cluster_config |
创建集群配置 | 生成自定义YAML配置 |
validate_cluster |
检查集群健康状况 | 验证节点和Pod |
troubleshoot_issue |
获取故障排除指南 | 修复“Pod待定”问题 |
run_health_check |
全面的健康检查 | 完整的集群验证 |
get_health_checklist |
健康检查命令 | 复制粘贴就绪命令 |
validate_cluster_health |
健康标准验证 | 自动健康评分 |
🎯 使用示例
AI编辑器集成 (光标/VCode):```
💬 "Help me troubleshoot why my CoreDNS pods are stuck"
💬 "Generate a cluster config for production with Calico"
💬 "Run a full health check on my cluster"
**HTTP API集成**:```bash
# CI/CD Pipeline Health Check
curl -X POST http://localhost:3000/health/check | jq '.health_check.total_categories'
# Automated Troubleshooting
curl -X POST http://localhost:3000/troubleshoot \
-d '{"issue_type": "pods_pending"}' | jq '.guidance'
可用资源:
- 📚
kubeadm://docs/-完整文档数据库 - 🏥
kubeadm://health/checklist-健康检查程序 - 📊
kubeadm://health/results-最新健康检查结果 - 📖
kubeadm://lessons/-业务经验教训
🚀 非常适合
- DevOps工程师:自动化集群运行状况监测
- 平台团队:标准化故障排除程序
- 人工智能开发:上下文感知集群管理
- CI/CD管道:自动验证和健康检查
- 学习:使用最佳实践指导Kubernetes设置
📚 额外资源
- 课程_学习.md -操作指南和故障排除方法
- 健康检查.md -全面的健康检查程序和验证
- GETTING_STARTED.md -详细的设置指南和分步说明
支持和文档
- Kubernetes文档: https://kubernetes.io/docs/
- Calico文件: https://docs.projectcalico.org/
- Ubuntu Kubernetes指南: https://ubuntu.com/kubernetes
- MCP协议: https://modelcontextprotocol.org/
🎯 版本中的新功能
✨ 新增主要功能:
- 🌐 完整HTTP REST API -用于集成的直接端点访问
- 🏥 全面健康检查 -7类集群验证
- 🔧 自动故障排除 -上下文感知问题解决
- 📊 健康监测 -实时集群状态和验证
- 🚀 增强的性能 -响应时间快250倍
- 📖 经验教训整合 -内置操作指南
- 🎯 双协议支持 -HTTP API和MCP协议
🔥 非常适合:
- 生产集群 -可靠的健康监测和故障排除
- CI/CD集成 -自动健康检查和验证
- 人工智能驱动的DevOps -上下文感知集群管理
- 学习与发展 -使用最佳实践指导设置
- 企业使用 -全面的文档和支持
