helm-validator

Helm Chart 验证与分析工具包

概述

此技能提供全面的 Helm Chart 验证与分析工作流，结合 Helm 原生 lint、模板渲染、YAML 验证、Schema 验证、CRD 文档查询和安全最佳实践检查。

重要：此验证器默认以只读方式运行。 它会分析 Chart 并提出改进建议。只有在用户明确要求应用修复时，才修改文件。

触发场景

在以下一个或多个常见场景中使用此技能：

• 用户要求验证、lint、检查、测试或排查 Helm Chart 问题
• Helm 模板渲染失败、lint 失败，或无法生成有效的 Kubernetes YAML
• 需要部署前质量门禁（Schema、dry-run、安全检查）
• 存在 CRD 资源，且需要根据文档验证其 spec 字段
• 用户需要按严重程度分类的验证报告及建议的修复措施

触发语句示例：

• “发布前验证此 Helm Chart”
• “为什么 helm template 会失败？”
• “检查此 Chart 是否存在 Kubernetes 和安全问题”

默认不在范围内：

• 新建 Chart 脚手架或大规模生成 Chart（使用 helm-generator）

职责边界

• 此技能负责验证并报告，不会擅自改写用户文件。
• 它可以提出具体补丁，但只有在用户明确要求修复时才能应用。
• 如果执行限制导致某个阶段无法运行，则必须继续执行可运行的阶段，并记录跳过原因。

执行模型

1. 按顺序运行各阶段（1 至 10）。
2. 阶段级失败后仍需继续，以收集完整问题；但如果渲染失败且没有任何清单，则不再继续。
3. 如果阶段 4 未生成任何清单，则将阶段 5 至 9 标记为受阻，并继续进行阶段 10 报告。
4. 将阶段 8 视为依赖环境的可选阶段；如果存在清单，则阶段 9 和阶段 10 为必需阶段。
5. 对于每个跳过的阶段，在最终摘要表中记录具体的工具或环境原因。

快速执行模式

模式 A：本地验证（无需集群）

bash scripts/setup_tools.sh
bash scripts/validate_chart_structure.sh <chart-directory>
helm lint <chart-directory> --strict
helm template <release-name> <chart-directory> --values <values-file> --debug --output-dir ./rendered
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec yamllint -c assets/.yamllint {} +
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec kubeconform -summary -verbose {} +

模式 B：完整验证（集群可用）

运行模式 A，并执行本文档中的阶段 8 dry-run 命令。

验证与测试工作流

按照以下顺序执行验证工作流。每个阶段都会发现不同类型的问题：

阶段 1：工具检查

开始验证前，确认所需工具已安装：

bash scripts/setup_tools.sh

所需工具：

• helm：Kubernetes 的 Helm 包管理器（v3+）
• yamllint：YAML 语法和风格 lint 工具
• kubeconform：支持 CRD 的 Kubernetes Schema 验证工具
• kubectl：集群 dry-run 测试工具（可选，但建议安装）

工具不可用或受环境限制时的回退策略：

条件	操作	阶段状态
缺少 helm	仅运行阶段 2，然后将阶段 3 至 9 报告为已跳过/受阻	⚠️ 警告
缺少 yamllint	如果有 yq，则使用它检查语法；否则跳过阶段 5	⚠️ 警告
缺少 kubeconform	跳过阶段 7，并依赖阶段 6 的 CRD/手动检查	⚠️ 警告
缺少 kubectl 或 kube-context	跳过阶段 8，继续执行其余阶段	⚠️ 警告
无法联网获取 CRD 文档	使用本地 CRD 清单和 kubeconform 输出，并标记文档查询未完成	⚠️ 警告

如果缺少工具，请根据 scripts/setup_tools.sh 的输出提供安装说明，并按照上述回退路径继续。

阶段 2：Helm Chart 结构验证

验证 Chart 是否遵循标准 Helm 目录结构：

bash scripts/validate_chart_structure.sh <chart-directory>

预期结构：

mychart/
  Chart.yaml          # Chart metadata (required)
  values.yaml         # Default values (required)
  values.schema.json  # JSON Schema for values validation (optional)
  templates/          # Template directory (required)
    _helpers.tpl      # Template helpers (recommended)
    NOTES.txt         # Post-install notes (recommended)
    *.yaml            # Kubernetes manifest templates
  charts/             # Chart dependencies (optional)
  crds/               # Custom Resource Definitions (optional)
  .helmignore         # Files to ignore during packaging (optional)

常见问题：

• 缺少必需文件（Chart.yaml、values.yaml、templates/）
• Chart.yaml 语法无效或缺少必需字段
• values.schema.json 格式错误
• 文件权限不正确

阶段 3：Helm Lint

运行 Helm 内置的检查器，以发现图表特有的问题：

helm lint <chart-directory> --strict

可选标志：

• --values <values-file>：使用指定的值进行测试
• --set key=value：覆盖指定的值
• --debug：显示详细的错误信息

常见问题：

• Chart.yaml 元数据无效
• 模板语法错误
• 缺少值或值未定义
• Kubernetes API 版本已弃用
• 违反图表最佳实践

自动修复方法：

• 对于模板错误，找出有问题的模板文件
• 向用户指出导致问题的具体行
• 提出修复补丁/差异
• 仅在用户明确要求时应用修复
• 应用修复后重新运行 helm lint

阶段 4：模板渲染

在本地渲染模板，以验证其是否生成有效的 YAML：

helm template <release-name> <chart-directory> \
  --values <values-file> \
  --debug \
  --output-dir ./rendered

可考虑的选项：

• --values values.yaml：使用指定的值文件
• --set key=value：覆盖单个值
• --show-only templates/deployment.yaml：渲染指定模板
• --validate：根据 Kubernetes OpenAPI 架构进行验证
• --include-crds：在渲染结果中包含 CRD
• --is-upgrade：模拟升级场景
• --kube-version 1.28.0：指定目标 Kubernetes 版本

常见问题：

• 模板语法错误（Go 模板问题）
• 变量或值未定义
• 类型不匹配（字符串与整数）
• 缺少必需的值
• 条件语句或循环中的逻辑错误
• 嵌套模板中的缩进不正确

对于模板错误：

• 找出模板文件和行号
• 检查 values.yaml 中是否正确定义了值
• 验证模板函数的用法（quote、required、default、include 等）
• 使用不同的值组合进行测试

阶段 5：YAML 语法验证

验证渲染后模板的 YAML 语法和格式：

find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec yamllint -c assets/.yamllint {} +

常见问题：

• 缩进错误（制表符与空格）
• 行尾空白
• 行长度超限
• 语法错误
• 重复键
• 文档起始/结束标记

自动修复方法：

• 对于简单问题（缩进、行尾空格），使用 Edit 工具提出修复
• 对于模板生成的问题，修复源模板，而非渲染后的输出
• 应用修复前，始终向用户展示将要更改的内容

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

在架构验证之前，检测图表是否包含或渲染了自定义资源定义：

# Check crds/ directory
if [ -d <chart-directory>/crds ]; then
  find <chart-directory>/crds -type f \( -name "*.yaml" -o -name "*.yml" \) \
    -exec bash scripts/detect_crd_wrapper.sh {} +
fi

# Check rendered templates
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec bash scripts/detect_crd_wrapper.sh {} +

脚本会输出包含资源信息的 JSON：

[
  {
    "kind": "Certificate",
    "apiVersion": "cert-manager.io/v1",
    "group": "cert-manager.io",
    "version": "v1",
    "isCRD": true,
    "name": "example-cert"
  }
]

对于检测到的每个 CRD：

1. 优先尝试使用 context7 MCP：

   Use mcp__context7__resolve-library-id with the CRD project name
   Example: "cert-manager" for cert-manager.io CRDs
            "prometheus-operator" for monitoring.coreos.com CRDs
            "istio" for networking.istio.io CRDs
   
   Then use mcp__context7__query-docs with:
   - libraryId from resolve step
   - query: The CRD kind and relevant features (e.g., "Certificate spec required fields")
   

2. 如果 Context7 失败，则回退到 web.search_query（网络搜索）：

   Search query pattern:
   "<kind>" "<group>" kubernetes CRD "<version>" documentation spec
   
   Example:
   "Certificate" "cert-manager.io" kubernetes CRD "v1" documentation spec
   "Prometheus" "monitoring.coreos.com" kubernetes CRD "v1" documentation spec
   

3. 提取关键信息：

   • spec 中的必需字段
   • 字段类型和验证规则
   • 文档中的示例
   • 特定版本的更改或弃用项
   • 常见配置模式

此步骤的重要性： CRD 使用自定义架构，而标准 Kubernetes 验证工具不包含这些架构。了解 CRD 的 spec 要求有助于避免验证错误，并确保资源配置正确。

阶段 7：架构验证

根据 Kubernetes 架构验证渲染后的模板：

find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec \
  kubeconform \
    -schema-location default \
    -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
    -summary \
    -verbose \
    {} +

可考虑的选项：

• 添加 -strict，以拒绝未知字段（生产环境推荐）
• 如果使用自定义/内部 CRD，添加 -ignore-missing-schemas
• 添加 -kubernetes-version 1.28.0，以根据特定的 K8s 版本进行验证
• 添加 -output json，以便进行编程处理

常见问题：

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

**对于 CRD：**如果 kubeconform 报告“no schema found”，这是预期情况。请使用阶段 6 的文档手动验证 spec 字段。

阶段 7 成功标准（明确）：

• ✅ 通过：kubeconform 以 0 退出，且未报告无效资源。
• ⚠️ 警告：仅剩 CRD 架构缺失问题，且已完成阶段 6 文档查阅/手动验证。
• ❌ 失败：存在任何非 CRD 架构违规、解析错误或未解决的必填字段/类型错误。

阶段 8：集群试运行（如可用）

如果已配置 kubectl 且可访问集群，请执行服务端试运行：

# Test installation
helm install <release-name> <chart-directory> \
  --dry-run=server \
  --debug \
  --values <values-file>

# Test upgrade
helm upgrade <release-name> <chart-directory> \
  --dry-run=server \
  --debug \
  --values <values-file>

如果 Helm 版本不支持 --dry-run=server，请使用 --dry-run，并说明仅执行了客户端 Helm 模拟。

此操作可发现：

• 准入控制器拒绝
• 策略违规（PSP、OPA、Kyverno 等）
• 资源配额违规
• 缺少命名空间
• ConfigMap/Secret 引用无效
• Webhook 验证问题
• 与现有资源冲突

如果无法执行试运行：

• 使用 kubectl 和渲染后的模板：kubectl apply --dry-run=server -f ./rendered/
• 如果无法访问集群，则跳过
• 说明已跳过集群特定验证

对于现有发布的更新：

helm diff upgrade <release-name> <chart-directory>

这会显示将要发生的更改，有助于发现意外修改。（需要 helm-diff 插件）

阶段 8 成功标准（明确）：

• ✅ 通过：试运行安装和升级命令以 0 退出，且没有准入/策略错误。
• ⚠️ 警告：由于 kubectl/集群上下文/访问不可用而跳过该阶段，或只能使用客户端回退方式。
• ❌ 失败：试运行命令因准入 Webhook、策略违规、命名空间/配额错误或引用错误而返回非零状态。

阶段 9：安全最佳实践检查（必须执行）

**重要：**此阶段必须执行。分析渲染后的模板是否符合安全最佳实践。

检查渲染后的 Deployment/Pod 模板：

1. 缺少 securityContext——查找未设置安全选项的 Pod/容器：

   # Check if pod-level securityContext exists
   spec:
     securityContext:
       runAsNonRoot: true
       runAsUser: 1000
       fsGroup: 2000
   

2. 缺少容器 securityContext——每个容器都应设置：

   securityContext:
     allowPrivilegeEscalation: false
     readOnlyRootFilesystem: true
     runAsNonRoot: true
     capabilities:
       drop:
         - ALL
   

3. 缺少资源限制/请求——检查：

   resources:
     limits:
       cpu: "100m"
       memory: "128Mi"
     requests:
       cpu: "100m"
       memory: "128Mi"
   

4. 镜像标签问题——如果使用 :latest 或未指定标签，则标记

5. 缺少探针——检查存活性/就绪性探针

**检查方法：**读取渲染后的 deployment YAML 文件，并使用 grep 搜索以下模式：

# Check for securityContext
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep -l "securityContext" {} +

# Check for resources
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep -l "resources:" {} +

# Check for latest tag
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep "image:.*:latest" {} +

阶段 10：最终报告（必须执行）

**重要：**即使所有验证均通过，也必须执行此阶段。你必须完成以下所有操作。

**默认情况下为只读。**除非用户明确要求应用修复，否则不要修改文件。

步骤 1：加载参考文件（存在警告时必须执行）

如果发现任何警告、错误或安全问题，你必须阅读：

Read references/helm_best_practices.md
Read references/k8s_best_practices.md

使用这些参考资料，为发现的每个问题提供背景信息和建议。

步骤 2：呈现验证摘要

始终呈现验证摘要，并使用表格显示：

• 已执行的每个验证阶段（阶段 1-9）
• 每个阶段的状态（✅ 通过、⚠️ 警告、❌ 失败）
• 每个阶段发现的问题数量

示例：

| Stage | Status | Issues |
|-------|--------|--------|
| 1. Tool Check | ✅ Passed | All tools available |
| 2. Structure | ⚠️ Warning | Missing: .helmignore, NOTES.txt |
| 3. Helm Lint | ✅ Passed | 0 errors |
| 4. Template Render | ✅ Passed | 5 templates rendered |
| 5. YAML Syntax | ✅ Passed | No yamllint errors |
| 6. CRD Detection | ✅ Passed | 1 CRD documented |
| 7. Schema Validation | ✅ Passed | All resources valid |
| 8. Dry-Run | ✅ Passed | No cluster errors |
| 9. Security Check | ⚠️ Warning | Missing securityContext |

第 3 步：对所有问题进行分类

按严重程度对发现的问题分组：

❌ 错误（必须修复）：

• 模板语法错误
• 缺少必填字段
• 架构验证失败
• Dry-run 失败

⚠️ 警告（应当修复）：

• 使用已弃用的 Kubernetes API
• 缺少 securityContext
• 缺少资源限制/请求
• 使用 :latest 镜像标签
• 缺少推荐文件（_helpers.tpl、.helmignore、NOTES.txt）

ℹ️ 信息（建议）：

• 缺少 values.schema.json
• 缺少 README.md
• 优化机会

第 4 步：列出建议的更改（不要应用）

对于每个问题，提供建议的修复方案，包括：

• 文件路径和行号（如适用）
• 更改前/后的代码块
• 说明推荐此更改的原因

示例格式：

## Proposed Changes

### 1. Add securityContext to Deployment
**File:** templates/deployment.yaml:25
**Severity:** ⚠️ Warning
**Reason:** Running containers as root is a security risk

**Current:**
```yaml
spec:
  containers:
    - name: app
      image: nginx:1.21

建议：

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 2000
  containers:
    - name: app
      image: nginx:1.21
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL

2. 添加 .helmignore 文件

文件： .helmignore（新文件） 严重程度： ⚠️ 警告 原因： 排除图表打包中不需要的文件

建议： 从 assets/.helmignore 复制

#### Step 5: Automation Opportunities

List all detected automation opportunities:
- If `_helpers.tpl` is missing → Recommend: `bash scripts/generate_helpers.sh <chart>`
- If `.helmignore` is missing → Recommend: Copy from `assets/.helmignore`
- If `values.schema.json` is missing → Recommend: Copy and customize from `assets/values.schema.json`
- If `NOTES.txt` is missing → Recommend: Create post-install notes template
- If `README.md` is missing → Recommend: Create chart documentation

#### Step 6: Final Summary

Provide a final summary:

验证摘要

图表： 状态： ⚠️ 发现警告（或 ✅ 可供部署）

发现的问题：

• 错误：X
• 警告：Y
• 信息：Z

建议的更改： 建议进行 N 项更改

后续步骤：

1. 查看上方建议的更改
2. 手动应用更改或使用 helm-generator 技能
3. 重新运行验证以确认修复结果

## Workflow Done Criteria

Validation is complete only when all of the following are true:
- A Stage 1 to Stage 10 status table is present with `✅ Passed`, `⚠️ Warning`, `❌ Failed`, or `⏭️ Skipped` for each stage.
- Every skipped stage includes a concrete tool or environment reason.
- Stage 7 and Stage 8 are evaluated against their explicit success criteria above.
- Severity totals are reported (`Errors`, `Warnings`, `Info`) with proposed remediation actions.
- Role boundary is respected: no file edits unless explicitly requested by the user.

## Helm Templating Automation & Best Practices

This section covers advanced Helm templating techniques, helper functions, and automation strategies.

### Template Helpers (`_helpers.tpl`)

Template helpers are reusable functions defined in `templates/_helpers.tpl`. They promote DRY principles and consistency.

**Standard helper patterns:**

1. **Chart name helper:**
```yaml
{{/*
Expand the name of the chart.
*/}}
{{- define "mychart.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

2. Fullname 辅助模板：

{{/*
Create a default fully qualified app name.
*/}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

3. 图表引用辅助模板：

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "mychart.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

4. 标准标签辅助模板：

{{/*
Common labels
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
{{ include "mychart.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

5. 选择器标签辅助模板：

{{/*
Selector labels
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

6. ServiceAccount 名称辅助模板：

{{/*
Create the name of the service account to use
*/}}
{{- define "mychart.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "mychart.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

何时创建辅助模板：

• 在多个模板中使用的值
• 重复出现的复杂逻辑
• 应保持一致的标签集
• 名称生成模式
• 有条件地包含资源

必备模板函数

请参考并使用以下 Helm 模板函数，以构建健壮的图表：

1. required - 强制要求提供值：

apiVersion: v1
kind: Service
metadata:
  name: {{ required "A valid service name is required!" .Values.service.name }}

2. default - 提供备用值：

replicas: {{ .Values.replicaCount | default 1 }}

3. quote - 安全地为字符串值加引号：

env:
  - name: DATABASE_HOST
    value: {{ .Values.database.host | quote }}

4. include - 通过管道使用辅助模板：

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

5. tpl - 将字符串作为模板渲染：

{{- tpl .Values.customConfig . }}

6. toYaml - 将对象转换为 YAML：

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

7. fromYaml - 解析 YAML 字符串：

{{- $config := .Values.configYaml | fromYaml }}

8. merge - 合并映射：

{{- $merged := merge .Values.override .Values.defaults }}

9. lookup - 查询集群资源（谨慎使用）：

{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
{{- if $secret }}
  # Secret exists, use it
{{- else }}
  # Create new secret
{{- end }}

高级模板模式

1. 有条件地创建资源：

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
# ... ingress definition
{{- end }}

2. 遍历列表：

{{- range .Values.extraEnvVars }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

3. 遍历映射：

{{- range $key, $value := .Values.configMap }}
{{ $key }}: {{ $value | quote }}
{{- end }}

4. 使用 With 块设置作用域：

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

5. 使用自定义上下文的命名模板：

{{- include "mychart.container" (dict "root" . "container" .Values.mainContainer) }}

Values 结构最佳实践

尽可能优先使用扁平结构：

# Good - Flat structure
serverName: nginx
serverPort: 80

# Acceptable - Nested structure for related settings
server:
  name: nginx
  port: 80
  replicas: 3

始终在 values.yaml 中提供默认值：

replicaCount: 1

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: "1.21.0"

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi

记录所有值：

# replicaCount is the number of pod replicas for the deployment
replicaCount: 1

# image configures the container image
image:
  # image.repository is the container image registry and name
  repository: nginx
  # image.tag overrides the image tag (default is chart appVersion)
  tag: "1.21.0"

模板注释和文档

使用 Helm 模板注释编写文档：

{{- /*
mychart.fullname generates the fullname for resources.
It supports nameOverride and fullnameOverride values.
Usage: {{ include "mychart.fullname" . }}
*/ -}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

使用 YAML 注释提供面向用户的说明：

# WARNING: Changing the storage class will not migrate existing data
storageClass: "standard"

空白字符管理

在模板指令中使用 - 去除空白字符：

{{- if .Values.enabled }}
  # Remove leading whitespace
{{- end }}

{{ .Values.name -}}
  # Remove trailing whitespace

良好的格式：

{{- if .Values.enabled }}
  key: value
{{- end }}

不良的格式：

{{if .Values.enabled}}
key: value
{{end}}

辅助模板模式参考

分析图表时，请找出使用辅助函数的机会：

1. 找出重复内容：

   • 多个资源使用相同的标签集
   • 重复的名称生成逻辑
   • 常见的条件模式

2. 建议的常见辅助模板模式：

   • 图表名称辅助模板（.name）
   • Fullname 辅助模板（.fullname）
   • 图表版本标签（.chart）
   • 常见标签（.labels）
   • 选择器标签（.selectorLabels）
   • ServiceAccount 名称（.serviceAccountName）

3. 建议使用辅助模板的情况：

   • 缺少 _helpers.tpl 文件
   • 模板之间存在重复代码模式
   • 标签用法不一致
   • 资源名称过长，需要截断

最佳实践参考

如需了解详细的 Helm 和 Kubernetes 最佳实践，请加载以下参考资料：

Read references/helm_best_practices.md
Read references/k8s_best_practices.md

这些参考资料包括：

• Chart 结构和元数据
• 模板约定和模式
• Values 文件组织方式
• 安全最佳实践
• 资源限制和请求
• 常见验证问题及修复方法

何时加载： 验证发现需要更多背景信息的问题时、实现新功能时，或用户询问最佳实践时。

使用 Chart 依赖项

当 Chart 有依赖项（位于 Chart.yaml 或 charts/ 目录中）时：

1. 更新依赖项：

helm dependency update <chart-directory>

2. 列出依赖项：

helm dependency list <chart-directory>

3. 验证依赖项：

   • 检查依赖项版本是否可用
   • 确认依赖项的 Values 配置是否正确限定作用域
   • 使用依赖项资源测试模板

4. 覆盖依赖项的 Values：

# values.yaml
postgresql:
  enabled: true
  postgresqlPassword: "secret"
  persistence:
    size: 10Gi

错误处理策略

工具不可用

• 运行 scripts/setup_tools.sh 检查工具是否可用
• 提供安装说明
• 跳过可选阶段，但记录跳过的内容
• 使用可用的工具继续操作

模板渲染错误

• 指明具体的模板文件和行号
• 检查 values.yaml 中是否定义了相应的 Values
• 确认模板函数语法正确
• 使用更简单的 Values 组合进行测试
• 使用 --debug 标志获取详细错误信息

集群访问问题

• 回退到客户端验证
• 使用渲染后的模板配合 kubectl
• 如果没有 kubectl 配置，则跳过集群验证
• 在验证报告中说明限制

未找到 CRD 文档

• 记录文档查找失败
• 尝试使用 kubeconform CRD 架构进行验证
• 建议手动检查 CRD：

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

验证阶段失败

• 即使某个阶段失败，也继续执行下一阶段
• 向用户展示结果之前，收集所有错误
• 优先修复 Helm lint 错误
• 然后修复模板错误
• 最后修复架构/验证错误

macOS 扩展属性问题

症状： 即使文件存在且可读取，Helm 仍报告“Chart.yaml file is missing”。

原因： 在 macOS 上，以编程方式创建的文件（通过 Write 工具、脚本或某些编辑器）可能带有扩展属性（例如 com.apple.provenance、com.apple.quarantine），从而干扰 Helm 对文件的检测。

诊断：

# Check for extended attributes
xattr /path/to/chart/Chart.yaml

# If attributes are present, you'll see output like:
# com.apple.provenance
# com.apple.quarantine

解决方案：

1. 移除扩展属性：

   # Remove all extended attributes from a file
   xattr -c /path/to/chart/Chart.yaml
   
   # Remove all extended attributes recursively from chart directory
   xattr -cr /path/to/chart/
   

2. 改用 Shell 命令创建文件：

   # Use cat with heredoc instead of direct file writes
   cat > Chart.yaml << 'EOF'
   apiVersion: v2
   name: mychart
   version: 0.1.0
   EOF
   

3. 从 Helm 创建的 Chart 复制：

   # Create a fresh chart and copy structure
   helm create temp-chart
   cp -r temp-chart/* /path/to/your/chart/
   rm -rf temp-chart
   

预防： 在 macOS 上创建新的 Chart 文件时，最好以 helm create 创建的内容为基础，或使用 Shell heredoc（cat > file << 'EOF'），而不是直接使用文件创建工具。

沟通指南

展示验证结果和修复方案时：

1. 表达清晰、简洁，说明发现了什么
2. 解释问题的影响（例如：“这会导致 Pod 创建失败”）
3. 适时提供 Helm 最佳实践相关背景
4. 将相关问题归类（例如，将所有缺失的 helper 问题归在一起）
5. 尽可能提供文件:行号引用
6. 说明自动修复的置信度（高置信度 = 语法修改，低置信度 = 逻辑修改）
7. 提出修复方案后始终提供摘要（明确要求应用修复时，应用后也要提供摘要），包括：
   • 修改了什么以及原因
   • 每项修复对应的文件和行号引用
   • 已解决问题的总数
   • 最终验证状态
   • 仍存在的警告或建议

版本兼容性

始终考虑 Kubernetes 和 Helm 版本兼容性：

• 检查是否使用了已弃用的 Kubernetes API
• 确保 Helm Chart 的 apiVersion 为 v2（适用于 Helm 3+）
• 对于 CRD，确保 apiVersion 与集群中的版本一致
• 使用 kubectl api-versions 列出可用的 API 版本
• 在适用时参考特定版本的文档
• 如有需要，在 Chart.yaml 中设置 kubeVersion 约束

Chart 测试

如需全面测试，请使用 Helm 测试资源：

1. 创建测试资源：

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "mychart.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
    - name: wget
      image: busybox
      command: ['wget']
      args: ['{{ include "mychart.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

2. 运行测试：

helm test <release-name>

自动化机会参考

在第 10 阶段（最终报告）中，在摘要里列出所有检测到的自动化机会。

不要向用户提问或修改文件。只需列出建议。

需要检测并列出的自动化机会：

缺失项	建议
_helpers.tpl	运行：bash scripts/generate_helpers.sh <chart>
.helmignore	从以下位置复制：assets/.helmignore
values.schema.json	从以下位置复制并自定义：assets/values.schema.json
NOTES.txt	创建安装后说明模板
README.md	创建 Chart 文档
重复模式	提取为辅助函数

发现问题时应包含的安全建议：

问题	建议
缺少 pod securityContext	添加 runAsNonRoot: true、runAsUser: 1000、fsGroup: 2000
缺少 container securityContext	添加 allowPrivilegeEscalation: false、readOnlyRootFilesystem: true、capabilities.drop: [ALL]
缺少资源限制	添加 CPU/内存限制和请求
使用 :latest 标签	固定为特定的镜像版本
缺少探针	添加存活探针和就绪探针

模板改进建议：

问题	建议
使用 template 而不是 include	替换为 include，以支持管道
缺少 nindent	添加 nindent，以确保 YAML 缩进正确
没有默认值	为可选值添加 default 函数
缺少 required 函数	为关键值添加 required 函数

资源

scripts/

setup_tools.sh

• 检查必需的验证工具（helm、yamllint、kubeconform、kubectl）
• 为缺失的工具提供安装说明
• 验证已安装工具的版本
• 用法：bash scripts/setup_tools.sh

validate_chart_structure.sh

• 验证 Helm Chart 目录结构
• 检查必需文件（Chart.yaml、values.yaml、templates/）
• 验证文件格式和语法
• 用法：bash scripts/validate_chart_structure.sh <chart-directory>

detect_crd_wrapper.sh

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

detect_crd.py

• 解析 YAML 文件以识别 Custom Resource Definition
• 提取 kind、apiVersion、group 和 version 信息
• 输出 JSON，供程序处理
• 需要 PyYAML（由包装脚本自动处理）
• 可直接调用：python3 scripts/detect_crd.py <file.yaml> [file2.yaml ...]

generate_helpers.sh

• 为 Chart 生成标准 Helm 辅助模板（_helpers.tpl）
• 创建 fullname、标签和选择器辅助模板
• 用法：bash scripts/generate_helpers.sh <chart-directory>

references/

helm_best_practices.md

• Helm Chart 最佳实践综合指南
• 涵盖模板模式、辅助函数和值结构
• 常见验证问题及其修复方法
• 安全和性能建议
• 提供 Helm 特定问题的上下文时加载

k8s_best_practices.md

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

template_functions.md

• Helm 模板函数参考指南
• 所有内置函数的示例
• Sprig 函数库参考
• 自定义函数模式
• 实现复杂模板时加载

assets/

.helmignore

• 用于在打包时排除文件的标准 .helmignore 文件
• 已预先配置常见模式

.yamllint

• 已预先配置适用于 Kubernetes YAML 的 yamllint 规则
• 遵循 Kubernetes 规范（2 个空格缩进、行长等）
• 可按项目自定义
• 用法：yamllint -c assets/.yamllint <file.yaml>

values.schema.json

• 用于校验 values 的 JSON Schema 示例
• 可复制并针对特定 chart 自定义
• 提供类型安全和校验