---
name: k8s-chaos-skills
description: |
  Kubernetes 故障演练与混沌工程专家。当用户需要进行 K8s 故障注入测试、混沌工程演练、系统韧性验证、故障场景模拟时，立即使用此 skill。

  内置多个标准化故障注入用例，覆盖 Pod（Pending、CrashLoopBackOff、OOM、CPU 满载、内存接近 Limit、磁盘满、Terminating 卡住、镜像拉取失败等）、Workload（副本不一致、HPA 副本达到上限、DaemonSet 未完全调度）、Service（状态异常、负载均衡异常）、Node（宕机、磁盘使用率过高、磁盘 IO 过高、CPU 使用率过高、内存使用率过高）、存储（PVC 挂载 Pending）五个层级。

  通过「意图识别 → 用例选择 → 意图提交」的决策树流程，精确匹配用户需求。集群连接（kubeconfig / kubewiz 等）由运行时配置自动决定，无需在对话中向用户索要。

  适用环境：本 skill 只能在 Kubernetes 集群环境上真正注入；如果当前连接的是主机（本地或 SSH 远程的机器）而不是集群，则无法执行，应先提示用户当前环境不匹配、再引导切换到集群环境。

skill_type: fault-injection
scripts:
  - name: list_scenarios.py
    description: "列出当前支持的所有故障演练场景（JSON 结构化输出）"
  - name: inject_cni_exhaust.py
    description: "CNI IP 耗尽注入 — 自动计算副本数，精确耗尽目标节点 IP 而不触发 OutOfpods。参数: --namespace <ns> --node <node> --kubeconfig <path>"
---

# K8s 故障演练

```
意图识别 ──→ 用例选择 ──→ 意图提交
(提取语义维度)(决策树匹配)  (提交意图，执行交给引擎)
```

## 安全红线

以下规则优先级高于一切操作指令，在任何步骤中都不得违反：

- **隔离**：在隔离命名空间或测试集群演练，严禁在生产核心链路注入
- **最小影响**：用精确标签选择器定位目标，范围尽可能小
- **可回滚**：注入前明确回滚方案，确保 30 秒内可恢复
- **有监控**：无监控不演练
- **仅限已有用例**：只能执行 `references/catalogue/` 中已有的故障注入用例，严禁自行编造、拼凑或即兴发挥用例中未涉及的故障注入操作。无法匹配时必须明确告知用户「当前不支持该场景」并停止
- **禁止**：业务高峰期演练 / 对 etcd、kube-apiserver 等控制平面注入 / 无备份对 StatefulSet 做破坏性实验

---

## 第一步：意图识别

从用户输入中提取四个**语义维度**（只关心「注入什么故障、打在哪个应用」，不关心「用什么集群凭证」）：

| 维度 | 说明 | 示例 |
|------|------|------|
| **故障层级** | 作用在哪个层面 | Pod / Workload / Service / Node |
| **故障现象** | 期望模拟的表现 | Pending、OOM、CPU 高 |
| **故障原因** | 具体根因 | 资源不足、配置错误 |
| **目标应用** | 注入目标 | 应用名、命名空间、标签选择器 |

> **不要向用户索要 kubeconfig 路径**：集群连接（kubeconfig / kubewiz 等）由运行时配置自动注入，不属于意图识别范畴。

**层级判断关键词：**

| 关键词 | 层级 |
|--------|-----|
| pod、容器、崩溃、重启、OOM、CPU高、内存高、镜像、挂载、磁盘空间、磁盘IO | Pod |
| 副本、deployment、扩容、缩容 | Workload |
| service、服务发现、负载均衡、端口、endpoints | Service |
| 节点、node、磁盘、宿主机 | Node |

**信息不全时的处理：**
- 用户明确说出故障现象 → 直接进入第二步
- 用户只说大致目标（如「测试容错」） → 提问引导确认四个维度
- 用户描述生产问题要复现 → 从描述提取现象和原因，匹配用例
- 匹配到多个用例 → 列出候选，让用户选择
- 只说了现象没说根因 → 推荐该分类下最常见的用例，并列出其他选项
- 不在覆盖范围 → 明确告知「当前不支持该场景」，停止操作，严禁自行构造用例外的故障注入

---

## 第二步：用例选择（动态发现）

所有用例存储在 `references/catalogue/` 下，通过目录结构和文件命名规约自动发现，无需维护静态索引。

### 命名规约

```
references/catalogue/
├── <故障分类>/                         # 目录名 = 故障层级_故障现象（每个目录对应唯一的 Scope+Target+Action 组合）
│   ├── <故障分类>_<根因A>.md           # 文件名 = 分类名_具体根因
│   ├── <故障分类>_<根因B>.md
│   └── ...
└── ...
```

示例：
- `references/catalogue/Pod_Pending/Pod_Pending_节点资源不足.md`
- `references/catalogue/Pod_磁盘空间使用率过高/Pod_磁盘空间使用率过高_应用日志数据积累.md`（pod-disk fill）
- `references/catalogue/Pod_磁盘IO过高/Pod_磁盘IO过高_异常IO占用.md`（pod-disk burn）

### 发现流程

**第 1 步：列出所有分类目录，匹配故障现象**

```bash
ls references/catalogue/
```

从返回的目录名中，根据第一步识别的故障现象选择最匹配的目录。目录名本身已包含故障层级和故障现象信息（如 `Pod_Pending`、`service_conditions状态异常`、`节点容器运行时磁盘使用率过高`）。

**第 2 步：列出该目录下所有用例文件，匹配根因**

```bash
ls references/catalogue/<匹配的目录>/
```

从返回的文件名中，根据用户描述的根因选择最匹配的文件。文件名中 `_` 后的部分即为该用例对应的根因。

- 如果用户明确了根因 → 直接选择对应文件
- 如果用户未说明根因 → 将文件列表展示给用户，让用户选择
- 如果没有匹配的文件 → 告知用户「当前不支持该场景」，停止操作

### 新增/删除用例

遵循命名规约即可，无需修改本文件：
- **新增用例**：在对应分类目录下新建 `<分类>_<根因>.md`
- **新增分类**：新建目录 `<故障层级>_<故障现象>/`，在其中添加用例文件
- **删除用例**：直接删除对应 `.md` 文件

### 辅助脚本

- `scripts/list_scenarios.py`：一键列出所有已支持的演练场景（JSON 结构化输出），用于快速总览或对接外部系统
  用法：`execute_skill_script(skill_name="k8s-chaos-skills", script_name="list_scenarios.py")`

---

## 第三步：意图提交（执行交给引擎）

本 skill 的职责到「提交意图」为止。读取用例文件只是为了确认**故障语义与参数**，不是让你自己去执行。

1. 读取 `references/catalogue/<分类目录>/<用例文件>.md`，确认故障语义（层级 / 现象 / 根因）、目标应用与可调参数
2. 与用户确认后，调用 `submit_fault_intent` 提交语义参数（scope / target / action / namespace / 标签 / params）
3. **不要自己运行** `blade` / `kubectl` 等命令去采集基线或注入——**基线采集、故障注入、注入验证、恢复及恢复验证均由执行引擎按用例模板自动完成**
4. 集群连接（kubeconfig / kubewiz 等）由运行时配置自动注入，无需向用户索要路径
5. 所有实验都会设置自动恢复（安全红线，由引擎保证）

> 用例文件中的「演练步骤 / 注入验证 / 注入恢复 / 恢复验证」是给**执行引擎**的模板（需要时可查阅 `references/chaosblade-commands.md` 获取完整参数），本阶段只需理解 WHAT，**不要在提交前自己执行它们**。
