Kubernetes YAML Validator

综合工具包，用于验证、检查和测试Kubernetes YAML资源。在验证Kubernetes清单、调试YAML语法错误、对集群执行干运行测试或使用需要文档查找的自定义资源定义（CRD）时，请使用这项技能。

重要：这是一个仅报告的验证工具。 不要修改文件，不要使用编辑工具，不要使用AskUserQuestion提供修复。生成一个包含建议修复的综合验证报告，然后让用户决定下一步怎么做。

Kubernetes YAML Validator

概览

这项技能提供了一个全面的Kubernetes YAML资源验证工作流程，结合了语法检查、模式验证、集群干运行测试和智能CRD文档查找。在将任何Kubernetes清单应用于集群之前，可以放心地进行验证。

使用此技能的时机

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

在将Kubernetes YAML文件应用于集群之前进行验证
调试YAML语法或格式错误
使用自定义资源定义（CRD）并需要文档
执行干运行测试以捕获准入控制器错误
确保YAML遵循Kubernetes最佳实践
了解清单中存在哪些验证错误（仅报告，用户手动修复）
用户要求“验证”、“检查”、“检查”或“测试”Kubernetes YAML文件

验证工作流程

按照这个顺序验证工作流程。每个阶段捕获不同类型的问题：

阶段0：预验证设置（资源计数检查）

重要：在运行任何验证工具之前，检查文件复杂性：

通过计算---文档分隔符或解析文件来计算文件中的资源数量
如果文件包含3个或更多资源，立即加载references/validation_workflow.md：
```
读取 references/validation_workflow.md
```
这确保您拥有处理复杂多资源文件的完整工作流程上下文。
记录资源计数以供验证报告摘要

这个预检查确保从验证开始就正确处理复杂文件。

阶段1：工具检查

在开始验证之前，验证所需的工具是否已安装：

bash scripts/setup_tools.sh

所需工具：

yamllint：YAML语法和样式检查
kubeconform：支持CRD的Kubernetes模式验证
kubectl：集群干运行测试（可选但推荐）

如果缺少工具，请从脚本输出中显示安装说明并继续使用可用的工具。在验证报告中记录缺少哪些工具。

阶段2：YAML语法验证

使用yamllint验证YAML语法和格式：

yamllint -c assets/.yamllint <file.yaml>

常见问题：

缩进错误（制表符与空格）
尾随空白
行长度违规
语法错误
重复键

报告方法：

报告所有语法问题，并提供文件：行引用
对于可修复的问题，显示建议的前后代码块
继续下一个验证阶段以收集所有问题，然后再报告

阶段3：CRD检测和文档查找

在模式验证之前，检测YAML是否包含自定义资源定义：

bash scripts/detect_crd_wrapper.sh <file.yaml>

包装脚本自动处理Python依赖项，如果PyYAML不可用，则创建临时虚拟环境。

**弹性解析：**该脚本对单个文档中的语法错误具有弹性。如果多文档YAML文件中有一些有效和一些无效文档，该脚本将：

解析有效文档并检测其CRD
报告无效文档的错误，但继续处理
这与kubeconform的行为相匹配，即使1/3有语法错误，也验证2/3资源

该脚本输出包含资源信息和解析状态的JSON：

{
  "resources": [
    {
      "kind": "Certificate",
      "apiVersion": "cert-manager.io/v1",
      "group": "cert-manager.io",
      "version": "v1",
      "isCRD": true,
      "name": "example-cert"
    }
  ],
  "parseErrors": [
    {
      "document": 1,
      "start_line": 2,
      "error_line": 6,
      "error": "mapping values are not allowed in this context"
    }
  ],
  "summary": {
    "totalDocuments": 3,
    "parsedSuccessfully": 2,
    "parseErrors": 1,
    "crdsDetected": 1
  }
}

对于每个检测到的CRD：

首先尝试上下文7 MCP（首选）：

使用mcp__context7__resolve-library-id与CRD项目名称
示例："cert-manager"用于cert-manager.io CRDs

然后使用mcp__context7__get-library-docs与：
- 从解析步骤中的context7CompatibleLibraryID
- 主题：CRD种类（例如，"Certificate"）
- 令牌：5000（根据需要调整）

如果上下文7失败，则回退到WebSearch：

搜索查询模式：
"<kind>" "<group>" kubernetes CRD "<version>" documentation spec

示例：
"Certificate" "cert-manager.io" kubernetes CRD "v1" documentation spec

提取关键信息：
- spec中所需字段
- 字段类型和验证规则
- 文档中的示例
- 版本特定更改或弃用

**通过kubeconform进行次要CRD检测：**如果detect_crd_wrapper.sh脚本未能检测到CRD（例如，所有文档都有语法错误），但kubeconform成功验证了CRD资源，您仍应查找该CRD的文档。解析kubeconform输出以识别已验证的CRD，并为它们执行上下文7/WebSearch查找。

**为什么这很重要：**CRD具有标准Kubernetes验证工具中不可用的自定义模式。了解CRD的spec要求可以防止验证错误，并确保资源配置正确。

阶段4：模式验证

使用kubeconform对Kubernetes模式进行验证：

kubeconform \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  -strict \
  -ignore-missing-schemas \
  -summary \
  -verbose \
  <file.yaml>

选项解释：

-strict：拒绝未知字段（生产推荐 - 捕获拼写错误）
-ignore-missing-schemas：跳过没有可用模式的CRD验证
-kubernetes-version 1.30.0：针对特定K8s版本进行验证

常见问题：

无效的apiVersion或kind
缺少所需字段
错误的字段类型
无效的枚举值
未知字段（使用-strict）

**对于CRDs：**如果kubeconform报告"未找到模式"，这是预期的。使用第3阶段的文档手动验证spec字段。

阶段5：集群干运行（如果可用）

**重要：始终先尝试服务器端干运行。**服务器端验证比客户端端捕获更多问题，因为它通过准入控制器和Webhook运行。

决策树：

1. 首先尝试服务器端干运行：
   kubectl apply --dry-run=server -f <file.yaml>

   └─ 如果成功 → 使用结果，继续第6阶段

   └─ 如果失败并出现连接错误（例如，"连接被拒绝",
      "无法连接",
      "没有配置"）：
      │
      ├─ 2. 回退到客户端干运行：
      │     kubectl apply --dry-run=client -f <file.yaml>
      │     在报告中记录："服务器端验证跳过（无集群访问权限）"
      │
      └─ 如果失败并出现验证错误（例如，"准入Webhook拒绝",
         "资源配额超出",
         "无效值"）：
         └─ 记录错误，继续第6阶段

   └─ 如果失败并出现解析错误（例如，"将YAML转换为JSON时出错",
      "yaml: 第X行：不允许在此上下文中使用映射值"）：
      └─ 记录错误，跳过客户端干运行（将出现相同的错误）
         在报告中记录："由于YAML语法错误，干运行被阻止 - 先修复语法错误"
         继续第6阶段

**注意：**早期阶段（yamllint，kubeconform）的解析错误也会导致干运行失败。不要尝试客户端干运行作为解析错误的回退 - 它将产生相同的错误。必须先修复解析错误，然后才能进行干运行验证。

服务器端干运行捕获：

准入控制器拒绝
策略违规（PSP，OPA，Kyverno等）
资源配额违规
缺少命名空间
无效的ConfigMap/Secret引用
Webhook验证

客户端干运行捕获（回退）：

基本模式验证
所需字段检查
类型验证
**注意：**不捕获准入控制器或策略问题

在您的报告中记录使用了哪种模式：

如果是服务器端：“执行了完整的集群验证”
如果是客户端端：“有限验证（无集群访问权限） - 未检查准入策略”
如果跳过：“跳过干运行 - kubectl不可用”

对于更新现有资源：

kubectl diff -f <file.yaml>

这显示了将发生的变化，有助于捕获意外的修改。

阶段6：生成详细验证报告（仅报告）

完成所有验证阶段后，生成一个综合报告。这是一个仅报告阶段。

永远不要做以下任何操作：

不要使用编辑工具修改文件
不要使用AskUserQuestion提供修复
不要提示用户询问他们是否想要应用修复
不要修改任何YAML文件

总是做以下操作：

生成一个综合验证报告
仅显示建议的前后代码块
让用户在查看报告后决定怎么做
以"下一步"结束，供用户手动采取

以表格格式总结所有发现的问题：

| 严重性 | 阶段 | 位置 | 问题 | 建议修复 |
|----------|-------|----------|-------|---------------|
| 错误 | 语法 | file.yaml:5 | 缩进错误 | 使用2个空格 |
| 错误 | 模式 | file.yaml:21 | 错误的类型 | 更改为整数 |
| 警告 | 最佳实践 | file.yaml:30 | 缺少标签 | 添加应用程序标签 |

按严重性分类：
- 错误（必须修复）：语法错误，缺少所需字段，干运行失败
- 警告（应该修复）：样式问题，最佳实践违规
- 信息（可选）：改进建议
为每个问题显示前后代码块：

对于每个问题，显示明确的前后YAML片段，显示建议的修复：
```
**问题1：deployment.yaml:21 - 字段类型错误（错误）**

当前：
```yaml
        - containerPort: "80"
```
建议修复：
```
        - containerPort: 80
```
**为什么：**containerPort必须是整数，而不是字符串。Kubernetes将拒绝字符串值。参考：请参阅k8s_best_practices.md "无效值"部分。

提供验证摘要：

## 验证报告摘要

文件：deployment.yaml
分析的资源：3（部署，服务，证书）

| 阶段 | 状态 | 发现的问题 |
|-------|--------|--------------|
| YAML语法 | ❌失败 | 2个错误 |
| CRD检测 | ✅通过 | 检测到1个CRD（证书） |
| 模式验证 | ❌失败 | 1个错误 |
| 干运行 | ❌失败 | 1个错误 |

总问题：4个错误，2个警告

## 详细发现

[如上所示列出每个问题的前后代码块]

## 下一步

1. 修复上述列出的4个错误（没有这些，部署将失败）
2. 考虑解决2个警告以获得最佳实践
3. 修复后重新运行验证以确认问题已解决

不要修改文件 - 这只是一个报告工具
- 清晰地呈现所有发现
- 让用户决定应用哪些修复
- 用户可以在查看报告后请求修复

Kubernetes YAML最佳实践参考

有关详细的Kubernetes YAML最佳实践，请加载参考：

读取 references/k8s_best_practices.md

此参考包括：

元数据和标签约定
资源限制和请求
安全上下文指南
探测配置
常见验证问题及其修复

何时加载（在这些情况下始终加载）：

模式验证失败并出现类型错误（例如，字符串与整数，无效值）
模式验证报告缺少所需字段
kubeconform报告无效字段值或未知字段
干运行因资源、探测或安全问题而失败
解释为什么需要修复时（提供最佳实践的上下文）

详细验证工作流程参考

有关深入的工作流程细节和错误处理策略，请加载参考：

读取 references/validation_workflow.md

此参考包括：

每个工具的详细命令选项和配置
错误处理策略
多资源文件处理
完整的工作流程图
故障排除指南

何时加载（在这些情况下始终加载）：

文件包含3个或更多资源（多文档YAML）
验证产生您以前没有见过或不能立即诊断的错误
需要了解完整的工作流程以进行调试
错误跨越多个验证阶段

处理多个资源

当YAML文件包含多个资源（由---分隔）时：

首先验证整个文件 使用yamllint和kubeconform
如果出现错误，通过检查行号确定哪个资源有问题
对于干运行，文件作为单位进行测试（Kubernetes按顺序处理）
在向用户报告结果时跟踪每个资源的问题

部分解析行为

当多文档YAML文件包含一些有效和一些无效文档时：

预期行为：

CRD检测脚本（detect_crd.py）将解析有效文档并跳过无效文档
kubeconform将验证它可以解析的资源，并报告无法解析的资源的错误
验证报告应清楚显示哪些文档已解析，哪些失败

示例场景： 一个包含3个文档的文件，其中文档1有语法错误：

文档1（部署）：第6行出现语法错误
文档2（服务）：有效
文档3（证书CRD）：有效

预期输出：

CRD检测：从文档3中找到证书CRD
kubeconform：报告文档1的错误，验证文档2和3
报告：为文档1显示语法错误，为文档2和3显示验证结果

在您的报告中：

| 文档 | 资源 | 解析 | 验证 |
|----------|----------|---------|------------|
| 1 | 部署 | ❌语法错误（第6行） | 跳过 |
| 2 | 服务 | ✅已解析 | ✅有效 |
| 3 | 证书 | ✅已解析 | ✅有效 |

行号参考样式：

始终使用文件绝对行号（相对于整个文件开头的行号）
这与yamllint、kubeconform和kubectl报告相匹配
示例：如果一个文件有3个文档，错误出现在文档2中，该文档从第35行开始，则报告为"第42行"（文件中的绝对行号），而不是"第7行"（相对于文档开头）
这种一致性使用户能够轻松地在编辑器中直接导航到错误

这确保即使某些文档有问题，用户也能获得最大的验证反馈。

错误处理策略

工具不可用

运行scripts/setup_tools.sh以检查可用性
提供安装说明
跳过可选阶段，但在验证报告中记录已跳过的内容
使用可用工具继续

集群访问问题

回退到客户端干运行
如果没有kubectl配置，则跳过集群验证
在验证报告中记录限制

CRD文档未找到

记录文档查找失败
使用kubeconform CRD模式进行验证

建议手动CRD检查：

kubectl get crd <crd-name>.group -o yaml
kubectl explain <kind>

验证阶段失败

即使一个失败，也继续下一个阶段
在向用户报告之前收集所有错误
首先优先修复早期阶段的错误

沟通指南

在呈现验证结果时：

清晰简洁地说明发现了什么
解释问题为什么重要（例如，“这将导致Pod创建失败”）
在相关时从最佳实践提供上下文
对相关问题进行分组（例如，所有缺少标签的问题一起）
为所有问题使用文件：行引用
显示修复复杂性 - 在问题标题中包括复杂性指示器：
- [简单]：单行修复，如缩进、拼写错误或值更改
- [中等]：多行更改或添加缺失字段/部分
- [复杂]：逻辑更改，重构，或影响多个资源的更改
示例格式在问题标题中：
```
**问题1：deployment.yaml:8 - 缩进错误（错误）[简单]**
**问题2：deployment.yaml:15-25 - 安全上下文缺失（警告）[中等]**
**问题3：deployment.yaml - 选择器与服务不匹配（错误）[复杂]**
```
始终提供一个综合报告，包括：
- 按严重性分类的问题摘要表
- 每个问题的前后代码块
- 错误和警告的总计数
- 清晰的用户下一步操作
永远不要提供应用修复 - 这是一个严格的报告工具
- 不要问"您想让我修复这个吗？"
- 不要使用AskUserQuestion进行修复确认
- 提交报告，让用户采取行动

性能优化

平行工具执行

为了提高验证速度，某些阶段可以并行执行：

可以并行运行（无依赖）：

yamllint（阶段2）和detect_crd_wrapper.sh（阶段3）可以同时运行
这两个工具独立于输入文件操作
需要两个工具的结果才能进行模式验证

示例并行执行：

# 并行运行这些（使用&和等待，或并行工具调用）：
yamllint -c assets/.yamllint <file.yaml>
bash scripts/detect_crd_wrapper.sh <file.yaml>

必须按顺序运行：

阶段0（资源计数检查）→ 在所有其他阶段之前
阶段1（工具检查）→ 使用任何工具之前
阶段4（模式验证）→ 在CRD检测之后（需要CRD信息进行上下文）
阶段5（干运行）→ 在模式验证之后
阶段6（报告）→ 在所有验证阶段完成后

何时并行化：

文件包含5个以上资源时，最受益于并行执行
对于小文件（1-2个资源），顺序执行即可

版本意识

始终考虑Kubernetes版本兼容性：

检查已弃用的API（例如，extensions/v1beta1 → apps/v1）
对于CRDs，确保apiVersion与集群中的相匹配
使用kubectl api-versions列出集群中可用的API版本
在可能的情况下参考特定版本的文档

测试覆盖指导

test/目录包含示例文件，以锻炼所有验证路径。使用这些来验证技能行为。

测试文件

测试文件	目的	预期行为
`deployment-test.yaml`	有效的标准K8s资源	所有阶段通过，报告显示"0个错误，0个警告"
`certificate-crd-test.yaml`	有效的CRD资源	检测到CRD，调用上下文7MCP，检索到文档
`comprehensive-test.yaml`	多资源，有意图的错误	语法错误被检测到，部分解析有效，CRD找到

要测试的验证路径

快乐路径（全部有效）
- 文件：deployment-test.yaml
- 预期：所有阶段通过，报告显示"0个错误，0个警告"
CRD检测路径
- 文件：certificate-crd-test.yaml
- 预期：检测到CRD，调用上下文7MCP，检索到文档
语法错误路径
- 文件：comprehensive-test.yaml
- 预期：yamllint捕获错误，kubeconform报告部分验证，干运行被阻止
多资源部分解析
- 文件：comprehensive-test.yaml（有3个资源，1个有语法错误）
- 预期：2/3资源验证，报告文档1的解析错误
无集群访问路径
- 任何有效文件，没有kubectl集群配置
- 预期：服务器端干运行失败，回退到客户端端
缺少工具路径
- 通过暂时从PATH中移除一个工具来测试
- 预期：setup_tools.sh报告缺失，使用可用工具继续验证

创建新的测试文件

添加测试文件时：

描述性地命名文件：<scenario>-test.yaml
在文件顶部的注释中记录预期行为
为错误路径测试包括有意的错误
测试标准K8s资源和CRD

预期报告结构

对于任何验证，报告应包括：

[ ] 按严重性分类的问题摘要表
[ ] 按阶段的状态表（通过/失败/跳过）
[ ] 文档解析表（多资源文件）
[ ] 每个问题的前后代码块
[ ] 修复复杂性指示器（[简单]，[中等]，[复杂]）
[ ] 文件绝对行号
[ ] "下一步"部分

资源

scripts/

detect_crd_wrapper.sh

包装脚本，处理Python依赖项管理
如果PyYAML不可用，则自动创建临时venv
调用detect_crd.py解析YAML文件
用法：bash scripts/detect_crd_wrapper.sh <file.yaml>

detect_crd.py

解析YAML文件以识别自定义资源定义
提取kind、apiVersion、group和version信息
输出JSON以进行程序处理
需要PyYAML（由包装脚本自动处理）
可以直接调用：python3 scripts/detect_crd.py <file.yaml>

setup_tools.sh

检查所需的验证工具
为缺少的工具提供安装说明
验证已安装工具的版本
用法：bash scripts/setup_tools.sh

references/

k8s_best_practices.md

Kubernetes YAML最佳实践的综合指南
涵盖元数据、标签、资源限制、安全上下文
常见验证问题及其修复
在提供验证错误上下文时加载

validation_workflow.md

详细的验证工作流程，包含所有阶段
命令选项和配置
错误处理策略
完整的工作流程图
加载复杂验证场景

assets/

.yamllint

为Kubernetes YAML预配置的yamllint规则
遵循Kubernetes约定（2个空格缩进、行长度等）
可以根据项目定制
用法：yamllint -c assets/.yamllint <file.yaml>