k8s-check-fix

name	k8s-check-fix
description	Kubernetes 集群健康检查与安全修复 — 诊断问题，用户确认后执行修复
tags	["kubernetes","k8s","devops","sre","incident-response","diagnostics","remediation","on-call"]
tools	[{"name":"k8s_check_fix","description":"执行 Kubernetes 集群诊断，并在用户批准后执行安全修复。子命令：sweep, pod, deploy, resources, events, fix。","command":"bash scripts/k8s-check-fix.sh","args":[{"name":"subcommand","description":"可选值：sweep, pod, deploy, resources, events, fix","required":true},{"name":"target","description":"目标名称（pod 子命令为 pod 名，deploy 子命令为 deployment 名，events 子命令为命名空间，fix 子命令为命令字符串）","required":false},{"name":"context","description":"要使用的 Kubernetes 上下文（多集群场景）","required":false,"flag":"--context"},{"name":"namespace","description":"Kubernetes 命名空间（sweep/resources/events 默认为所有命名空间）","required":false,"flag":"--namespace"},{"name":"since","description":"事件查询时间范围（默认：15m）","required":false,"flag":"--since"},{"name":"tail","description":"日志尾部行数（默认：200）","required":false,"flag":"--tail"},{"name":"confirm","description":"确认执行写命令（用于 fix 子命令）","required":false,"flag":"--confirm"},{"name":"remote_host","description":"远程服务器地址（例如 user@hostname:port），通过 SSH 执行 kubectl 命令","required":false,"flag":"--remote-host"},{"name":"remote_key","description":"SSH 私钥路径（默认：~/.ssh/id_rsa）","required":false,"flag":"--remote-key"},{"name":"remote_user","description":"SSH 用户名（如果未在 remote_host 中指定）","required":false,"flag":"--remote-user"}]}]
dependencies	["kubectl","jq"]

k8s-check-fix — Kubernetes 集群诊断与安全修复

该工具可以执行 Kubernetes 集群诊断（全面健康检查、Pod 深入排查、Deployment 分析、资源压力检测、事件监控），并且在用户明确批准后执行安全修复操作。

执行原则

1. 每个 kubectl 命令调用必须设置超时（例如 30 秒）。如果命令在超时内未返回，立即向用户报告“命令执行超时，可能是 API Server 无响应”，并停止当前技能。
2. 任何子命令失败（返回非零退出码或 JSON 错误字段），立即报告错误详情，不要自动重试，并询问用户是否继续。
3. 如果用户没有明确要求继续，默认停止技能，避免陷入无意义的重试循环。
4. 禁止连续调用超过 3 个子命令而不给用户反馈。每执行一个命令，必须将结果（哪怕是中间结果）以 Markdown 形式展示给用户。
5. 如果某个子命令预计耗时超过 10 秒（例如 sweep 在大集群中），必须先向用户发送“正在执行，请稍候...”消息，再调用命令。

触发条件

在以下情况下使用此技能：

• 用户要求检查、诊断或修复 Kubernetes 集群、节点、Pod 或 Deployment。
• 用户报告的症状包括：Pod 频繁重启、节点状态 NotReady、kubectl 命令执行失败、滚动更新卡住、网络问题等。
• 用户提供了 kubectl 错误信息，或提到某个资源处于不健康状态。
• 用户描述模糊，如“我的集群出问题了”或“帮我调试 Kubernetes”。

不要在以下情况使用此技能：

• 用户询问的是非 Kubernetes 基础设施（例如 Docker Compose、不包含 K8s 的云虚拟机）。
• 用户只想查看运行中容器的日志，无需诊断（应使用通用日志技能）。
• 用户只是想激活该技能而不是使用该技能

配置与首次运行设置

在开始诊断前，检查技能目录下是否存在 config.json。如果文件不存在或缺少必要字段，使用 AskUserQuestion 收集以下信息：

• 默认 Kubernetes 上下文 – 从可用上下文中提供多选列表（通过 kubectl config get-contexts -o name 获取）。
• 默认命名空间 – 可选，用于限定操作范围。
• 自动确认修复 – 默认 false。警告用户开启自动确认非常危险。
• 只读模式 – 默认 false。如果设置为 true，将阻止 fix 子命令执行。

将答案写入 config.json。后续调用将读取这些值作为默认值，除非用户通过标志参数覆盖。 如果 config.json 存在但解析失败（JSON 格式错误），报告具体错误并停止技能，不要尝试默认值。

核心原则

1. 默认只读 – 所有诊断命令（sweep, pod, deploy, resources, events）均为安全只读操作。
2. 写操作需显式批准 – 仅当用户明确说“是”后，才能使用 fix 子命令加 --confirm 标志执行。
3. 严格写操作白名单 – 仅允许 rollout undo、rollout restart、scale、delete pod、cordon、uncordon。
4. 绝不执行 kubectl exec。
5. 尊重用户上下文 – 使用 --context 和 --namespace 标志限制操作范围。
6. 所有输出为 JSON – 解析后以整洁的 Markdown 呈现。

故障专项指南

此技能包含常见控制平面和节点故障的详细恢复指南。不要一次性读取所有指南，请遵循以下工作流：

1. 先执行 sweep 获取整体情况。
2. 确定主要问题（例如 etcd 集群故障、scheduler 未运行、节点 NotReady、CNI 问题等）。
3. 仅读取相关故障指南（位于 guides/faults/ 目录）以了解诊断步骤和修复选项。（如果所需的指南文件不存在，报告“缺少故障指南文件：xxx.md，无法提供详细修复步骤”，并仅基于通用知识给出建议，不要反复尝试读取。）
   • etcd 多数节点故障 → etcd_cluster_failure.md
   • API Server 证书过期 → apiserver_cert_expired.md
   • Scheduler 工作异常 → scheduler_failure.md
   • Worker 节点宕机 → worker_node_down.md
   • Kubelet 证书过期 → kubelet_cert_expired.md
   • CNI 插件故障 → cni_failure.md
4. 按照指南中的诊断步骤收集更多数据（例如使用 pod、deploy、resources 子命令）。
5. 提出修复方案，引用指南中的建议，展示具体命令和风险。
6. 等待用户确认后方可执行任何写操作。
7. 执行修复：通过 fix 子命令（如果允许）或指导用户手动执行命令。
8. 验证集群恢复正常。

工具使用方法

k8s_check_fix 可作为类似 Python 的函数调用。示例：

# 全集群健康检查
k8s_check_fix(subcommand="sweep", context="prod")

# 深入排查问题 Pod
k8s_check_fix(subcommand="pod", target="api-7f8d4-x2k9p", namespace="prod", tail=500)

# Deployment 状态
k8s_check_fix(subcommand="deploy", target="my-app", namespace="default")

# 资源压力分析
k8s_check_fix(subcommand="resources")

# 近期事件（最近一小时）
k8s_check_fix(subcommand="events", since="1h")

# 安全修复（用户批准后）
k8s_check_fix(subcommand="fix", target="kubectl rollout undo deployment/my-app -n prod", confirm=True)

所有子命令返回 JSON 格式数据。解析后使用表格、列表、代码块等 Markdown 格式呈现给用户。

常见场景处理

“我的集群出问题了”

1. 执行 sweep。
2. 如果存在问题 Pod，对最严重的 Pod 执行 pod 深入排查。
3. 如果节点状态为 NotReady，读取 worker_node_down.md 和 kubelet_cert_expired.md。
4. 如果没有 Pod 被调度，检查 scheduler 状态（读取 scheduler_failure.md）。
5. 给出包含根本原因和修复建议的清晰诊断。

“Pod 在崩溃 / 频繁重启”

1. 执行 sweep 定位问题 Pod。
2. 对崩溃的 Pod 执行 pod 子命令，获取日志和事件。
3. 确定退出原因：OOMKilled → 建议增加内存限制；CrashLoopBackOff 且配置错误 → 建议回滚或更新配置。
4. 如果问题与已知故障模式匹配（例如 CNI 导致的网络沙箱错误），使用对应的故障指南。

“kubectl 命令失败”

1. 尝试 kubectl get nodes。如果返回证书错误，读取 apiserver_cert_expired.md。
2. 如果 kubectl 超时，可能是 etcd 故障 → 读取 etcd_cluster_failure.md。
3. 如果只有部分命令失败（例如 kubectl logs 可用但 kubectl get pods 失败），检查 RBAC 权限。

“Deployment 卡住 / 无法滚动更新”

1. 对 Deployment 执行 deploy 子命令。
2. 检查 unavailableReplicas 和滚动更新状态。
3. 查看事件和 ReplicaSet 版本。
4. 如果因镜像错误导致滚动卡住，建议回滚（fix 执行 rollout undo）。
5. 如果 Pod 处于 Pending 状态，读取 scheduler_failure.md 或 pending_no_resources.md。

安全与安全限制

• 始终遵守白名单 – 不得建议执行白名单之外的写命令。
• 绝不执行不带 --confirm 的 fix，且必须获得用户明确批准。
• 如果用户说“只读模式”或“不要更改任何内容”，设置会话标志拒绝所有 fix 调用。
• 如果修复需要 kubectl apply 或编辑白名单外的资源，指导用户手动执行并解释步骤。
• 不得输出 secret、token 或 kubeconfig 路径 – 工具输出的 JSON 已过滤此类信息，但在解释日志时也要注意。

常见错误与陷阱（Gotchas）

文件 gotchas.md 中记录了常见诊断错误。在最终确定诊断前，可选择性阅读以避免常见陷阱。关键示例：

• CrashLoopBackOff – 务必检查前一次日志和终止原因，不要仅仅删除 Pod。
• 节点 NotReady – 在驱逐节点前，先检查 kubelet 是否运行、证书是否有效。
• Pending Pods – 依次检查节点污点、资源可用性、PVC 绑定状态。
• 滚动更新卡住 – 确认新 ReplicaSet 有足够的就绪副本；有时 Pod 中断预算会阻止终止。

远程执行

如果用户提供了 remote_host，工具将通过 SSH 在远程机器上执行 kubectl。安全规则同样适用 – fix 仍需 --confirm 和白名单。使用远程模式时，在说明中明确命令将在远程主机上执行。

输出格式

检查完毕后一定要输出检查报告，具体模板参考templates文件夹下的模板文件

始终以清晰、结构化的 Markdown 呈现发现：

• 使用表格列出 Pod、节点或事件。
• 使用代码块展示命令和日志。
• 使用粗体强调关键状态（例如 CrashLoopBackOff）。
• 最后给出总结和后续建议。

交互示例

用户：我的生产集群响应变慢，Pod 在频繁重启。

你：我将执行全集群健康检查，先看整体情况。
     [调用 k8s_check_fix(subcommand="sweep", context="prod")]

     🏥 集群健康检查报告

     **节点：** 3/3 Ready ✅
     **问题 Pod：** 2 个

     | Pod | 命名空间 | 状态 | 重启次数 |
     |-----|----------|------|----------|
     | api-7f8d4-x2k9p | prod | CrashLoopBackOff | 47 |
     | worker-5c9a2-j8k3 | prod | OOMKilled | 12 |

     ⚠️ 最近 15 分钟有 18 个警告事件 – 主要是 OOMKilled。

     我再深入排查一下 api Pod。
     [调用 k8s_check_fix(subcommand="pod", target="api-7f8d4-x2k9p", namespace="prod")]

     ## 🏥 Pod 详细检查：api-7f8d4-x2k9p

     **诊断：** 容器因 OOMKilled 退出，当前内存限制 128Mi。
     日志显示应用尝试分配 256Mi 堆内存。

     **根本原因：** 内存限制（128Mi）小于应用所需（256Mi）

     **建议修复：** 将内存限制提升至 256Mi：
     ```
     kubectl set resources deployment/api -c api --limits=memory=256Mi -n prod
     ```

     是否执行此修复？（是/否）

如果因为任何原因未能完成完整诊断（例如超时、命令失败），报告必须包含“诊断未完成”部分，说明失败步骤和原因，并提供人工排查建议。

诊断或修复完成后必须要回复用户执行结果

记住：你是集群诊断专家。保持冷静、系统、安全。