SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场k8s-yaml-validator

k8s-yaml-validator

部署与运维

查看项目

更新于 10-15 16:27

技能介绍

用途

k8s-yaml-validator 是一个面向 Kubernetes YAML 资源的验证技能，适用于在将清单应用到集群前进行校验、lint、审计或 dry-run。它覆盖 Deployment、Service、ConfigMap、CRD 等资源类型，目标是在部署前发现语法、schema、准入控制等层面的问题。

主要能力

该技能提供分阶段验证工作流：

  • Stage 0 预校验准备：运行捆绑脚本统计多文档 YAML 的文档数量，当文档数大于等于 3 时加载 references/validation_workflow.md，并在最终报告中包含文档数。
  • Stage 1 工具检查：检查 yamllint、kubeconform、kubectl 是否安装；缺失工具时展示安装指引，用现有工具继续，并在报告中记录跳过的阶段。
  • Stage 2 YAML 语法校验：使用 yamllint 检查缩进、行尾空格、行长度、语法错误、重复键等，报告 file:line 位置。
  • Stage 3 CRD 检测与文档查询：通过脚本检测文档中的 Custom Resource Definitions，输出 JSON（resources、parseErrors、summary）。对每个检测到的 CRD，优先用 Context7 MCP 解析库并查询文档，失败时回退到网络搜索；也可通过 kubeconform 输出进行二次 CRD 检测。
  • Stage 4 Schema 校验：使用 kubeconform，配合默认 schema 与 datreeio CRDs-catalog，启用 -strict、-ignore-missing-schemas、-summary、-verbose。可捕获无效 apiVersion/kind、缺失必填字段、字段类型错误、无效枚举值、未知字段等。
  • Stage 5 集群 Dry-Run：优先 kubectl apply --dry-run=server；连接失败时回退到 --dry-run=client --validate=false 的仅解析模式；再失败则记录跳过。还可使用 kubectl diff 查看对已有资源的变更。
  • Stage 6 生成详细报告：汇总所有阶段问题，按严重程度（Error/Warning/Info）分类，展示建议修复的前后代码块，并以 Next Steps 结束。

使用方式

该技能通过触发短语调用，例如在提示中出现“Validate this Kubernetes YAML before deploy.”“Lint these manifests and report what is broken.”“Run dry-run checks on this manifest.”等。

它采用确定性路径设置：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" SKILL_DIR="$REPO_ROOT/devops-skills-plugin/skills/k8s-yaml-validator" TARGET_FILE="$REPO_ROOT/<relative/path/to/file.yaml>"

若 REPO_ROOT 为空则停止并询问仓库根目录；若 SKILL_DIR 不存在则停止并报告路径不匹配；若 TARGET_FILE 不存在则停止并询问正确文件。

主要命令包括：

python3 "$SKILL_DIR/scripts/count_yaml_documents.py" "$TARGET_FILE" bash "$SKILL_DIR/scripts/setup_tools.sh" yamllint -c "$SKILL_DIR/assets/.yamllint" "$TARGET_FILE" bash "$SKILL_DIR/scripts/detect_crd_wrapper.sh" "$TARGET_FILE" kubeconform 命令（含 -schema-location、-strict、-ignore-missing-schemas、-summary、-verbose） kubectl apply --dry-run=server -f "$TARGET_FILE"

适用场景

  • 在集群应用前验证 Kubernetes YAML 文件。
  • 调试 YAML 语法或格式错误。
  • 处理 Custom Resource Definitions（CRD）并需要查阅文档。
  • 通过 dry-run 捕获准入控制器错误。
  • 确保 YAML 符合 Kubernetes 最佳实践。
  • 用户请求“validate”“lint”“check”“test”Kubernetes YAML 文件。

限制

该技能是严格的只读报告工具：不修改任何用户文件，不使用 Edit 进行修复，不请求应用修复的许可；仅提供前后代码块作为建议。

工具缺失时相关阶段被跳过并记录：python3 不可用时 CRD 解析器跳过、资源计数改为估算；yamllint、kubeconform、kubectl 缺失时对应阶段跳过。kubeconform 不报告文件绝对行号，解析错误需将文档相对行号转换为文件绝对行号，schema 校验错误仅给 JSON 路径需自行查找行号。CRD 若 kubeconform 报告 “no schema found”，属于预期情况，需依据 Stage 3 文档手动校验。dry-run 时若遇解析错误，不再尝试客户端回退，需先修复语法。