📚 课程目录第2章 Chart结构详解

2. Chart结构详解：Chart目录结构规范、Chart.yaml文件配置、values.yaml设计原则、templates目录组织模式

Helm Chart 是 Kubernetes 应用打包、部署和管理的核心单元。理解 Chart 的标准目录结构、元数据配置、参数设计原则以及模板组织方式，是编写可维护、可复用 Chart 的基础。本章将逐一拆解这四个关键维度。

2.1 Chart目录结构规范

一个标准的 Helm Chart 遵循固定的目录布局。Helm 在打包和安装时会根据此结构查找文件。以下是最小推荐结构及每个文件/目录的职责：

路径	是否必需	说明
`Chart.yaml`	是	Chart 的元数据文件，包含名称、版本、描述等。
`values.yaml`	是	默认配置值文件，用户可通过 `--set` 或自定义 values 文件覆盖。
`templates/`	是	存放 Go 模板文件，渲染后生成 Kubernetes 资源清单。
`charts/`	否	存放子 Chart（依赖），Helm 会自动管理。
`crds/`	否	存放自定义资源定义（CRD），Helm 会在安装时优先应用。
`README.md`	推荐	Chart 的使用说明、参数表格、注意事项。
`NOTES.txt`	否	安装成功后打印给用户的提示信息（如访问地址、默认密码）。
`.helmignore`	否	打包时忽略的文件模式列表，类似 `.gitignore`。

工程建议：即使 charts/ 和 crds/ 不是必需目录，也建议在 Chart 根目录保留它们（即使为空），以表明该 Chart 的设计意图，方便后续扩展。

以下 SVG 展示了标准 Chart 目录的树形结构及各节点的核心职责：

2.2 Chart.yaml文件配置

Chart.yaml 是 Chart 的“身份证”，Helm 通过它识别 Chart 的身份、版本和依赖关系。以下是一个生产级配置示例：

apiVersion: v2
name: my-application
description: A production-grade web application stack
type: application
version: 1.2.0
appVersion: "3.1.5"
kubeVersion: ">=1.21.0-0"
keywords:
  - web
  - api
  - microservice
home: https://github.com/myorg/my-application
sources:
  - https://github.com/myorg/my-application
maintainers:
  - name: DevOps Team
    email: devops@myorg.com
    url: https://myorg.com
dependencies:
  - name: postgresql
    version: "12.x"
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
    alias: db
icon: https://myorg.com/icon.svg
annotations:
  category: Infrastructure
  support: production

字段	类型	说明	工程要点
`apiVersion`	string	Chart API 版本，v2 是当前标准	必须为 `v2`，v1 已废弃
`name`	string	Chart 名称	与目录名保持一致
`version`	string	Chart 语义化版本	遵循 SemVer 2.0，每次变更需递增
`appVersion`	string	应用版本	与 Chart 版本解耦，可独立更新
`kubeVersion`	string	兼容的 Kubernetes 版本约束	使用 SemVer 范围，如 `>=1.21.0-0`
`dependencies`	list	子 Chart 依赖列表	使用 `condition` 控制开关，`alias` 避免命名冲突
`annotations`	map	自定义元数据	用于 CI/CD 分类、审批流程标记

版本管理陷阱：Chart 的 version 与 appVersion 是两个独立维度。每次修改模板或 values 默认值时，必须递增 version；而 appVersion 仅当上游容器镜像版本变化时才更新。混淆两者会导致 Helm 仓库中的 Chart 版本混乱。

2.3 values.yaml设计原则

values.yaml 是 Chart 的配置接口，其设计质量直接决定 Chart 的易用性和可维护性。以下是经过生产验证的五大设计原则：

扁平化优先，嵌套有度：避免超过 3 层嵌套，过深的路径会导致 --set 覆盖时语法冗长且易错。
提供合理的默认值：所有参数必须有默认值，且默认值应能直接启动一个最小可用实例。
类型明确，注释完整：每个参数标注预期类型（string/int/bool），并给出取值范围或示例。
使用 enabled 开关控制可选组件：对于可插拔功能（如 ServiceMonitor、Ingress），统一使用 enabled: true/false 控制。
敏感信息不硬编码：密码、等敏感值应留空或使用占位符，引导用户通过 --set 或外部 Secret 注入。

以下是一个符合上述原则的 values.yaml 片段：

# -- 副本数，生产环境建议至少 3
replicaCount: 1

image:
  repository: nginx
  # -- 镜像标签，默认使用 Chart.yaml 中的 appVersion
  tag: ""
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80
  # -- 节点端口，仅当 type=NodePort 时生效
  nodePort: ""

ingress:
  enabled: false
  className: nginx
  hosts:
    - host: my-app.local
      paths:
        - path: /
          pathType: Prefix

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

# -- 数据库连接配置，生产环境建议通过外部 Secret 注入
database:
  host: ""
  port: 5432
  user: app_user
  password: ""

设计检查清单：
每个参数是否都有注释说明其用途？
默认值是否能让 Chart 在 minikube 或开发集群中直接安装成功？
是否所有 enabled 开关都对应 templates 中的 {{- if .Values.xxx.enabled }} 条件块？
敏感字段是否留空或使用 "" 占位？

2.4 templates目录组织模式

templates/ 目录是 Chart 的核心逻辑所在。合理的组织模式能显著提升模板的可读性和可测试性。以下是推荐的工程化组织方式：

文件/目录	职责	示例
`deployment.yaml`	工作负载定义	Deployment / StatefulSet / DaemonSet
`service.yaml`	网络暴露	Service / Ingress
`configmap.yaml`	非敏感配置	ConfigMap / 环境变量注入
`secret.yaml`	敏感配置	Secret（值来自 values 或外部）
`hpa.yaml`	自动扩缩容	HorizontalPodAutoscaler
`pvc.yaml`	持久化存储	PersistentVolumeClaim
`serviceaccount.yaml`	RBAC 权限	ServiceAccount / Role / RoleBinding
`_helpers.tpl`	模板辅助函数	命名规范、标签定义、条件判断宏
`tests/`	测试 Pod 定义	用于 `helm test` 的 Pod YAML

以下 SVG 展示了 templates 目录中文件之间的数据流与渲染关系：

2.5 模板组织最佳实践

命名规范：模板文件名使用小写字母 + 连字符（如 service-monitor.yaml），与 Kubernetes 资源命名风格一致。
单一职责：每个模板文件只生成一种 Kubernetes 资源类型。不要将 Deployment 和 Service 写在同一个文件中。
善用 _helpers.tpl：将重复的命名规则、标签、注解定义提取到 _helpers.tpl 中，通过 {{ include "my-chart.fullname" . }} 复用。
条件包含：对于可选资源（如 Ingress、ServiceMonitor），使用 {{- if .Values.ingress.enabled }} 包裹整个资源定义。
测试文件隔离：将 helm test 使用的 Pod 定义放在 templates/tests/ 子目录中，避免与主资源混淆。

生产级模板组织示例（推荐）：

templates/
├── _helpers.tpl          # 命名、标签、条件宏
├── deployment.yaml       # 主工作负载
├── service.yaml          # 服务暴露
├── configmap.yaml        # 应用配置
├── secret.yaml           # 敏感信息
├── hpa.yaml              # 自动扩缩容
├── pvc.yaml              # 持久化存储
├── ingress.yaml          # 入口路由（条件包含）
├── serviceaccount.yaml   # 服务账户与 RBAC
├── servicemonitor.yaml   # 监控指标采集（条件包含）
└── tests/
    └── test-connection.yaml  # 连接测试 Pod