helm-chart-builder

Helm Chart 构建器

生产级 Helm Chart。合理的默认值。安全优先的设计。拒绝盲目照搬。

这是一套有明确主张的 Helm 工作流，可将临时编写的 Kubernetes 清单转变为可维护、可测试、可复用的 Chart。内容涵盖 Chart 结构、values 设计、模板模式、依赖管理和安全加固。

这不是 Helm 教程，而是一组关于如何构建让运维人员信任、开发人员不抵触的 Chart 的具体决策。

---

斜杠命令

命令	功能
/helm:create	搭建符合最佳实践结构的生产级 Helm Chart
/helm:review	分析现有 Chart 的问题，例如缺失标签、硬编码值、模板反模式
/helm:security	审计 Chart 的安全问题，包括 RBAC、网络策略、Pod 安全和密钥处理

---

何时启用此技能

识别用户的以下请求模式：

• “为这个服务创建一个 Helm Chart”
• “审查我的 Helm Chart”
• “这个 Chart 安全吗？”
• “设计一个 values.yaml”
• “添加一个子 Chart 依赖”
• “设置 helm test”
• “[工作负载类型] 的 Helm 最佳实践”
• 任何涉及以下内容的请求：Helm Chart、values.yaml、Chart.yaml、templates、helpers、_helpers.tpl、子 Chart、helm lint、helm test

如果用户已有 Helm Chart，或希望将 Kubernetes 资源打包，则适用本技能。

---

工作流

/helm:create — Chart 脚手架

1. 确定工作负载类型

   • Web 服务（Deployment + Service + Ingress）
   • Worker（Deployment，无 Service）
   • CronJob（CronJob + ServiceAccount）
   • 有状态服务（StatefulSet + PVC + Headless Service）
   • 库 Chart（无模板，仅包含 helpers）

2. 搭建 Chart 结构

   mychart/
   ├── Chart.yaml              # Chart metadata and dependencies
   ├── values.yaml             # Default configuration
   ├── values.schema.json      # Optional: JSON Schema for values validation
   ├── .helmignore             # Files to exclude from packaging
   ├── templates/
   │   ├── _helpers.tpl        # Named templates and helper functions
   │   ├── deployment.yaml     # Workload resource
   │   ├── service.yaml        # Service exposure
   │   ├── ingress.yaml        # Ingress (if applicable)
   │   ├── serviceaccount.yaml # ServiceAccount
   │   ├── hpa.yaml            # HorizontalPodAutoscaler
   │   ├── pdb.yaml            # PodDisruptionBudget
   │   ├── networkpolicy.yaml  # NetworkPolicy
   │   ├── configmap.yaml      # ConfigMap (if needed)
   │   ├── secret.yaml         # Secret (if needed)
   │   ├── NOTES.txt           # Post-install usage instructions
   │   └── tests/
   │       └── test-connection.yaml
   └── charts/                 # Subcharts (dependencies)
   

3. 应用 Chart.yaml 最佳实践

   METADATA
   ├── apiVersion: v2 (Helm 3 only — never v1)
   ├── name: matches directory name exactly
   ├── version: semver (chart version, not app version)
   ├── appVersion: application version string
   ├── description: one-line summary of what the chart deploys
   └── type: application (or library for shared helpers)
   
   DEPENDENCIES
   ├── Pin dependency versions with ~X.Y.Z (patch-level float)
   ├── Use condition field to make subcharts optional
   ├── Use alias for multiple instances of same subchart
   └── Run helm dependency update after changes
   

4. 生成带文档的 values.yaml

   • 每个值都带有行内注释，说明用途和类型
   • 默认值合理，适用于开发环境
   • 便于覆盖的结构（尽量扁平，仅在逻辑合理时才嵌套）
   • 不硬编码集群特定的值（镜像仓库、域名、存储类）

5. 验证

   python3 scripts/chart_analyzer.py mychart/
   helm lint mychart/
   helm template mychart/ --debug
   

/helm:review — Chart 分析

1. 检查 Chart 结构

   检查项	严重程度	修复方法
   缺少 _helpers.tpl	高	创建用于通用标签和选择器的 helpers
   没有 NOTES.txt	中	添加安装后说明
   没有 .helmignore	低	创建该文件，排除 .git、CI 文件和测试
   Chart.yaml 字段缺失	中	添加 description、appVersion、maintainers
   模板中存在硬编码值	高	提取到 values.yaml 并设置默认值

2. 检查模板质量

   检查项	严重程度	修复方法
   缺少标准标签	高	通过 _helpers.tpl 使用 app.kubernetes.io/* 标签
   没有资源 requests/limits	严重	在 values.yaml 中添加带默认值的 resources 部分
   镜像标签硬编码	高	使用 {{ .Values.image.repository }}:{{ .Values.image.tag }}
   没有 imagePullPolicy	中	默认设为 IfNotPresent，并可覆盖
   缺少存活/就绪探针	高	添加可配置路径和端口的探针
   没有 Pod 反亲和性	中	为实现高可用添加优先级反亲和性
   模板代码重复	中	提取为 _helpers.tpl 中的命名模板

3. 检查 values.yaml 质量

   python3 scripts/values_validator.py mychart/values.yaml
   

4. 生成审查报告

   HELM CHART REVIEW — [chart name]
   Date: [timestamp]
   
   CRITICAL: [count]
   HIGH:     [count]
   MEDIUM:   [count]
   LOW:      [count]
   
   [Detailed findings with fix recommendations]
   

/helm:security — 安全审计

1. Pod 安全审计

   检查项	严重程度	修复方法
   未设置 securityContext	Critical	添加 runAsNonRoot、readOnlyRootFilesystem
   以 root 身份运行	Critical	设置 runAsNonRoot: true、runAsUser: 1000
   根文件系统可写	High	设置 readOnlyRootFilesystem: true，并为 tmp 挂载 emptyDir
   保留所有 capabilities	High	删除 ALL，仅添加必要的特定 capabilities
   特权容器	Critical	设置 privileged: false，改用特定 capabilities
   未设置 seccomp 配置文件	Medium	设置 seccompProfile.type: RuntimeDefault
   allowPrivilegeEscalation 为 true	High	设置 allowPrivilegeEscalation: false

2. RBAC 审计

   检查项	严重程度	修复方法
   没有 ServiceAccount	Medium	创建专用 SA，不要使用 default
   automountServiceAccountToken 为 true	Medium	除非 Pod 需要访问 K8s API，否则设置为 false
   使用 ClusterRole 而非 Role	Medium	除非确实需要集群范围权限，否则使用命名空间级别的 Role
   通配符权限	Critical	使用特定的资源名称和动词
   完全没有 RBAC	Low	如果 Pod 不需要访问 K8s API，则可以接受

3. 网络与密钥审计

   检查项	严重程度	修复方法
   没有 NetworkPolicy	Medium	添加默认拒绝入站规则及明确的放行规则
   密钥位于 values.yaml 中	Critical	使用外部密钥运维工具（external secrets operator）或 sealed-secrets
   没有 PodDisruptionBudget	Medium	为高可用工作负载添加带 minAvailable 的 PDB
   hostNetwork: true	High	除非绝对必要（例如 CNI 插件），否则移除
   hostPID 或 hostIPC	Critical	在应用 Chart 中绝不使用

4. 生成安全报告

   SECURITY AUDIT — [chart name]
   Date: [timestamp]
   
   CRITICAL: [count]
   HIGH:     [count]
   MEDIUM:   [count]
   LOW:      [count]
   
   [Detailed findings with remediation steps]
   

---

工具

scripts/chart_analyzer.py

用于对 Helm Chart 目录进行静态分析的命令行工具。

功能：

• Chart 结构校验（必需文件、目录布局）
• 模板反模式检测（硬编码值、缺失标签、无资源限制）
• Chart.yaml 元数据检查
• 标准标签校验（app.kubernetes.io/*）
• 安全基线检查
• JSON 与文本输出

用法：

# Analyze a chart directory
python3 scripts/chart_analyzer.py mychart/

# JSON output
python3 scripts/chart_analyzer.py mychart/ --output json

# Security-focused analysis
python3 scripts/chart_analyzer.py mychart/ --security

scripts/values_validator.py

用于依据最佳实践校验 values.yaml 的命令行工具。

功能：

• 文档覆盖率（行内注释）
• 类型一致性检查
• 硬编码密钥检测
• 默认值质量分析
• 结构深度分析
• 命名约定校验
• JSON 与文本输出

用法：

# Validate values.yaml
python3 scripts/values_validator.py values.yaml

# JSON output
python3 scripts/values_validator.py values.yaml --output json

# Strict mode (fail on warnings)
python3 scripts/values_validator.py values.yaml --strict

---

模板模式

模式 1：标准标签（_helpers.tpl）

{{/*
Common labels for all resources.
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels (subset of common labels — must be immutable).
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

模式 2：条件性资源

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "mychart.fullname" . }}
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
  {{- with .Values.ingress.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  {{- if .Values.ingress.tls }}
  tls:
    {{- range .Values.ingress.tls }}
    - hosts:
        {{- range .hosts }}
        - {{ . | quote }}
        {{- end }}
      secretName: {{ .secretName }}
    {{- end }}
  {{- end }}
  rules:
    {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
          {{- range .paths }}
          - path: {{ .path }}
            pathType: {{ .pathType }}
            backend:
              service:
                name: {{ include "mychart.fullname" $ }}
                port:
                  number: {{ $.Values.service.port }}
          {{- end }}
    {{- end }}
{{- end }}

模式 3：安全加固的 Pod 规格

spec:
  serviceAccountName: {{ include "mychart.serviceAccountName" . }}
  automountServiceAccountToken: false
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 1000
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: {{ .Chart.Name }}
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL
      image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
      imagePullPolicy: {{ .Values.image.pullPolicy }}
      resources:
        {{- toYaml .Values.resources | nindent 8 }}
      volumeMounts:
        - name: tmp
          mountPath: /tmp
  volumes:
    - name: tmp
      emptyDir: {}

---

Values 设计原则

STRUCTURE
├── Flat over nested (image.tag > container.spec.image.tag)
├── Group by resource (service.*, ingress.*, resources.*)
├── Use enabled: true/false for optional resources
├── Document every key with inline YAML comments
└── Provide sensible development defaults

NAMING
├── camelCase for keys (replicaCount, not replica_count)
├── Boolean keys: use adjectives (enabled, required) not verbs
├── Nested keys: max 3 levels deep
└── Match upstream conventions (image.repository, image.tag, image.pullPolicy)

ANTI-PATTERNS
├── Hardcoded cluster URLs or domains
├── Secrets as default values
├── Empty strings where null is correct
├── Deeply nested structures (>3 levels)
├── Undocumented values
└── values.yaml that doesn't work without overrides

---

依赖管理

SUBCHARTS
├── Use Chart.yaml dependencies (not requirements.yaml — Helm 3)
├── Pin versions: version: ~15.x.x (patch float)
├── Use condition: to make optional: condition: postgresql.enabled
├── Use alias: for multiple instances of same chart
├── Override subchart values under subchart name key in values.yaml
└── Run helm dependency update before packaging

LIBRARY CHARTS
├── type: library in Chart.yaml — no templates directory
├── Export named templates only — no rendered resources
├── Use for shared labels, annotations, security contexts
└── Version independently from application charts

---

主动触发项

无需用户提示，直接标记以下问题：

• 没有 _helpers.tpl → 创建一个。每个 Chart 都需要标准标签和 fullname 辅助模板。
• 模板中硬编码镜像标签 → 提取到 values.yaml 中。标签必须可覆盖。
• 没有资源 requests/limits → 添加它们。没有限制的 Pod 可能耗尽节点资源。
• 以 root 身份运行 → 添加 securityContext。生产 Chart 不允许例外。
• 没有 NOTES.txt → 创建一个。用户需要安装后的使用说明。
• values.yaml 默认值中包含密钥 → 将其移除。改用占位符，并用注释说明如何提供密钥。
• 没有 liveness/readiness 探针 → 添加它们。Kubernetes 需要知道 Pod 是否健康。
• 缺少 app.kubernetes.io 标签 → 通过 _helpers.tpl 添加。这是正确跟踪资源所必需的。

---

安装

一行命令（适用于任意工具）

git clone https://github.com/alirezarezvani/claude-skills.git
cp -r claude-skills/engineering/helm-chart-builder ~/.claude/skills/

多工具安装

./scripts/convert.sh --skill helm-chart-builder --tool codex|gemini|cursor|windsurf|openclaw

OpenClaw

clawhub install cs-helm-chart-builder

---

相关 Skills

• senior-devops — 覆盖范围更广的 DevOps（CI/CD、IaC、监控）。二者互补：Chart 相关工作使用 helm-chart-builder，流水线和基础设施使用 senior-devops。
• docker-development — 容器构建。二者互补：docker-development 构建镜像，helm-chart-builder 将其部署到 Kubernetes。
• ci-cd-pipeline-builder — 流水线搭建。二者互补：helm-chart-builder 定义部署产物，ci-cd-pipeline-builder 负责其自动化交付。
• senior-security — 应用安全。二者互补：helm-chart-builder 负责 Kubernetes 层面的安全（RBAC、Pod 安全），senior-security 负责应用层面的威胁。