k8s-check-fix

Files (36)

• CHANGELOG.md
• SECURITY.md
• SKILL.md
• config.json
• examples.md
• gotchas.md
• README.md · references/
• deployment_checks.md · references/
• apiserver_cert_expired.md · references/faults/
• cni_failure.md · references/faults/
• etcd_cluster_failure.md · references/faults/
• kubelet_cert_expired.md · references/faults/
• scheduler_failure.md · references/faults/
• worker_node_down.md · references/faults/
• network_checks.md · references/
• node_checks.md · references/
• pod_checks.md · references/
• security_notes.md · references/
• k8s-check-fix.sh · scripts/
• preflight.sh · scripts/lib/
• ask_user.sh · scripts/lib/
• common.sh · scripts/lib/
• config_loader.sh · scripts/lib/
• k8s_utils.sh · scripts/lib/
• remote.sh · scripts/lib/
• deploy.sh · scripts/subcommands/
• events.sh · scripts/subcommands/
• fix.sh · scripts/subcommands/
• pod.sh · scripts/subcommands/
• resources.sh · scripts/subcommands/
• sweep.sh · scripts/subcommands/
• deployment_report_template.md · templates/
• fix_plan_template.md · templates/
• pod_autopsy_template.md · templates/
• report_templates.md · templates/
• style_guide.md · templates/

SKILL.md (first lines)

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

From Ascend/agent-skills, MulanPSL-2.0.

More from Ascend/agent-skills