helm-generator

Helm Chart 生成器

概述

通过确定性的脚手架、标准辅助模板、可复用模板和验证循环，生成可用于生产环境的 Helm Chart。

官方文档：

• Helm 文档 - 主要文档
• Chart 最佳实践 - 官方最佳实践指南
• 模板函数 - 内置函数
• Sprig 函数 - 扩展函数库

何时使用此技能

使用 helm-generator	使用其他技能
创建新的 Helm Chart	helm-validator：验证/检查现有 Chart
生成 Helm 模板	k8s-yaml-generator：原始 K8s YAML（不使用 Helm）
将 K8s 清单转换为 Helm	k8s-debug：调试已部署的资源
在 Helm 中实现 CRD	k8s-yaml-validator：验证 K8s 清单

触发短语

当提示中包含以下短语时，使用此技能：

• “创建 Helm Chart”
• “搭建 Helm Chart 脚手架”
• “生成 Helm 模板”
• “将清单转换为 Helm Chart”
• “构建包含 Deployment/Service/Ingress 的 Chart”

执行流程

按顺序执行以下阶段。不要跳过必需阶段。

阶段 1：收集需求（必需）

收集：

• 范围：完整 Chart、特定模板，或从清单转换
• 工作负载：deployment、statefulset 或 daemonset
• 镜像引用：仓库、可选标签或摘要
• 端口：服务端口和容器目标端口（分别设置）
• 运行时设置：资源、探针、自动伸缩、Ingress、存储
• 安全性：服务账户、安全上下文、可选的 RBAC/网络策略

缺少关键信息时，使用 request_user_input。

如果 request_user_input 不可用，则在常规聊天中询问，并基于明确的假设继续。

缺失信息	要询问的问题
镜像仓库/标签	“应使用哪个容器镜像？（例如 nginx:1.25）”
服务端口	“应公开哪个服务端口？”
容器目标端口	“应将流量转发到哪个容器端口？”
资源限制	“应设置哪些 CPU/内存限制？（例如 500m CPU、512Mi 内存）”
探针端点	“应用提供哪些健康检查端点？（例如 /health、/ready）”
伸缩要求	“是否应启用自动伸缩？如果是，最小/最大副本数和目标 CPU 百分比是多少？”
工作负载类型	“工作负载类型是什么：Deployment、StatefulSet 还是 DaemonSet？”
存储要求	“应用是否需要持久化存储？容量和访问模式是什么？”

不要默默假设关键设置。

阶段 2：查阅 CRD 文档（仅当范围包含 CRD 时）

1. 首先尝试 Context7：
   • mcp__context7__resolve-library-id
   • mcp__context7__query-docs
2. 如果 Context7 不可用或信息不完整，则按以下顺序回退：
   • Operator 官方文档（优先）
   • 常规网页搜索

另请查阅 references/crd_patterns.md 中的示例模式。

阶段 3：搭建 Chart 结构（必需）

运行：

bash scripts/generate_chart_structure.sh <chart-name> <output-directory> [options]

选项：

• --image <repo> — 支持仅指定仓库、带标签的镜像、带注册表端口的镜像，以及摘要引用
• --port <number> — 服务端口（默认值：80）
• --target-port <number> — 容器目标端口（默认值：8080）
• --type <type> — 工作负载类型：deployment、statefulset、daemonset（默认值：deployment）
• --with-templates — 生成资源模板（deployment.yaml、service.yaml 等）
• --with-ingress — 包含 ingress 模板
• --with-hpa — 包含 HPA 模板
• --force — 不提示，直接覆盖现有 chart

镜像解析行为：

• --image nginx:1.27 -> 仓库为 nginx，标签为 1.27
• --image registry.local:5000/team/app -> 保留仓库原样
• --image ghcr.io/org/app@sha256:... -> 摘要模式（不拼接标签）
• --tag 不能与摘要镜像引用同时使用

幂等性和覆盖行为：

• generate_chart_structure.sh：覆盖前会提示；使用 --force 可不交互地覆盖。
• generate_standard_helpers.sh：替换 templates/_helpers.tpl 前会提示；使用 --force 可跳过提示。

预期的脚手架结构：

mychart/
  Chart.yaml
  values.yaml
  templates/
    _helpers.tpl
    NOTES.txt
    serviceaccount.yaml
    service.yaml
    configmap.yaml
    secret.yaml
    deployment.yaml|statefulset.yaml|daemonset.yaml
    ingress.yaml (optional)
    hpa.yaml (optional)
  .helmignore

阶段 4：生成标准辅助模板

运行：

bash scripts/generate_standard_helpers.sh <chart-name> <chart-directory>

必需的辅助模板：name、fullname、chart、labels、selectorLabels、serviceAccountName。

备用方案：

• 如果脚本执行受阻，请复制 assets/_helpers-template.tpl，并将 CHARTNAME 替换为 chart 名称。

阶段 5：参考文档并生成模板（必需）

在此阶段查阅相关参考文档：

• references/resource_templates.md，了解要生成的资源模式
• references/helm_template_functions.md，了解模板函数的用法
• 仅当涉及 CRD 时，查阅 references/crd_patterns.md

打开文件的命令示例：

sed -n '1,220p' references/resource_templates.md
sed -n '1,220p' references/helm_template_functions.md

references/resource_templates.md 中涵盖的资源：

• 工作负载：Deployment、StatefulSet、DaemonSet、Job、CronJob
• 服务：Service、Ingress
• 配置：ConfigMap、Secret
• RBAC：ServiceAccount、Role、RoleBinding、ClusterRole、ClusterRoleBinding
• 网络：NetworkPolicy
• 自动扩缩：HPA、PodDisruptionBudget

必需的模板模式：

metadata:
  name: {{ include "mychart.fullname" . }}
  labels: {{- include "mychart.labels" . | nindent 4 }}

{{- with .Values.nodeSelector }}
nodeSelector: {{- toYaml . | nindent 2 }}
{{- end }}

annotations:
  {{- if and .Values.configMap .Values.configMap.enabled }}
  checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
  {{- end }}

工作负载必须包含校验和注解，但该注解必须是有条件的，且只能引用生成的模板（configmap.yaml、secret.yaml）。

阶段 6：创建 values.yaml

结构指南：

• 按逻辑对相关设置分组
• 使用 # -- 注释说明每个值
• 提供合理的默认值
• 包含安全上下文、资源限制和探针
• 分别明确设置 service.port 和 service.targetPort
• 确保 configMap.enabled / secret.enabled 与生成的模板保持一致

JSON Schema 验证请参阅 assets/values-schema-template.json。

阶段 7：验证

首选方案：运行 helm-validator 技能。

如果无法调用技能，请直接运行本地命令：

helm lint <chart-dir>
helm template test <chart-dir>

如果无法使用 helm，请明确说明阻碍，并执行部分检查：

• bash -n scripts/generate_chart_structure.sh
• bash -n scripts/generate_standard_helpers.sh
• 手动检查生成的文件和关键字段

修复后重新运行验证。

模板函数速查

完整指南请参阅 references/helm_template_functions.md。

函数	用途	示例
required	强制要求指定值	{{ required "msg" .Values.x }}
default	备用值	{{ .Values.x | default 1 }}
quote	为字符串加引号	{{ .Values.x | quote }}
include	使用辅助模板	{{ include "name" . | nindent 4 }}
toYaml	转换为 YAML	{{ toYaml .Values.x | nindent 2 }}
tpl	按模板渲染	{{ tpl .Values.config . }}
nindent	换行并缩进	{{- include "x" . | nindent 4 }}

使用 CRD

完整示例请参见 references/crd_patterns.md。

要点：

• 随项目一起发布的 CRD -> crds/ 目录（不进行模板化，卸载时也不会删除）
• CR 实例 -> templates/ 目录（完全模板化）
• 始终查阅文档，了解 CRD 规范要求
• 在 Chart.yaml 注解中注明 Operator 依赖项

将清单转换为 Helm

1. 参数化： 名称 -> helpers，值 -> values.yaml
2. 应用模式： 标签、条件语句，以及用于复杂对象的 toYaml
3. 添加 helpers： 创建包含标准 helpers 的 _helpers.tpl
4. 验证： 运行 helm-validator（或使用本地 lint/template 作为备用方案），然后使用不同的值进行测试

错误处理

问题	解决方案
模板语法错误	helm template test <chart-dir> --debug --show-only templates/<file>.yaml
未定义的值	运行 helm lint <chart-dir> --strict 并添加 default/required
校验和包含错误	确保 templates/configmap.yaml 和 templates/secret.yaml 存在，并正确设置 configMap.enabled / secret.enabled
端口不匹配（Service 与容器之间）	设置 service.port 和 service.targetPort，然后重新运行 helm template test <chart-dir>
CRD 验证失败	使用 Context7 或 Operator 文档核实 apiVersion/spec 字段，然后重新渲染
脚本参数错误	运行 bash scripts/generate_chart_structure.sh --help，并为选项标志传入必需的值

示例流程

包含模板、入口、HPA 和显式端口映射的完整脚手架：

bash scripts/generate_chart_structure.sh webapp ./charts \
  --image ghcr.io/acme/webapp:2.3.1 \
  --port 80 \
  --target-port 8080 \
  --type deployment \
  --with-templates \
  --with-ingress \
  --with-hpa

基于摘要的镜像脚手架：

bash scripts/generate_chart_structure.sh api ./charts \
  --image ghcr.io/acme/api@sha256:0123456789abcdef \
  --with-templates

不含模板的最小脚手架：

bash scripts/generate_chart_structure.sh starter ./charts

脚手架成功标准

仅当所有检查均通过时，才标记为完成：

• Chart.yaml、values.yaml、.helmignore、templates/NOTES.txt 和 templates/_helpers.tpl 均存在
• values.yaml 包含显式的 service.port 和 service.targetPort
• 如果使用了 --with-templates，则 serviceaccount.yaml、service.yaml、configmap.yaml、secret.yaml 和一个工作负载模板均存在
• 生成的工作负载模板对 config/secret 使用条件校验和注解
• 镜像渲染逻辑支持标签和摘要模式
• 已完成验证（使用 helm-validator 技能或本地备用命令），并报告结果

资源

脚本

脚本	用法
scripts/generate_chart_structure.sh	bash scripts/generate_chart_structure.sh <chart-name> <output-dir> [options]
scripts/generate_standard_helpers.sh	bash scripts/generate_standard_helpers.sh <chart-name> <chart-dir> [--force]

参考资料

文件	内容
references/helm_template_functions.md	完整的模板函数指南
references/resource_templates.md	所有 K8s 资源模板
references/crd_patterns.md	CRD 模式（cert-manager、Prometheus、Istio、ArgoCD）

资源文件

文件	用途
assets/_helpers-template.tpl	标准 helpers 模板
assets/values-schema-template.json	用于值验证的 JSON Schema

与 helm-validator 集成

生成 Chart 后，调用 helm-validator 并完成闭环：

1. 生成 Chart/模板
2. 运行 helm-validator（或使用本地备用命令）
3. 修复发现的问题
4. 重新验证，直至通过