AI导哈

Kubernetes集群管理服务器

一个基于kubeadm的Kubernetes集群管理服务器，提供HTTP REST API和MCP协议支持，适用于Ubuntu系统上的Calico网络环境。

  • by Hawaiideveloper
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 hawaiideveloper/mcp-kubeadm-server

使用说明

Kubeadm MCP服务器

一个模型上下文协议（MCP）服务器，用于使用Calico网络在Ubuntu系统上使用kubeadm管理Kubernetes集群。

🚀 快速开始AI集成

想在5分钟内开始使用人工智能驱动的Kubernetes管理吗？

👉 请参阅《入门指南》→

非常适合 VS代码与GitHub Copilot 和 光标 需要AI协助进行集群管理的用户！

🎯 单线设置

./start.sh

🎉 新：服务器现在提供 两个HTTP REST API 和 MCP协议!

✅ 快速测试 （无需设置）：

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:

{
  "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 获取故障排除指南

🚀 快速示例

# 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脚本：

#!/bin/bash
# Check cluster health in CI/CD
HEALTH=$(curl -s -X POST http://localhost:3000/health/check)
echo "Cluster Health: $HEALTH"

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")

监控/警报：

# 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设置（推荐）

# 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.直接安装

# 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系统

    sudo apt update && sudo apt upgrade -y

  • [ ] 安装所需的软件包

    sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

  • [ ] 禁用交换（Kubernetes需要）

    sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

  • [ ] 配置内核模块

    cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

  • [ ] 配置sysctl参数

    cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

阶段2：容器运行时（containerd）

  • [ ] 安装容器d

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y containerd.io

  • [ ] 为Kubernetes配置containerd

    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存储库

    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组件

    sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

阶段4：初始化Kubernetes集群

  • [ ] 使用自定义CIDR初始化集群

    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

    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清单

    curl https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml -O

  • [ ] 为Calico配置自定义CIDR（172.100.10.0/24）

    # 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网络

    kubectl apply -f calico.yaml

  • [ ] 验证Calico吊舱是否正在运行

    kubectl get pods -n kube-system -l k8s-app=calico-node
kubectl get pods -n kube-system -l k8s-app=calico-kube-controllers

第6阶段：验证

  • [ ] 检查集群状态

    kubectl get nodes -o wide
kubectl get pods -A

  • [ ] 验证网络配置

    # Check if CIDR is correctly configured
kubectl cluster-info dump | grep -m 1 cluster-cidr
kubectl get ippool -o yaml

  • [ ] 测试吊舱联网

    # 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（单节点）

  • [ ] 删除单节点群集的主污染
    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

验证命令

# 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卡在待定状态

    kubectl describe pod <pod-name>
kubectl logs -n kube-system -l k8s-app=calico-node

  2. 节点未就绪状态

    kubectl describe node $(hostname)
systemctl status kubelet
journalctl -xeu kubelet

  3. 网络问题

    # Check Calico status
kubectl get pods -n kube-system | grep calico

# Verify IP assignment
kubectl get pods -o wide

🏥 健康检查和监测

MCP服务器包括全面的健康检查功能：

快速健康检查：

# 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
  • ✅ 演出 -资源使用情况、响应时间

获取具体清单：

# 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"

使用自动修复进行验证：

# Validate and get recommendations
curl -X POST http://localhost:3000/cluster/validate \
  -d '{"severity_threshold": "medium", "auto_fix": false}'

🔧 自动故障排除

常见问题解决：

# 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"}'

重置群集（如果需要）

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，未检测到内存泄漏

运行测试

# 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集成:

# 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设置

📚 额外资源

支持和文档

  • 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 -上下文感知集群管理
  • 学习与发展 -使用最佳实践指导设置
  • 企业使用 -全面的文档和支持

相关 MCP