3. Chart 目录结构详解：Chart.yaml、values.yaml、templates/、charts/、crds/、README 等文件的作用与规范

一个标准 Helm Chart 的目录结构是 Helm 打包、发布和版本管理的基石。理解每个文件和目录的职责，是进行 Chart 治理的第一步。本章将逐层拆解标准 Chart 目录，并给出生产级规范。

mychart/
├── Chart.yaml          # Chart 元数据（必选）
├── values.yaml         # 默认配置值（必选）
├── values.schema.json  # values 的 JSON Schema 校验（可选）
├── templates/          # Kubernetes 资源模板（必选）
│   ├── _helpers.tpl    # 模板辅助函数（可选）
│   ├── NOTES.txt       # 安装后提示信息（可选）
│   └── *.yaml          # 各类资源模板
├── charts/             # 子 Chart 依赖（可选）
├── crds/               # 自定义资源定义 CRD（可选）
├── README.md           # 使用说明（推荐必选）
└── .helmignore         # 打包忽略规则（可选）

3.1 Chart.yaml：Chart 的身份证

Chart.yaml 是每个 Chart 必须存在的核心文件，定义了 Chart 的名称、版本、描述等元数据。Helm 通过该文件识别 Chart 身份并执行版本管理。

# 标准 Chart.yaml 示例
apiVersion: v2
name: my-nginx
description: A Helm chart for deploying Nginx on Kubernetes
type: application
version: 1.2.3
appVersion: 1.25.0
home: https://github.com/myteam/my-nginx
sources:
  - https://github.com/myteam/my-nginx
maintainers:
  - name: DevOps Team
    email: devops@example.com
    url: https://devops.example.com
keywords:
  - nginx
  - web
  - reverse-proxy
annotations:
  category: Infrastructure
  team: platform

3.2 values.yaml：配置的默认值

values.yaml 是 Chart 的默认配置入口，定义了所有可配置参数的默认值。用户可以通过 --values 或 --set 覆盖这些值。

values.yaml 编写规范：

• 扁平化优先：避免过深嵌套，建议不超过 3 层
• 命名一致：使用驼峰命名（camelCase）或全小写连字符
• 注释完整：每个参数上方添加注释说明用途和默认值含义
• 类型明确：字符串、数字、布尔值、列表、字典类型清晰区分
• 提供示例：复杂结构给出完整示例值

# values.yaml 规范示例
# -- 副本数量
replicaCount: 3

# -- 容器镜像配置
image:
  repository: nginx
  tag: 1.25.0
  pullPolicy: IfNotPresent

# -- 服务配置
service:
  type: ClusterIP
  port: 80
  targetPort: 8080

# -- 资源限制
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

# -- 环境变量列表
env:
  - name: LOG_LEVEL
    value: info
  - name: NODE_ENV
    value: production

# -- 持久化存储配置
persistence:
  enabled: false
  storageClass: ""
  accessMode: ReadWriteOnce
  size: 10Gi

3.3 templates/：Kubernetes 资源模板

templates/ 目录是 Chart 的核心，包含所有 Kubernetes 资源的 Go 模板文件。Helm 在渲染时会将这些模板与 values.yaml 结合，生成最终的 YAML 清单。

templates/ 目录治理要点：

• 单一职责：每个模板文件只定义一个 Kubernetes 资源
• 复用辅助函数：将重复逻辑提取到 _helpers.tpl 中
• 避免硬编码：所有可变值通过 .Values 引用
• 使用命名模板：通过 define 和 template 实现模块化
• 添加资源标签：统一使用 helm.sh/chart、app.kubernetes.io/name 等标准标签

{{- /* templates/deployment.yaml 示例 */ -}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-nginx.fullname" . }}
  labels:
    {{- include "my-nginx.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "my-nginx.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-nginx.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.service.targetPort }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

3.4 charts/：子 Chart 依赖管理

charts/ 目录存放 Chart 的依赖子 Chart。有两种方式管理依赖：

• 手动放置：将子 Chart 打包后的 .tgz 文件放入该目录
• 自动管理：在 Chart.yaml 的 dependencies 中声明，通过 helm dependency update 自动下载

3.5 crds/：自定义资源定义

crds/ 目录用于存放 Chart 所需的 CustomResourceDefinition（CRD）资源。Helm 在处理 CRD 时有特殊行为：

• 安装时先安装 CRD：在渲染 templates/ 之前，Helm 会先安装 crds/ 目录中的 CRD
• 不参与模板渲染：crds/ 中的文件不会被 Go 模板引擎处理，必须是纯 YAML
• 不参与升级和回滚：CRD 安装后，helm upgrade 和 helm rollback 不会修改或删除 CRD
• 不参与删除：helm uninstall 不会删除已安装的 CRD

3.6 README.md：Chart 的使用说明书

虽然 README.md 不是 Helm 的强制要求，但在生产级 Chart 治理中，它是推荐必选的文件。良好的 README 能显著降低使用者的学习成本。

README.md 标准结构：

3.7 其他辅助文件

values.schema.json： 用于对 values.yaml 进行 JSON Schema 校验。Helm 在安装或升级时会自动校验用户提供的 values 是否符合 schema 定义，提前发现配置错误。

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["replicaCount", "image"],
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "image": {
      "type": "object",
      "required": ["repository", "tag"],
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$" }
      }
    }
  }
}

.helmignore： 类似于 .gitignore，在 helm package 打包时忽略指定文件或目录，避免将敏感文件或本地配置打包进 Chart。

# .helmignore 示例
.git/
.gitignore
*.md
test/
ci/
*.log
.secrets/

3.8 目录结构全景图

下图展示了标准 Helm Chart 目录结构及其各组件之间的数据流关系：

3.9 目录结构治理清单

在 Chart 发布前，建议使用以下清单逐项检查目录结构完整性：