kube-medic

核心用法

kube-medic 是一款面向Kubernetes SRE/运维工程师的AI辅助诊断工具，封装了kubectl常用排查命令，提供五个核心子命令：

• `sweep`：全集群健康扫描，快速定位CrashLoopBackOff、ImagePullBackOff、NotReady节点等关键问题
• `pod <name>`：深度Pod尸检，关联容器状态、日志、事件、镜像版本差异，输出标准化诊断报告
• `deploy <name>`：Deployment状态分析，检测 rollout 阻塞、版本历史对比、ReplicaSet健康度
• `resources`：CPU/内存压力检测，识别节点过载风险与无资源限制的Pod
• `events [namespace]``：近期事件聚合，支持自定义时间窗口，快速追溯变更

显著优点

1. 数据关联诊断：不罗列原始输出，而是主动关联 Events+Pod Status、Logs+Deployment History，给出根因判断而非症状堆砌
2. 结构化输出：统一Markdown格式报告，含表格、时间线、诊断结论、可执行建议，适合Slack/Discord/工单直接粘贴
3. 默认只读安全：写操作需用户显式确认（--confirm-write），支持回滚、扩缩容、Pod删除等受控修复动作
4. 多集群支持：通过--context无缝切换生产/测试环境
5. 大集群优化：自动过滤非Running Pod、限制Top 20资源消费者、事件截断100条，避免信息过载

潜在缺点与局限性

• 依赖本地kubectl：需用户本地配置有效的kubeconfig，无法直连云端托管集群API
• Metrics Server依赖：resources子命令需集群预装metrics-server，否则CPU/内存用量无法获取
• RBAC权限敏感：部分诊断需节点读取、事件查看等权限，受限用户可能遇到授权失败
• 无历史数据：仅分析当前集群状态，无法对比跨时间段趋势（需配合Prometheus等外部系统）
• Discord场景特殊处理：长输出需分片发送，宽表格在移动端体验受限

适合人群

• On-call SRE/运维工程师：快速分级（triage）生产事故，替代手工kubectl排查脚本
• 平台工程团队：标准化故障排查流程，降低新手K8s认知门槛
• DevOps开发者：自助排查自有命名空间应用异常，减少工单流转

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 误删/误回滚 | 用户确认后执行写操作 | 强制二次确认，显示完整命令与影响范围 |

| 敏感信息泄露 | Pod日志可能含密钥、token | 建议企业级部署时对接日志脱敏系统 |

| 集群过载 | 大规模集群sweep产生大量API请求 | 内置命名空间过滤与结果截断机制 |

| 权限提升试探 | 工具本身不提供提权，但可探测权限边界 | 遵循最小RBAC原则部署 |

核心用法

kube-medic是一款专为Kubernetes SRE和运维团队设计的智能诊断工具，通过封装kubectl命令提供六大核心功能：

1. sweep（全集群健康扫描）：一键获取节点状态、问题Pod分类、近期警告事件和组件健康度，适合快速了解集群整体状况。

2. pod（Pod尸检）：深入分析单个Pod的全生命周期数据，包括容器状态、当前/历史日志、关联事件和镜像版本匹配检测，帮助定位崩溃根因。

3. deploy（部署状态分析）：检查Deployment的副本状态、滚动更新进度、历史版本对比，识别卡住的发布流程。

4. resources（资源压力检测）：展示节点CPU/内存使用率、压力条件，以及Top 20资源消耗Pod和无资源限制的风险Pod。

5. events（事件追踪）：获取最近100条集群事件，支持按命名空间和时间窗口筛选，快速发现"发生了什么变化"。

6. 写入操作（需确认）：在诊断出需要修复的问题后，可执行回滚、重启、扩缩容等操作，但必须获得用户明确确认。

工具采用结构化JSON输出，AI Agent负责解析并关联多源数据（如将OOMKilled事件与内存限制不足关联），提供连贯的诊断结论而非孤立数据。

显著优点

诊断智能化：不同于简单的命令封装，kube-medic强调数据关联分析——将Pod状态、事件、日志、资源指标交叉验证，自动指出最可能的根因。例如识别"10分钟前的新版本部署 + 同时开始的Pod崩溃 = 部署引发故障"。

安全优先设计：默认只读架构从根本上杜绝误操作风险；写入操作受白名单限制（仅允许rollout undo/restart、scale、delete pod、cordon/uncordon），且必须通过--confirm-write显式确认。

注入防护完善：脚本启用set -euo pipefail严格模式，所有参数通过jq --arg传递，写入命令经shell元字符过滤和正则白名单双重校验，有效防止命令注入。

多云与多集群支持：通过--context参数无缝切换不同集群上下文，适配复杂的生产环境架构。

输出优化：针对Discord等场景提供紧凑摘要模式（首响应<1200字符），避免信息过载；同时支持完整详细输出满足深度排查需求。

零第三方依赖：仅依赖系统级工具kubectl和jq，无额外包管理风险，供应链攻击面极小。

潜在缺点与局限性

数据来源受限：诊断深度完全依赖集群中metrics-server和日志的可用性。若未安装metrics-server，资源压力检测功能失效；若应用日志未输出到stdout或已被轮转，日志分析受限。

RBAC权限敏感：虽然工具本身安全，但实际可访问数据范围由kubeconfig的RBAC权限决定。过高权限可能暴露敏感命名空间数据，过低权限则导致诊断不完整。需要用户自行配置平衡的最小权限角色。

Pod日志隐私风险：日志内容可能包含PII、令牌、内部URL等敏感信息，Skill本身不做脱敏处理，依赖应用层预处理和RBAC限制。

T3来源可信度：由个人开发者通过ClawHub发布，非知名组织背书，需用户自行审查代码或建立内部审计流程。

无历史趋势分析：当前仅提供实时快照诊断，缺乏时间序列对比和长期趋势预警能力。

适合的目标群体

平台/SRE工程师：需要快速响应on-call报警、进行 incident triage 的核心运维人员。

DevOps团队：负责CI/CD流水线故障排查、部署健康度监控的开发运维一体化团队。

Kubernetes管理员：管理多集群环境，需要统一诊断工具减少上下文切换成本。

技术支持团队：处理客户集群问题时，需要标准化诊断流程降低人为遗漏。

学习与认证场景：CKA/CKAD备考者可通过结构化输出加深对K8s故障排查的理解。

常规使用风险

性能风险：在超大规模集群（数千Pod级别）执行sweep或全命名空间events可能产生大量API调用，增加etcd和apiserver负载。建议始终配合--namespace限定范围。

误操作风险：尽管有确认机制，若用户配置了cluster-admin权限的kubeconfig，确认后的写入操作可能影响生产服务。建议生产环境使用只读RBAC角色。

数据残留风险：虽然Skill不持久化日志数据，但诊断过程中的输出会进入AI对话历史，可能间接暴露敏感信息。建议在处理含PII的集群后清除对话记录。

版本兼容性：依赖kubectl版本与目标集群版本匹配，跨大版本（如1.20 vs 1.30）可能存在API行为差异。

网络隔离环境：在严格网络隔离的私有集群中，需确保运行环境能正常访问Kubernetes API Server，VPN或代理配置问题可能导致连接失败。