📚 课程目录第2章 Helm基础回顾

2. Helm 基础回顾：Chart 结构、模板引擎、Values 管理、依赖管理、Hooks 与生命周期

在深入 Argo CD 与集群模板蓝图之前，必须牢固掌握 Helm 的核心机制。Helm 是 Kubernetes 的包管理工具，它将应用定义、配置与生命周期管理封装为 Chart。本章将系统梳理 Helm 的六大核心模块，为后续的压测沙盘与容量预测奠定基础。

2.1 Chart 目录结构与核心文件

一个标准的 Helm Chart 遵循固定的目录布局，Argo CD 在同步时会解析此结构以生成 Kubernetes 资源。

路径 / 文件	用途	是否必需
`Chart.yaml`	Chart 元数据：名称、版本、API 版本、描述、依赖声明	是
`values.yaml`	默认配置值，供模板引擎渲染时引用	是
`templates/`	Go 模板文件目录，渲染后生成 Kubernetes 清单	是
`charts/`	子 Chart 或依赖 Chart 的打包文件（`.tgz`）	否
`crds/`	自定义资源定义（CRD），在模板渲染前安装	否
`templates/NOTES.txt`	安装成功后向用户显示的说明文本	否
`templates/_helpers.tpl`	模板辅助函数定义，可被其他模板引用	否

关键点： Argo CD 在同步 Helm Chart 时，会先读取 Chart.yaml 获取依赖信息，然后执行 helm dependency update 拉取子 Chart，最后渲染 templates/ 目录下的所有模板文件。

2.2 模板引擎与 Values 管理

Helm 使用 Go 模板引擎将 values.yaml 中的配置注入到 Kubernetes 资源定义中。模板语法包括变量引用、控制结构（if/else、range）和管道函数。

# values.yaml 示例
replicaCount: 3
image:
  repository: nginx
  tag: "1.25"
service:
  type: ClusterIP
  port: 80
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"
  requests:
    cpu: "250m"
    memory: "256Mi"

# templates/deployment.yaml 模板示例
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-{{ .Chart.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Chart.Name }}
  template:
    metadata:
      labels:
        app: {{ .Chart.Name }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        resources:
          {{- toYaml .Values.resources | nindent 10 }}

最佳实践： 在 Argo CD 中，可以通过 values 字段或 helm.values 参数覆盖默认 Values。对于多环境（开发/测试/生产），建议使用独立的 values-{env}.yaml 文件，并通过 Argo CD Application 的 source.helm.valueFiles 引用。

2.3 依赖管理：子 Chart 与条件加载

Helm 支持通过 Chart.yaml 中的 dependencies 字段声明依赖。Argo CD 在部署时会自动解析并拉取这些依赖。

# Chart.yaml 依赖声明示例
dependencies:
  - name: redis
    version: "17.3.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled
    tags:
      - cache
  - name: postgresql
    version: "12.1.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled

依赖管理的关键机制包括：

条件加载：通过 condition 字段控制子 Chart 是否启用，避免资源浪费。
标签分组：使用 tags 字段对依赖进行逻辑分组，便于批量启用或禁用。
子 Chart 覆盖：父 Chart 的 Values 可以被子 Chart 的 Values 覆盖，形成层级配置。

注意： 在 Argo CD 中，如果依赖 Chart 存储在私有仓库，需要在 Application 的 source.helm.repositories 中配置认证信息，否则同步会失败。

2.4 Hooks 与生命周期管理

Helm Hooks 允许在 Chart 生命周期的特定节点执行自定义操作，例如数据库迁移、预检查或清理任务。Hooks 通过 Kubernetes Job 或 Pod 实现，并由 Helm 管理其执行顺序。

Hook 名称	触发时机	典型用途
`pre-install`	在模板渲染前、资源创建前执行	数据库初始化、配置验证
`post-install`	在所有资源创建成功后执行	数据填充、通知发送
`pre-upgrade`	在升级操作开始前执行	备份旧数据、迁移检查
`post-upgrade`	在升级操作成功后执行	验证新版本、清理临时资源
`pre-delete`	在删除操作开始前执行	释放外部资源、记录日志
`post-delete`	在删除操作成功后执行	清理残留、通知下游
`test`	通过 `helm test` 命令触发	集成测试、健康检查

# templates/pre-install-migration.yaml 示例
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-migration
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migration
        image: "{{ .Values.migration.image }}"
        command: ["/bin/sh", "-c", "echo 'Running migration...'"]

生命周期权重： 通过 helm.sh/hook-weight 注解控制同一 Hook 阶段内多个 Job 的执行顺序（数值越小越先执行）。helm.sh/hook-delete-policy 控制 Job 资源的清理策略，避免残留。

2.5 Helm 生命周期与 Argo CD 集成流程

下图展示了 Helm Chart 从构建到在 Argo CD 中部署的完整生命周期，以及 Hooks 的介入点。

2.6 核心概念对比：Helm 与 Argo CD 的职责边界

理解 Helm 与 Argo CD 的职责划分，有助于设计高效的交付流水线。

维度	Helm	Argo CD
核心职责	模板化、打包、版本管理	持续同步、状态对比、自动修复
配置来源	`values.yaml` + 命令行覆盖	Git 仓库中的 Chart 目录 + 额外 Values 文件
生命周期	install / upgrade / rollback / delete	sync / refresh / prune / self-heal
依赖管理	本地 `charts/` 或远程仓库	自动执行 `helm dependency build`
Hooks 支持	原生支持，通过 Job 实现	尊重 Helm Hooks，但需注意同步策略
多环境管理	通过不同 Values 文件实现	通过 Application 的 `targetRevision` 和 `helm.values` 实现

实践建议： 在 Argo CD 中，推荐将 Helm Chart 视为“模板蓝图”，而将 Values 视为“环境配置”。Argo CD 负责从 Git 拉取蓝图并注入环境配置，实现“一次构建，多次部署”。

2.7 常见陷阱与避坑指南

Hooks 资源残留：未设置 helm.sh/hook-delete-policy 会导致 Job 资源堆积，影响集群性能。建议设置为 before-hook-creation 或 hook-succeeded。
依赖版本锁定：在 Chart.yaml 中使用精确版本号（如 17.3.0），避免使用 ^17.0.0 导致意外升级。
Values 覆盖层级：Argo CD 中 Values 覆盖优先级：Application 参数 > 文件覆盖 > 默认 values.yaml。注意避免意外覆盖关键配置。
模板调试：使用 helm template --debug 或 helm install --dry-run --debug 在本地验证模板输出，减少 Argo CD 同步失败。

关键提醒： 在压测沙盘场景中，Hooks 中的 Job 可能消耗大量资源（如数据库迁移）。务必为 Hooks Job 设置资源限制（resources.limits），避免影响压测结果。