---
tags: [helm, kubernetes, templating, kustomize, devops]
create time: 2026-05-17 10:00
---

# Helm 模板管理

## 概述

本文档系统讲解 Helm Chart 的编写与管理实践。内容覆盖：Chart 骨架、values.yaml 参数化、Go 模板语法、多环境值覆盖、Chart 依赖管理、Hooks 机制，以及与 ArgoCD 的集成方式。架构决策参见 [[../03-CICD与GitOps]]。

## 为什么需要 Helm？

> [!question] 每个服务几十个 YAML 文件，怎么管理？
>
> 一个典型的 `order-service` 部署包含：Deployment、Service、Ingress、ConfigMap、HPA、NetworkPolicy、PDB……当你有 50 个服务，每个都要维护这么一堆模板——**这是重复劳动的噩梦**。

Helm 提供了两个核心抽象：

| 概念 | 类比 | 说明 |
|------|------|------|
| **Chart** | NPM 包 / Maven jar | 打包格式，定义"我要部署什么" |
| **Release** | npm install 的实例 | 运行实例，同一个 Chart 可以有多个 Release（staging/prod） |

```bash
# 创建 Chart 骨架
helm create order-service

# 目录结构一览
charts/order-service/
├── Chart.yaml          # 元信息 (name, version, description)
├── values.yaml         # 默认值 —— 你唯一需要经常改的文件
├── templates/          # Go 模板文件
│   ├── deployment.yaml
│   ├── service.yaml
│   └── ingress.yaml
└── .helmignore         # 类似 .gitignore
```

### Helm Release 生命周期

```mermaid
flowchart LR
    A["install"] --> B["running"]
    C["upgrade"] --> B
    D["rollback"] --> B
    E["uninstall"] --> B
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#fce4ec
    style E fill:#f3e5f5
```

## 第一步：让配置全部参数化

**values.yaml** 中存放所有可变参数，遵循"一处定义、多处引用"原则：

```yaml
# values.yaml
replicaCount: 2

image:
  repository: registry.example.com/order-service
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8080

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

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 75
```

**templates/deployment.yaml** 中使用 `{{ }}` 引用：

```yaml
# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
  namespace: {{ .Release.Namespace }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          resources: {{ toYaml .Values.resources | nindent 12 }}
```

> [!tip] 两个关键技巧
>
> 1. **`toYaml .X | nindent 12`**：将嵌套的对象序列化为 YAML 并缩进。如果直接写 `{{ .Values.resources }}`，输出会压缩成一行，Kubernetes 无法解析。
> 2. **`-` 修剪空白**：`{{- if ...` 和 `{{- end }}` 中的 `-` 会消除模板前后多余的换行符，避免生成空行导致 YAML 格式错误。

### Helm 内置对象速查

| Helm 对象 | 访问方式 | 用途 |
|-----------|----------|------|
| `.Release` | `.Release.Name`, `.Release.Namespace` | 当前发布实例的信息 |
| `.Chart` | `.Chart.Name`, `.Chart.Version` | Chart 本身的元信息 |
| `.Values` | `.Values.replicaCount` 等 | 用户传入的值（合并了 values.yaml + --set） |
| `.Capabilities` | `.Capabilities.KubeVersion` | 集群 API 版本信息 |
| `.Files` | `.Files.Get "config.ini"` | 读取同目录下的非模板文件 |
| `.Notes` | 渲染后显示给用户的提示文本 | Post-install 使用说明 |

## 第二步：多环境值覆盖

通过 **values 文件叠加**实现不同环境的差异化：

```bash
# Staging 使用命令行临时覆盖
helm upgrade --install order-service ./charts/order-service \
  --namespace=staging \
  --set image.tag=v1.2.4-dev

# Production 叠加额外值文件
helm upgrade --install order-service ./charts/order-service \
  --namespace=production \
  --values charts/order-service/values.prod.yaml \
  --set image.tag=v1.2.3
```

典型 `values.prod.yaml`（只写与默认值不同的部分）：

```yaml
replicaCount: 5

resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "2"
    memory: 2Gi

autoscaling:
  minReplicas: 5
  maxReplicas: 50
```

> [!tip] Values 文件合并优先级（低 → 高）
>
> 1. `values.yaml` — 默认值
> 2. `values.prod.yaml` — 环境变量覆盖文件
> 3. `--set image.tag=xxx` — 命令行参数（最高优先级）

```mermaid
flowchart TD
    A["values.yaml"] --> D["合并结果"]
    B["values.prod.yaml"] --> D
    C["--set image.tag=v1.2.3"] --> D
    D --> E[".Values"]
```

> [!warning] 常见陷阱：JSON Patch
>
> 当使用 `--set` 修改嵌套字段时，Helm 使用 JSON Patch，意味着它会**替换整个对象**而非合并。例如 `--set resources.limits.cpu="1"` 会将 `memory` 字段丢弃。对于复杂嵌套，优先使用独立的 values 文件。

## 第三步：条件渲染与循环

### 条件渲染

用 Helm 的条件语法处理可选资源：

```yaml
# templates/ingress.yaml
{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .Release.Name }}
spec:
  rules:
    - host: {{ .Values.ingress.host | quote }}
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ .Release.Name }}
                port:
                  number: {{ .Values.service.port }}
{{- end }}
```

> [!note] `quote` 管道函数
>
> 当值的类型不确定时（可能是字符串也可能是数字），加 `| quote` 确保输出带引号，避免 `true/false` 被 YAML 解析为布尔值。

### Range 循环生成多个资源

当需要批量创建多个 ServiceMonitor、ConfigMap 等时，`range` 非常有用：

```yaml
# templates/servicemonitor.yaml
{{- range $key, $value := .Values.extraServices }}
---
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: {{ $.Release.Name }}-{{ $key }}
spec:
  selector:
    matchLabels:
      app: {{ $.Release.Name }}
  endpoints:
    - port: {{ $value.port }}
      interval: {{ $value.interval | default "30s" }}
{{- end }}
```

对应的 values：

```yaml
extraServices:
  grpc-exporter:
    port: grpc
    interval: 15s
  prometheus-path:
    port: metrics
    interval: 10s
```

> [!example] 生成结果
>
> 上面这段模板会为每个 `extraServices` 条目生成一个独立的 ServiceMonitor。注意 `$key` 绑定到键名（`grpc-exporter`），而 `$value` 绑定到对应对象。使用 `$.Release.Name`（带美元前缀）是因为在 range 内部 `.` 已被重绑定。

## 第四步：复用模板片段

随着 Chart 膨胀，`deployment.yaml` 和 `service.yaml` 之间会产生大量重复逻辑。Helm 提供 `_helpers.tpl` 来统一管理可复用的模板片段。

### _helpers.tpl 标准写法

```yaml
{{/*
Common labels — 所有资源统一标注 */}}
{{- define "order.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end -}}

{{/*
Selector labels — Deployment selector 必须使用固定值 */}}
{{- define "order.selectorLabels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}
```

### 在模板中引用

```yaml
# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
  labels:
    {{- include "order.labels" . | nindent 4 }}
spec:
  selector:
    matchLabels:
      {{- include "order.selectorLabels" . | nindent 6 }}
```

> [!tip] include vs template
>
> - `include "name" .`：**返回值**，可通过 `| nindent` 继续管道处理 —— 适合注入 label、annotation
> - `template "name" .`：**直接输出**，不返回结果 —— 很少用，通常只在特殊情况下需要

## Chart 依赖与仓库管理

大型项目往往不会从零编写所有模板，而是复用社区已有的 Chart。

### 声明子依赖

```yaml
# Chart.yaml
apiVersion: v2
name: order-service
type: application
version: 1.2.0
appVersion: "1.2.3"

dependencies:
  - name: postgresql
    version: "15.0.0"
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
  - name: redis
    version: "18.0.0"
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled
```

- `condition` 告诉 Helm：当 values 中对应路径为 `false` 时，跳过安装该子 Chart。
- 子 Chart 的 values 通过 `postgresql.xxx` / `redis.xxx` 命名空间传入。

### 常用命令

```bash
helm dependency update ./charts/order-service   # 拉取 / 更新子依赖
helm dependency build ./charts/order-service    # 仅从 Chart.lock 构建（无网络变更时使用）
helm repo add bitnami https://charts.bitnami.com/bitnami
helm search repo prometheus                      # 搜索公开 Chart
```

> [!note] Chart.yaml 的 apiVersion
>
> - `apiVersion: v1`（Helm 2）：依赖写在 `dependencies:` 数组里，语义不同
> - `apiVersion: v2`（Helm 3）：引入 `requirements.yaml` 的概念整合到 Chart.yaml 自身，推荐使用 v2

## 与 ArgoCD 集成

ArgoCD 原生支持将 Helm Chart 作为 Application source，自动解析 `values.yaml`：

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: order-service
spec:
  source:
    repoURL: https://github.com/team/k8s-manifests.git
    targetRevision: main
    path: charts/order-service
    helm:
      parameters:
        - name: image.tag
          value: v1.2.3
        - name: replicaCount
          value: "5"
```

> [!tip] ArgoCD + Helm 进阶用法
>
> - **`helm.valueFrom`**：从 ConfigMap 或 Secret 取值，避免把敏感值暴露在 Git 中
> - **`helm.fileParameters`**：从文件加载大段配置值，适合 CI/CD 流水线场景
> - **`helm.ignoreMissingValueFiles: true`**：允许某些 values 文件按环境选择性存在

## Hooks：在关键时机执行自定义逻辑

Helm Hooks 允许你在 Release 的生命周期事件中挂载自定义 Job 或 Pod：

```yaml
# templates/migrate-db.yaml
{{- if .Values.dbMigration.enabled }}
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-db-migrate
  annotations:
    "hooks.helm.sh/hook": pre-upgrade,pre-install
    "hooks.helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          command: ["./migrate", "up"]
      restartPolicy: Never
{{- end }}
```

| Hook 事件 | 触发时机 |
|-----------|----------|
| `pre-install` | 资源创建之前（如数据库迁移） |
| `post-install` | 资源创建之后（如初始化数据） |
| `pre-upgrade` | 升级操作之前 |
| `post-upgrade` | 升级操作之后 |
| `pre-delete` | 删除操作之前（如优雅停机通知） |
| `post-delete` | 删除操作之后 |

## 调试与测试

### 可视化渲染结果

```bash
# 查看渲染后的纯 YAML（不做实际部署）
helm template my-release ./charts/order-service

# 指定命名空间和 values 文件
helm template my-release ./charts/order-service \
  --namespace=staging \
  -f values.staging.yaml
```

> [!tip] 调试三件套
>
> 1. **`helm lint ./charts/order-service`**：静态检查，快速定位语法问题
> 2. **`helm template`**：看渲染后的全量 YAML，逐段排查问题
> 3. **`helm diff upgrade --install ...`**：配合 [helm-diff 插件](https://github.com/helm/diff)，对比升级前后的差异

### Dry Run

```bash
# 模拟部署（服务端校验，但不会真正改变集群状态）
helm upgrade --install my-release ./charts/order-service \
  --dry-run --debug
```

## 最佳实践

| 原则 | 具体做法 |
|------|---------|
| **单一真相源** | 所有可配参数集中在 values.yaml，模板层只做引用不做硬编码 |
| **Helper 集中管理** | 公共 labels / selectors / annotations 一律放在 `_helpers.tpl` |
| **条件最小化** | 能用 defaults 解决的就不加 `if`；减少分支能大幅降低测试复杂度 |
| **版本号分离** | `Chart.yaml` 的 `version` 管 Chart 本身迭代，`appVersion` 管应用版本 |
| **先 lint 再 push** | CI 中加入 `helm lint` + `helm template --strict` 门禁 |
| **值文件只写差异** | `values.prod.yaml` 只覆盖与默认值不同的字段，保持可读性 |

## 何时用裸 YAML vs Helm vs Kustomize？

| 场景 | 推荐方案 | 理由 |
|------|---------|------|
| < 10 个服务 | Kustomize / 裸 YAML | 复杂度高于收益 |
| 10~50 个服务 | Helm | 模板复用价值明显 |
| > 50 个服务 | Helm + Kustomize overlays | Helm 管模板，Kustomize 管环境差异 |

> [!note] Kustomize 的定位
>
> Kustomize 不依赖 Go templating，更轻量。适合"基于同一套模板，按环境覆盖差异配置"的场景。
>
> **常见组合**：Helm 生成基础模板，Kustomize overlay 处理 staging/prod 差异。

## 关联笔记

- [[01-CICD基础与实践]] — CI/CD Pipeline 的搭建与实践
- [[02-GitOps与ArgoCD]] — GitOps 工作流与 ArgoCD
- [[04-安全与发布策略]] — 安全管理与发布决策
- [[../03-CICD与GitOps]] — 参考手册与决策指南