k8s-yaml-generator

Kubernetes YAML 生成器

通过确定性步骤、有限的 CRD 研究，以及完整资源输出的强制验证来生成 Kubernetes 清单。

触发指南

当用户要求创建或更新 Kubernetes YAML 时使用此技能，例如：

• “为我的应用生成 Deployment + Service 清单。”
• “创建一个 Argo CD Application CRD。”
• “编写一个带 PVC 模板的 StatefulSet。”
• “生成符合最佳实践、可用于生产环境的 Kubernetes YAML。”

仅验证类请求不要使用此技能。仅验证时，请使用 k8s-yaml-validator。

执行模型

规范性关键词：

• MUST：必须
• SHOULD：默认执行，除非用户另有要求
• MAY：可选

确定性步骤：

1. 预检请求，并检查路径和渲染是否正常。
2. 收集最低限度的必要输入。
3. 解析 CRD 引用（仅当涉及 CRD/自定义 API 时，才执行有限工作流）。
4. 生成 YAML 并进行基础质量检查。
5. 执行强制验证（如果工具不可用，则遵循已记录的回退流程）。
6. 提供 YAML、明确的验证报告和假设。

如果某个步骤受环境限制而无法执行，请执行该步骤的回退流程并继续。

1) 预检

生成之前：

• 确认输出是完整清单还是仅代码片段。
• 若用户提供了目标 Kubernetes 版本，请予以确认。
• 使用任何本地文件路径前，先确认路径存在。
• 在适用时，将资源名称规范化为符合 DNS-1123 的名称。

预检停止条件：

• 如果缺少必要的核心输入（资源类型、基于 Pod 的资源所需的工作负载镜像，或 CRD 的 kind/apiVersion），请先询问用户。

2) 收集必要输入

收集：

• 资源类型（Deployment、Service、ConfigMap、CRD kind 等）
• apiVersion + kind
• Namespace/作用域要求
• 端口、副本数、镜像、探针、存储，以及密钥/配置需求
• 环境假设（dev/staging/prod）
• 对于 CRD：项目名称及已知的目标 CRD 版本

安全默认值（在输出中明确说明）：

• Namespace：default（限定 Namespace 的资源）
• Deployment 副本数：2
• Service 类型：ClusterIP
• 镜像拉取策略：IfNotPresent（除非用户需要强制拉取）

3) CRD 查询工作流（有限）

仅在涉及 Kubernetes 内置 API 组之外的自定义 API 时执行此步骤。

3.1 确定 CRD 目标

提取：

• API 组、版本、kind（例如 argoproj.io/v1alpha1、Application）
• 用户请求的产品/版本（例如 Argo CD v2.9.x）

3.2 Context7 首选路径

使用正确的 Context7 工具和负载：

1. mcp__context7__resolve-library-id
2. mcp__context7__query-docs

示例负载：

Tool: mcp__context7__resolve-library-id
libraryName: "argo-cd"
query: "Find Argo CD documentation for Application CRD schema compatibility"

Tool: mcp__context7__query-docs
libraryId: "/argoproj/argo-cd/v2.9.0"
query: "Application CRD required spec fields for apiVersion argoproj.io/v1alpha1 with minimal valid example"

选择规则：

• 优先选择名称完全匹配的项目/库。
• 用户指定版本时，优先选择带版本的 libraryId。
• 否则使用不带版本的 ID，并注明版本不确定性。

3.3 限额与停止条件

限制查询次数，避免无限重试：

• resolve-library-id：最多尝试 2 次（首选名称 + 一个备用名称）。
• query-docs：总计最多进行 3 次针对性查询。
• 网页回退：最多进行 2 次特定版本搜索。

满足以下全部条件时提前停止：

• 已确定必需的 CRD 字段。
• 已找到至少一个权威示例。
• 已知版本兼容性，或已明确标注为未知。

达到限额后必须停止：

• 仅生成已通过来源验证的字段。
• 将其余字段标记为 Needs confirmation。
• 报告剩余风险，并请求用户提供以下其中一项：
  • 确切的 CRD 文档 URL，或
  • 集群内省输出（例如，在可用时提供 kubectl explain <kind>.spec）。

3.4 回退顺序

按以下顺序使用：

1. Context7（resolve-library-id -> query-docs）
2. 通过网页搜索查找项目官方文档
3. 集群本地内省（若可访问集群，则使用 kubectl explain）

如果以上途径均不可用，请提供明确标注的最简草案，且不得声称其完全符合 CRD 要求。

4）YAML 生成规则

应用以下检查：

• 使用明确且未弃用的 API 版本。
• 在相关资源中使用一致的标签（app.kubernetes.io/*）。
• 为命名空间范围内的资源指定命名空间。
• 除非用户选择不添加，否则为 Pod 工作负载添加资源请求和限制。
• 在适用的情况下，为长期运行的服务添加就绪探针和存活探针。
• 使用 securityContext，默认避免以 root 身份运行。
• 按依赖安全的顺序排列多个资源（例如，在 Deployment 使用者之前创建 ConfigMap）。

最低标签基线：

labels:
  app.kubernetes.io/name: myapp
  app.kubernetes.io/instance: myapp-prod
  app.kubernetes.io/part-of: myplatform
  app.kubernetes.io/managed-by: codex

5）强制验证与应急方案

生成完整清单时，必须进行验证。

首选方案：

• 调用 k8s-yaml-validator。
• 循环执行修复 → 重新验证，直至所有阻塞问题解决。

每次验证后都必须报告：

• Validation mode：k8s-yaml-validator | script fallback | manual fallback
• Syntax：pass/fail
• Schema：pass/fail/partial
• CRD check：pass/fail/partial
• Dry-run：server/client/skipped
• Blocking issues remaining：yes/no

应急方案 A：验证工具技能不可用

运行以下直接命令：

bash devops-skills-plugin/skills/k8s-yaml-validator/scripts/setup_tools.sh
yamllint -c devops-skills-plugin/skills/k8s-yaml-validator/assets/.yamllint <file.yaml>
kubeconform -schema-location default -strict -ignore-missing-schemas -summary <file.yaml>
server_out="$(mktemp)"
client_out="$(mktemp)"
trap 'rm -f "$server_out" "$client_out"' EXIT

if kubectl apply --dry-run=server -f <file.yaml> >"$server_out" 2>&1; then
  echo "server_validation=passed"
elif grep -Eqi "connection refused|no such host|i/o timeout|tls handshake timeout|unable to connect to the server|no configuration has been provided|the server doesn't have a resource type" "$server_out"; then
  echo "server_validation=skipped"
  if kubectl apply --dry-run=client -f <file.yaml> >"$client_out" 2>&1; then
    echo "client_validation=passed"
  else
    echo "client_validation=failed"
    cat "$client_out"
    exit 1
  fi
else
  echo "server_validation=failed"
  cat "$server_out"
  exit 1
fi

应急方案 B：本地工具部分不可用

• 运行可用的检查。
• 明确记录跳过的检查。
• 为每项跳过的检查添加剩余风险说明。

应急方案 C：反复验证失败

• 最多执行 3 轮修复／重新验证。
• 如果仍然失败，则停止并返回：
  • 当前 YAML，
  • 完整的失败错误信息，
  • 解除阻塞所需的最小用户决策／输入。

验证例外：

• 仅请求代码片段或仅请求文档的任务可以跳过完整验证，但输出必须注明 Validation status: Skipped (reason)。

6）交付约定

最终输出必须包含：

1. 生成的 YAML。
2. 生成内容（资源列表、命名空间／作用域）。
3. 按规定格式提供的验证报告。
4. 使用的假设和默认值。
5. 使用的参考资料：
   • 使用的 Context7 ID／查询（针对 CRD）
   • 使用的外部文档／搜索结果
   • 跳过／缺失的项目及其影响

建议的后续命令：

kubectl apply -f <filename>.yaml
kubectl get <resource-type> <name> -n <namespace>
kubectl describe <resource-type> <name> -n <namespace>

7）标准示例流程

示例 A：内置资源（Deployment + Service）

1. 收集应用镜像、端口、副本数和命名空间。
2. 生成标签／选择器一致的 Deployment 和 Service。
3. 使用 k8s-yaml-validator 进行验证。
4. 返回 YAML、验证报告和假设。

示例 B：CRD 资源（Argo CD Application）

1. 提取 argoproj.io/v1alpha1 + Application。
2. 执行有界 Context7 查询（先 resolve-library-id，再 query-docs）。
3. 如有需要，执行有界网络搜索回退。
4. 仅使用已验证字段生成 CRD YAML。
5. 验证、报告任何部分验证情况，并说明剩余风险。

8）完成标准

只有在所有适用检查均通过后，执行才算完成：

• 触发的用例正确（生成，而非仅验证）。
• 已收集所需输入，或已记录明确的假设。
• CRD 查询遵循有界阈值和停止条件。
• 工具名称和命令路径有效且一致。
• 已验证完整清单（或已记录回退方案及剩余风险）。
• 最终响应包含 YAML、验证报告、假设和参考资料。