📚 课程目录第3章 Helm Hook机制详解

3. Helm Hook 机制详解：Hook 类型、权重与删除策略

Helm Hook 是 Chart 在资源生命周期关键节点插入自定义操作的机制。它允许你在安装、升级、删除或回滚等动作的前后执行特定 Job 或 Pod，从而实现数据库迁移、配置预热、健康检查、资源清理等高级交付场景。

核心价值：Hook 将“应用交付”从简单的资源声明扩展为可编排的交付流程，是构建灰度发布、蓝绿部署、准入检查等复杂策略的基础设施。

3.1 Hook 类型全景

Helm 定义了 8 种标准 Hook 类型，覆盖了 Release 生命周期的所有关键阶段。下表列出了每种 Hook 的触发时机与典型用途：

Hook 类型	触发时机	典型用途
`pre-install`	模板渲染后、资源创建前	数据库初始化、配置生成、前置依赖检查
`post-install`	所有资源创建成功后	数据填充、缓存预热、首次启动通知
`pre-upgrade`	升级模板渲染后、资源更新前	旧版本数据备份、Schema 迁移、兼容性检查
`post-upgrade`	所有资源更新成功后	新版本验证、缓存刷新、监控告警重置
`pre-delete`	删除操作执行前	资源快照、日志归档、外部系统解注册
`post-delete`	所有资源删除成功后	清理临时数据、发送删除通知
`pre-rollback`	回滚模板渲染后、资源回滚前	当前版本快照、回滚前置检查
`post-rollback`	所有资源回滚成功后	回滚后验证、恢复通知

  关键理解：Hook 资源本身 不参与 Release 的常规资源管理。它们不会被 helm upgrade 更新，也不会被 helm rollback 回滚。Hook 的生命周期完全由 Helm 根据 Hook 类型和权重独立调度。

3.2 Hook 权重与执行顺序

当同一个 Release 操作（如 install）触发了多个同类型 Hook（例如两个 pre-install Job）时，Helm 通过 权重（Weight） 控制执行顺序。

权重范围：支持负整数、零和正整数，默认值为 0。
排序规则：按权重 从小到大 升序执行。权重相同的 Hook 按资源名称字母序执行。
阻塞特性：每个 Hook Job 必须运行到 Completed 状态后，Helm 才会启动下一个同类型 Hook。

以下是一个带权重的 Hook 定义示例：

apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ .Release.Name }}-db-migrate"
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migrate
        image: myapp/migrate:1.0
        command: ["/bin/sh", "-c", "echo 'Running pre-upgrade migration...'"]

权重设计建议：将前置检查类 Hook 设为负权重（如 -10），确保它们在数据迁移或资源准备之前执行。将清理或通知类 Hook 设为正权重（如 5），让核心操作优先完成。

3.3 Hook 删除策略

Hook Job 执行完成后，其资源（Pod、Job）默认会保留在集群中，以便调试。通过 helm.sh/hook-delete-policy 注解可以控制何时自动清理这些资源。

删除策略值	行为描述
`before-hook-creation`	在创建新 Hook 资源前，删除同名的旧 Hook 资源。适用于升级场景，避免残留。
`hook-succeeded`	Hook Job 成功完成后立即删除其资源。适用于一次性迁移任务。
`hook-failed`	Hook Job 失败后保留资源，供排查问题。通常与 `hook-succeeded` 组合使用。

常见的组合策略：

生产环境推荐：before-hook-creation,hook-succeeded —— 确保每次执行都是全新的 Job，且成功后自动清理。
调试环境推荐：before-hook-creation —— 保留所有执行记录，方便查看日志。
幂等迁移任务：hook-succeeded —— 只保留失败记录，成功即清理。

3.4 Hook 生命周期流程

下图展示了 helm upgrade 操作中，Hook 与常规资源之间的完整交互流程：

3.5 实战：Hook 组合模式

在实际交付流程中，通常将多个 Hook 类型组合使用，形成完整的交付流水线。以下是一个典型的灰度发布 Hook 组合：

阶段	Hook 类型	权重	执行内容	删除策略
前置检查	`pre-install`	-10	检查集群资源配额、Secret 是否存在	`before-hook-creation,hook-succeeded`
数据迁移	`pre-upgrade`	0	执行数据库 Schema 迁移脚本	`before-hook-creation,hook-succeeded`
灰度验证	`post-upgrade`	0	调用灰度验证 API，检查新版本健康状态	`hook-succeeded`
回滚快照	`pre-rollback`	-5	备份当前 ConfigMap 和数据库状态	`before-hook-creation`
清理通知	`post-delete`	5	发送 Release 删除通知到监控系统	`hook-succeeded`

  最佳实践：始终为 Hook Job 设置 restartPolicy: Never，避免 Pod 无限重启。对于关键迁移任务，建议在 Job 内部实现幂等逻辑，确保多次执行不会产生副作用。

3.6 常见陷阱与避坑指南

Hook 资源残留：未设置 hook-delete-policy 会导致大量已完成 Job 堆积，占用集群资源。生产环境务必显式声明删除策略。
权重冲突：多个 Chart 依赖同一个 Hook 类型时，权重可能重叠。建议团队内部约定权重区间（如 -100~-50 留给基础设施检查，-49~0 留给数据操作）。
Hook 超时：Helm 默认等待 Hook Job 完成的时间为 300 秒。长时间运行的迁移任务需要设置 --timeout 参数。
回滚时的 Hook 行为：helm rollback 会触发 pre-rollback 和 post-rollback，但不会触发 pre-upgrade 或 post-upgrade。迁移脚本需要为回滚场景单独设计。

调试技巧：使用 helm get hooks <release-name> 查看当前 Release 关联的所有 Hook 资源及其状态。使用 kubectl logs job/<hook-job-name> 查看 Hook Job 的执行日志。