Kubernetes 健康诊断
适用于任意 Kubernetes 集群配置的动态、由发现驱动的健康检查
开始之前
| 影响 | 值 |
|---|
| Token 节省 | 与手动探索 kubectl 相比约节省 70% |
| 设置时间 | 0 分钟（使用现有 kubectl 配置） |
| 覆盖范围 | 自动适配已安装的 Operator |
可预防的已知问题
| 问题 | 根本原因 | 此技能的帮助方式 |
|---|
| Operator 健康状态缺失 | 静态检查清单会漏掉 CRD | 动态 API 发现可检测所有已安装的 Operator |
| 诊断结果过时 | 手动检查会逐渐过时 | 实时查询集群 API |
| 覆盖不完整 | 集群配置未知 | 自动启用相关子 Agent |
快速开始
- 验证集群访问权限：确保已配置
kubectl，且能够访问集群
- 运行发现：执行
discover_apis.py，检测已安装的 Operator
- 分派 Agent：使用编排器，根据发现结果运行健康检查
# Step 1: Verify kubectl context
kubectl config current-context
kubectl cluster-info
# Step 2: Run API discovery
uv run .claude/skills/kubernetes-health/scripts/discover_apis.py
# Step 3: Review detected operators and dispatch health agents
关键规则
始终执行
- 运行健康检查前，验证 kubectl 上下文
- 使用只读 kubectl 命令（get、describe、logs）
- 先运行核心健康检查，再运行特定于 Operator 的检查
- 使用提供的评分方法汇总结果
切勿执行
- 在健康检查期间修改集群资源
- 在健康报告中公开密钥值（仅包含元数据）
- 跳过生产集群的上下文验证
- 未经 API 发现就假定 Operator 已安装
常见错误
| 错误 | 错误原因 | 正确做法 |
|---|
| 将 Operator 检查硬编码 | 会漏掉已安装的 Operator，也会检查未安装的 Operator | 使用 API 发现检测已安装的内容 |
| 顺序分派 Agent | 对于包含多个 Operator 的集群，速度较慢 | 并行运行 Operator Agent（相同优先级） |
| 原始 kubectl 输出 | Token 使用效率低，难以解析 | 使用脚本生成精简的 JSON 输出 |
随附资源
脚本
| 脚本 | 用途 |
|---|
scripts/discover_apis.py | 发现所有 API 组并检测已安装的 Operator |
scripts/health_orchestrator.py | 将发现的 API 映射到专用健康检查 Agent |
scripts/aggregate_report.py | 将多个 Agent 的结果汇总为统一报告 |
参考资料
| 文件 | 内容 |
|---|
references/operator-checks.md | 每个受支持 Operator 的详细健康检查 |
references/health-scoring.md | 评分方法和权重分配 |
模板
| 文件 | 用途 |
|---|
templates/health-report.json | 健康报告输出的 JSON 架构 |
依赖项
必需
| 包 | 版本 | 用途 |
|---|
| kubectl | Latest | 集群交互 |
| Python | >= 3.11 | 脚本执行 |
| uv | Latest | Python 脚本运行器 |
可选
| 包 | 版本 | 用途 |
|---|
| kubernetes | >= 28.1.0 | Python 客户端（用于高级发现） |
支持的 Operator
该技能会自动检测并分派专用 Agent，用于检查：
| Operator | API 组 | Agent |
|---|
| 核心 K8s | （始终启用） | k8s-core-health-agent |
| Crossplane | crossplane.io | k8s-crossplane-health-agent |
| ArgoCD | argoproj.io | k8s-argocd-health-agent |
| Cert-Manager | cert-manager.io | k8s-certmanager-health-agent |
| Prometheus | monitoring.coreos.com | k8s-prometheus-health-agent |
健康评分
| 状态 | 分数范围 | 标准 |
|---|
| HEALTHY | 90-100 | 所有检查均通过，无警告 |
| DEGRADED | 60-89 | 存在部分警告，无严重问题 |
| CRITICAL | 0-59 | 存在影响可用性的严重问题 |
故障排除
kubectl 连接问题
# Verify context
kubectl config current-context
# Test connectivity
kubectl cluster-info
# Check permissions
kubectl auth can-i get pods --all-namespaces
发现结果为空
- 确保集群可访问
- 检查 API 发现所需的 RBAC 权限
- 验证 kubectl 版本兼容性
Agent 调度失败
- 确认发现的 API 组与 Agent 触发条件匹配
- 检查
.claude/agents/specialized/kubernetes/ 中是否存在 Agent 文件
- 查看 Agent 的工具限制
设置清单
