AI导哈

Kubernetes诊断工具

AI驱动的Kubernetes集群诊断工具，提供智能调试建议和故障分析

  • by ongjin
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ongjin/k8s-doctor-mcp

使用说明

🏥 K8s医生MCP

基于人工智能的Kubernetes集群诊断和智能调试建议

英语 | 韩语

演示

为什么选择K8s医生？

当Kubernetes问题出现时，开发人员通常会经历一个无休止的循环：

  • kubectl get pods
  • kubectl logs
  • kubectl describe
  • 疯狂搜索StackOverflow。..

K8s医生改变了游戏。 它不仅仅是一个kubectl包装器，它是一个AI驱动的诊断工具，可以：

  • 🔍 分析根本原因 -超越简单的状态检查
  • 🧠 检测错误模式 -识别常见问题（连接被拒绝、OOM、DNS故障）
  • 💡 提供可操作的解决方案 -为您提供精确的kubectl命令来解决问题
  • 📊 退出代码分析 -解释出口1371431的实际含义
  • 🎯 日志模式匹配 -在数千条记录行中查找信号
  • 🏥 健康评分 -对你的吊舱/集群健康状况进行0-100的评分

特性

工具 说明
diagnose-pod 全面的吊舱诊断 -分析状态、事件、资源，并提供健康评分
debug-crashloop CrashLoopBackOff专家 -解码退出代码，分析日志，找到根本原因
analyze-logs 智能日志分析 -检测错误模式，建议解决常见问题
check-resources 资源使用 -验证CPU/内存限制，警告OOM风险
full-diagnosis 群集健康检查 -扫描所有节点和Pod以查找问题
check-events 事件分析 -过滤和分析警告事件
list-namespaces 命名空间列表 -所有名称空间的快速概述
list-pods Pod列表 -显示带有状态指示器的有问题的Pod

安装

通过npm（推荐）

npm install -g @zerry_jin/k8s-doctor-mcp

来源

git clone https://github.com/ongjin/k8s-doctor-mcp.git
cd k8s-doctor-mcp
npm install && npm run build

使用Claude代码进行设置

# After npm global install
claude mcp add --scope project k8s-doctor -- k8s-doctor-mcp

# Or from source build
claude mcp add --scope project k8s-doctor -- node /path/to/k8s-doctor-mcp/dist/index.js

快速设置（自动批准工具）

厌倦了每次手动批准工具执行？按照以下步骤启用自动审批。

🖥️ 适用于Claude桌面应用程序用户

  1. 重新启动Claude桌面应用程序。
  2. 用以下方式问你的第一个问题 k8s-doctor.
  3. 当权限对话框出现时，选中该框 “始终允许来自此服务器的请求” 然后单击 允许. （未来的请求将自动执行，无需提示。）

⌨️ 适用于Claude Code（CLI）用户

如果您正在使用 claude 终端命令，通过交互式菜单管理权限：

  1. 跑 claude 在你的终端。
  2. 类型 /permissions 在提示中，按Enter键。
  3. 选择 全局权限 （或项目权限）> 允许使用的工具.
  4. 进入 mcp__k8s-doctor__* 允许所有工具，或单独添加特定工具。

💡 小贴士：对于大多数用例，允许 diagnose-pod, debug-crashloop，以及 analyze-logs 足够了。这三个场景涵盖了90%的调试场景。

推荐配置：

# Balanced approach - allow main diagnostic tools
claude config add allowedTools \
  "mcp__k8s-doctor__diagnose-pod" \
  "mcp__k8s-doctor__debug-crashloop" \
  "mcp__k8s-doctor__analyze-logs" \
  "mcp__k8s-doctor__full-diagnosis"

先决条件

  • kubectl 的 已配置并工作(kubectl cluster-info 应该成功）
  • kubeconfig 文件位于默认位置(~/.kube/config)或 KUBECONFIG 有人看过
  • Node.js 18岁或以上
  • 访问Kubernetes集群（本地，如minikube/cind，或远程）

使用示例

示例1：诊断碰撞循环吊舱

You: "My pod 'api-server' in namespace 'production' is CrashLooping. What's wrong?"

Claude (using k8s-doctor):
🔍 CrashLoopBackOff 진단

Exit Code: 137 (OOM Killed)
Root Cause: Container was killed due to Out Of Memory

Solution:
Increase memory limit:
```yaml
resources:
  limits:
    memory: "512Mi"  # Increase from current value

相关日志：

  • 第1234行：错误：JavaScript堆内存不足
  • 第1256行：严重错误：已达到堆限制

### Example 2: Analyze Application Logs

你：“分析pod‘后端worker’的日志，告诉我什么是失败的”

Claude（使用分析日志）： 📝 日志分析

检测到的错误模式：

🔴 数据库连接错误（15次） 可能的原因：

  • 数据库服务未就绪
  • 连接字符串错误
  • 认证失败

解决：

  • 检查DB吊舱状态
  • 验证环境变量（ConfigMap/Resecret）
  • 检查服务端点：kubectl获取端点

🟡 超时（8次） 可能原因：响应时间太慢或网络延迟 解决方案：增加超时值或优化服务性能


### Example 3: Cluster Health Check

您：“检查整体群集运行状况”

克劳德（使用完整诊断）： 🏥 集群健康诊断

总分：72/100💛

节点：3/3就绪✅ Pod：45/52跑步

  • 碰撞循环：2🔥
  • 待定：5⏳

关键问题： 🔴 Pod“支付服务”崩溃循环（出口1） 🔴 Pod“worker-3”OOM被杀

建议：

  • 立即修复2个CrashLoop吊舱
  • 检查挂起的Pod是否缺少资源

## How It Works

1. **Connects to your cluster** via kubeconfig (same as kubectl)
2. **Gathers comprehensive data** - pod status, events, logs, resource usage
3. **Applies pattern matching** - recognizes common error patterns from production experience
4. **Analyzes root causes** - doesn't just show status, explains WHY it's failing
5. **Provides solutions** - gives exact commands and YAML to fix issues

## Error Patterns Detected

K8s Doctor recognizes these common patterns:

- 🔴 **Connection Refused** - Service not ready, wrong port, network policy
- 🔴 **Database Connection Errors** - DB auth, wrong connection strings
- 🔴 **Out of Memory** - OOM kills, memory leaks, undersized limits
- 🟠 **File Not Found** - ConfigMap not mounted, wrong paths
- 🟠 **Permission Denied** - SecurityContext issues, fsGroup problems
- 🟠 **DNS Resolution Failed** - CoreDNS issues, wrong service names
- 🟡 **Port Already in Use** - Multiple processes on same port
- 🟡 **Timeout** - Slow responses, network delays
- 🟡 **SSL/TLS Errors** - Expired certs, missing CA bundles

## Architecture

k8s医生mcp/ ├── src/ │ ├── index.ts#MCP服务器及其所有工具 │ ├── types.ts#TypeScript类型定义 │ ├── 诊断学/ │ │ ├── pod-dignostics.ts#pod健康分析 │ │ └── cluster-health.ts#集群范围的诊断 │ ├── 分析器/ │ │ └── log-analyzer.ts#智能日志模式匹配 │ └── utils/ │ ├── k8s-client.ts#Kubernetes API客户端 │ └── formatters.ts#输出格式化工具 └── package.json


## Security Considerations

- K8s Doctor uses **read-only** Kubernetes API calls (list, get, describe)
- Requires same permissions as `kubectl get/describe/logs`
- Never modifies cluster state
- kubeconfig credentials stay local
- No data sent to external servers

## Troubleshooting

### "kubeconfig not found"
```bash
# Verify kubectl works
kubectl cluster-info

# Check kubeconfig location
echo $KUBECONFIG

# Test with explicit path
export KUBECONFIG=~/.kube/config

“权限被拒绝”

# Check your cluster permissions
kubectl auth can-i get pods --all-namespaces

# You need at least read access to:
# - pods, events, namespaces, nodes

“连接拒绝群集”

# Verify cluster connectivity
kubectl get nodes

# For local clusters (minikube/kind)
minikube status
kind get clusters

发展

# Clone and install
git clone https://github.com/ongjin/k8s-doctor-mcp.git
cd k8s-doctor-mcp
npm install

# Development mode
npm run dev

# Build
npm run build

# Test with Claude Code
npm run build
claude mcp add --scope project k8s-doctor-dev -- node $(pwd)/dist/index.js

贡献

欢迎投稿！特别是：

  • 🆕 新的错误模式检测
  • 🌍 国际化（更多语言）
  • 📊 度量集成（普罗米修斯等）
  • 🧪 测试覆盖率
  • 📖 文档改进

路线图

  • []度量服务器集成（实时CPU/内存使用率）
  • []网络策略诊断
  • []存储/PVC故障排除
  • []Helm图表分析
  • []多集群支持
  • []交互式调试模式
  • []导出报告（PDF、HTML）

许可证

MIT© 泽里

致谢

内置：

星迹

如果此工具为您节省了调试时间，请⭐ 明星回购！

作者

泽里

  • github： @泽里
  • 为厌倦kubectl地狱的DevOps社区创建😅

制作❤️ 对于淹没在日志中的Kubernetes用户

相关 MCP