# K8S Check Fix

> Kubernetes 集群健康检查与安全修复 — 诊断问题，用户确认后执行修复

- Skill: `ascend/k8s-check-fix` (Agent Skill, multi-file: 36 files)
- Install (CLI): `npx skillmds@latest add ascend/k8s-check-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ascend/k8s-check-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ascend (https://skillmd.com/u/ascend)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ascend/k8s-check-fix

---


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

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

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

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