Helm 核心概念详解

AI 协助说明： 本页由 Codex 协助核验和修复站内链接；正文的技术事实和适用范围未因本次修改而改变，仍以文中来源及当前官方文档为准。

本文边界：本文聚焦 Chart、模板与 values、Release 等状态模型；若需要按场景查找具体 CLI 用法，请阅读命令速查文档。

推荐深读：Helm 常用命令技术文档。

1. 文档定位#

这篇文档配合 Helm 常用命令技术文档 阅读。命令文档回答“怎么做”，本文回答“这些命令背后的对象、状态和边界是什么”。

Helm 官方文档当前已经进入 Helm 4 文档版本，但实际环境中 Helm 3 仍然非常常见。命令文档中的安装脚本是 get-helm-3，因此本文以 Helm 3/4 都适用的核心概念为主；涉及版本差异时，会尽量用通用说法描述。

2. 一句话理解 Helm#

Helm 是 Kubernetes 的包管理器。它负责把一组 Kubernetes 资源定义组织成可复用、可配置、可版本化的包，然后安装到 Kubernetes 集群中。

更具体地说，Helm 同时做了三件事：

1. 把 Kubernetes YAML 打包成 Chart。
2. 用 values 把模板渲染成最终 manifest。
3. 把一次安装后的实例记录为 Release，支持升级、回滚、查看历史和卸载。

可以把 Helm 想成下面这条流水线：

flowchart LR
  A["Chart<br/>模板化的 Kubernetes 包"] --> B["Values<br/>配置输入"]
  B --> C["Template Rendering<br/>模板渲染"]
  C --> D["Manifest<br/>最终 Kubernetes YAML"]
  D --> E["Kubernetes API<br/>创建或更新资源"]
  E --> F["Release<br/>Helm 记录的安装实例"]

3. 本文覆盖的概念索引#

命令文档中直接或间接出现的概念包括：

• Helm
• Kubernetes
• Chart
• Chart.yaml
• Chart API version
• values.yaml
• values file
• values management
• values.schema.json
• computed values
• global values
• --set
• --set-string
• --set-file
• --set-json
• --reuse-values
• --reset-values
• Repository
• Artifact Hub
• Chart repository
• OCI registry
• Chart reference
• Chart package
• Chart archive
• appVersion
• chart version
• Release
• release name
• revision
• history
• rollback
• namespace
• kubeconfig
• kube-context
• manifest
• template
• dry-run
• debug
• wait
• timeout
• status
• hooks
• notes
• dependency
• subchart
• Chart.lock
• plugin
• helm-diff
• helm-secrets
• HELM_NAMESPACE
• HELM_KUBECONTEXT
• Kubernetes event
• label selector

下面逐个展开。

4. Helm 与 Kubernetes 的关系#

Helm 不负责运行容器。真正运行容器、调度 Pod、暴露 Service、管理 Deployment 的仍然是 Kubernetes。

Helm 的位置更像是 Kubernetes 上层的“应用交付工具”。你可以手写几十个 YAML 文件并用 kubectl apply 部署，也可以把这些 YAML 变成 Helm Chart，用一条 helm install 安装。

所以，Helm 的输出最终仍然是 Kubernetes 能理解的资源清单。

5. Helm Client#

命令文档中的 helm version、helm install、helm repo add 都是在使用 Helm CLI，也就是 Helm Client。

Helm Client 做这些事情：

• 读取本地 Helm 配置和仓库缓存。
• 读取 kubeconfig，知道要连接哪个 Kubernetes 集群。
• 下载或读取 Chart。
• 合并 values。
• 渲染模板。
• 调用 Kubernetes API 创建、更新或删除资源。
• 保存和读取 Release 信息。

Helm 3 以后没有 Helm 2 时代的服务端组件 Tiller。现代 Helm 常见工作模式是：本地 CLI 直接通过 Kubernetes API 操作集群。

6. kubeconfig 与 kube-context#

Helm 要访问 Kubernetes 集群，通常依赖和 kubectl 相同的 kubeconfig。

kubeconfig 里通常包含：

• clusters：集群地址和证书信息。
• users：访问集群的身份凭证。
• contexts：把 cluster、user、namespace 组合成一个可切换的上下文。
• current-context：当前默认使用哪个上下文。

命令文档中提到：

export HELM_KUBECONTEXT=prod-cluster

这表示让 Helm 默认使用名为 prod-cluster 的 kube-context。也可以在具体命令中使用 --kube-context 指定。

排障时常见命令：

kubectl config view
kubectl cluster-info

如果 Helm 安装失败，但错误看起来像权限、连接、证书、集群不可达，问题通常不在 Chart，而在 kubeconfig、当前 context 或集群访问权限。

7. Namespace#

Namespace 是 Kubernetes 的命名空间，用来在同一个集群中隔离资源名称和访问边界。

命令文档中常见写法：

helm install my-nginx bitnami/nginx -n my-namespace
helm list -n my-namespace
helm list --all-namespaces

需要区分三层含义：

1. Kubernetes 资源所在 namespace。
2. Helm Release 记录所在 namespace。
3. 命令默认操作的 namespace。

如果你在 production namespace 安装了一个 Release，那么普通的 helm list 可能看不到它，因为默认只查当前 namespace。需要：

helm list -n production

或：

helm list -A

HELM_NAMESPACE 可以设置 Helm 默认 namespace：

export HELM_NAMESPACE=production

注意：-n 指定 namespace 不一定会自动创建 namespace。实际部署时常见做法是先创建 namespace，或在支持的命令中加 --create-namespace。

8. Chart#

Chart 是 Helm 的包。一个 Chart 描述了一个应用、组件或服务在 Kubernetes 中应该如何部署。

官方文档把 Chart 描述为包含一组 Kubernetes 资源定义的包。一个 Chart 可以很简单，比如只部署一个 nginx；也可以很复杂，比如同时包含 Web 服务、数据库、缓存、ServiceAccount、Ingress、ConfigMap 等。

典型目录结构：

my-chart/
  Chart.yaml
  values.yaml
  values.schema.json
  templates/
  charts/
  crds/
  README.md
  LICENSE
  .helmignore

这些文件分别承担不同职责。

9. Chart.yaml#

Chart.yaml 是 Chart 的身份信息文件。

常见内容：

apiVersion: v2
name: my-chart
description: A Helm chart for Kubernetes
type: application
version: 1.2.3
appVersion: "2.0.0"
dependencies:
  - name: redis
    version: 20.0.0
    repository: https://charts.bitnami.com/bitnami

重要字段解释：

10. Chart API Version#

命令文档中出现了：

helm create my-chart --api-version v2

这里的 api-version 指 Chart API 版本。它描述 Chart 格式本身，不是 Deployment、Service 这些 Kubernetes 资源的 apiVersion。

常见区别：

现代 Helm 3/4 的普通 Chart 通常使用 apiVersion: v2。

11. Application Chart 与 Library Chart#

Chart 类型由 Chart.yaml 中的 type 字段表示。

application Chart 是最常见类型，用于真正安装应用。比如 nginx、redis、wordpress 这些都属于应用 Chart。

library Chart 不直接安装应用资源，而是提供可复用的模板片段、命名模板或辅助函数。它常用于组织多个 Chart 的公共逻辑，例如统一 labels、name 生成规则、image 拼接规则。

如果你只是部署服务，通常写 type: application。只有在抽公共模板能力时，才考虑 library Chart。

12. Repository#

Repository 是 Chart 仓库，用来存放和分发 Chart。

命令文档中：

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo list
helm repo update
helm repo remove bitnami

这些命令管理的是本地 Helm Client 认识哪些 Chart 仓库。

传统 Chart repository 本质上是一个 HTTP 服务，里面至少需要一个 index.yaml。index.yaml 记录了仓库中有哪些 Chart、每个 Chart 的版本、下载地址、摘要等信息。

可以这样理解：

helm repo add    -> 记住仓库地址
helm repo update -> 拉取或刷新 index.yaml 到本地缓存
helm search repo -> 在本地缓存中搜索 Chart

helm repo update 不会升级集群里的应用，它只更新本地对远程 Chart 仓库的索引认知。

13. stable 仓库与 Bitnami 仓库#

命令文档中有：

helm repo add stable https://charts.helm.sh/stable
helm repo add bitnami https://charts.bitnami.com/bitnami

stable 是历史上非常常见的 Helm 仓库名称。现在实际使用时，更多会通过 Artifact Hub 查找维护良好的 Chart，然后添加具体维护方的仓库。例如 Bitnami、Grafana、Prometheus Community、Ingress NGINX 等。

bitnami/nginx 的含义是：

bitnami -> 本地仓库别名
nginx   -> 仓库里的 Chart 名称

这个组合叫 Chart reference。

14. Artifact Hub#

命令文档中出现：

helm search hub wordpress

Artifact Hub 是云原生制品搜索平台。它不是你本地添加的 Helm 仓库，而是一个用于发现公开 Chart 的索引平台。

helm search hub 和 helm search repo 的区别：

常见流程是：

先用 helm search hub 找 Chart
再根据结果 helm repo add 对应仓库
然后 helm search repo 或 helm install

15. OCI Registry#

命令文档中出现：

helm install my-app oci://registry.example.com/charts/my-app
helm push my-chart-1.0.0.tgz oci://registry.example.com/charts

OCI 是 Open Container Initiative 的缩写。你可以粗略理解成“容器镜像仓库那套分发协议”。Helm 支持把 Chart 作为 OCI Artifact 存到支持 OCI 的 registry 中。

传统 Chart repository 和 OCI registry 的区别：

helm push 推送 OCI Chart 时，目标地址一般不写 Chart 文件名和版本标签。Helm 会从 .tgz 包中的 Chart 名称和 Chart 版本推导出 registry 中的 basename 和 tag。

16. Chart Reference#

Chart reference 是 Helm 命令中指定 Chart 来源的方式。

helm install 支持多种 Chart 表达方式：

helm install my-nginx bitnami/nginx
helm install my-app ./my-chart
helm install my-app ./my-chart-1.0.0.tgz
helm install my-app https://example.com/charts/my-chart-1.0.0.tgz
helm install my-app oci://registry.example.com/charts/my-app

这些都在表达“我要安装哪个 Chart”。

17. Chart Version、App Version 与 Release Revision#

这三个版本很容易混淆。

举例：

version: 1.2.3
appVersion: "2.0.0"

表示这个 Chart 包版本是 1.2.3，它默认部署的应用版本是 2.0.0。

如果你执行：

helm upgrade my-app ./my-chart

Helm 会给 my-app 这个 Release 增加一个新的 revision。这个 revision 是 Release 生命周期里的历史序号，不等于 Chart version，也不等于 appVersion。

18. values.yaml#

values.yaml 是 Chart 的默认配置文件。

模板中常见写法：

replicas: {{ .Values.replicaCount }}

对应的 values.yaml：

replicaCount: 3

Helm 渲染模板时，会把 .Values.replicaCount 替换成 3。

所以 Chart 的核心思想是：

templates 负责结构
values 负责变量
manifest 是渲染结果

19. Values File#

命令文档中经常使用：

helm install my-nginx bitnami/nginx -f custom-values.yaml
helm upgrade my-nginx bitnami/nginx -f new-values.yaml
helm template my-app ./my-chart -f values.yaml

-f 或 --values 用来传入额外的 values 文件，覆盖 Chart 内置的 values.yaml。

常见做法是按环境拆分：

values.yaml
values-dev.yaml
values-test.yaml
values-prod.yaml

部署生产环境时：

helm upgrade my-app ./my-chart -f values-prod.yaml

这样比在命令行中写大量 --set 更容易审查、版本管理和回滚。

20. Values 优先级#

Helm values 通常来自多层输入。越靠后的覆盖能力越强：

Chart 内置 values.yaml
< 父 Chart 给子 Chart 的 values
< 命令行 -f / --values 文件
< 命令行 --set

多个 -f 同时出现时，右边的文件优先级更高：

helm install my-app ./chart -f base.yaml -f prod.yaml

如果两个文件都定义了同一个 key，以 prod.yaml 为准。

多个 --set 同时出现时，也是右边优先：

helm install my-app ./chart --set image.tag=v1 --set image.tag=v2

最终 image.tag 是 v2。

21. –set 与嵌套配置#

命令文档中出现：

helm install my-nginx bitnami/nginx --set replicaCount=3
helm install my-nginx bitnami/nginx --set service.type=LoadBalancer

--set service.type=LoadBalancer 对应的 YAML 结构是：

service:
  type: LoadBalancer

--set 适合临时覆盖少量参数。如果参数很多，推荐使用 values 文件。

常见相关参数：

例如端口、布尔值、长数字、密码、JSON 数组这类值，使用错误的 --set 形式可能导致类型不符合预期。

22. Values 管理策略#

前面几节解释了 values 是什么、如何覆盖、优先级如何计算。实际项目中更重要的问题是：values 应该放在哪里、怎么分环境、怎么审查、怎么处理密钥、升级时怎么避免旧值污染新版本。

Values 管理要解决的是下面这些问题：

• 同一个 Chart 在开发、测试、预发、生产环境中配置不同。
• 配置需要进入 Git 做审查和追踪。
• 临时参数不能在生产环境里失控扩散。
• 密钥不能明文暴露在仓库、日志和终端历史中。
• 升级 Chart 时能清楚知道新默认值和旧自定义值如何合并。
• 子 Chart、全局配置和应用自身配置边界清楚。

22.1 默认 values 与部署 values 要分开#

Chart 自带的 values.yaml 应该表达“这个 Chart 的默认配置”。它更像 Chart 的配置接口说明，不应该被每个环境直接改来改去。

如果使用第三方 Chart，例如 bitnami/nginx，通常不要修改 Chart 包里的 values.yaml。正确做法是另建覆盖文件：

helm-values/
  nginx-dev.yaml
  nginx-test.yaml
  nginx-prod.yaml

部署时传入：

helm upgrade --install my-nginx bitnami/nginx \
  -n production \
  -f helm-values/nginx-prod.yaml

这样可以保持 Chart 来源可升级，同时让你的环境配置独立版本管理。

如果是自研 Chart，可以把默认值放在 Chart 的 values.yaml 中，把不同环境的值放在 Chart 外部或仓库的环境目录中：

charts/
  my-app/
    Chart.yaml
    values.yaml
    templates/
environments/
  dev/
    my-app.yaml
  staging/
    my-app.yaml
  prod/
    my-app.yaml

22.2 推荐的 values 分层#

Helm 支持多次使用 -f，右侧文件优先级更高。因此可以按“从通用到具体”的顺序组织：

helm upgrade --install my-app ./charts/my-app \
  -f values/common.yaml \
  -f values/prod.yaml \
  -f values/prod-cn.yaml

推荐分层：

关键原则是：越靠后的文件越具体，越具体的文件覆盖越通用的文件。

22.3 values 文件应该进入版本管理#

生产环境 values 文件应该进入 Git 或 GitOps 仓库。这样有几个好处：

• 每次配置变更可以被 code review。
• 可以回溯谁在什么时候改了哪个参数。
• 可以和应用版本、Chart 版本建立对应关系。
• 可以在事故后还原当时部署输入。
• CI/CD 能复现同一次部署。

不推荐在生产环境中长期依赖手写命令：

helm upgrade my-app ./chart --set replicaCount=5 --set image.tag=v2

更推荐把稳定配置写入文件：

# values-prod.yaml
replicaCount: 5
image:
  tag: v2

然后执行：

helm upgrade my-app ./chart -f values-prod.yaml

--set 更适合发布流水线传入少量动态值，例如镜像 tag、构建号、Git commit SHA。

22.4 --set 的使用边界#

--set 最大的问题是不可审查、容易进入 shell history、复杂结构可读性差。

适合使用 --set 的场景：

• CI/CD 注入镜像 tag。
• 临时调试一个开关。
• 覆盖一两个简单标量值。
• 本地快速验证。

不适合使用 --set 的场景：

• 大量业务配置。
• 多层嵌套结构。
• Secret、token、password。
• 需要长期维护的生产配置。
• 包含逗号、等号、JSON、特殊字符的复杂值。

复杂值优先写入 values 文件。必须走命令行时，根据类型选择：

例如版本号 1.20、布尔字符串 "false"、长数字 ID，都应该避免被 YAML 或 Helm 类型推断改写：

helm upgrade my-app ./chart --set-string app.version=1.20

22.5 Computed Values 与 User-supplied Values#

执行：

helm install my-app ./chart --dry-run --debug

输出里通常会看到两类 values：

USER-SUPPLIED VALUES
COMPUTED VALUES

USER-SUPPLIED VALUES 表示用户通过 -f、--set 等方式传入的值。

COMPUTED VALUES 表示 Helm 合并 Chart 默认值、父 Chart 覆盖值、用户 values、命令行参数之后得到的最终 values。

排查配置不生效时，优先看 computed values。因为模板真正读取的是合并后的 .Values，不是某一个单独文件。

22.6 查看已部署 Release 的 values#

安装后可以用：

helm get values my-app

查看用户传入过的 values。这个命令默认不展示 Chart 默认值，只展示用户覆盖过的部分。

如果想看合并 Chart 默认值后的完整 values，可以使用：

helm get values my-app --all

查看历史 revision 的 values：

helm get values my-app --revision 3

这在排查“上次升级到底带了哪些配置”时很有用。

22.7 升级时 values 如何处理#

升级时最容易出问题的是旧 values 和新 Chart 默认 values 的关系。

常见策略：

生产升级建议：

1. 先用 helm show values <chart> 查看新 Chart 默认 values。
2. 和当前环境 values 文件对比，确认 key 是否变更。
3. 用 helm diff upgrade 查看 manifest 差异。
4. 用 helm upgrade --dry-run --debug 查看 computed values。
5. 再执行正式 upgrade。

如果 Chart 大版本升级，尤其是 values 结构发生变化时，不要盲目 --reuse-values。旧 key 可能已经废弃，或者含义已经改变。

22.8 删除默认值中的某个 key#

Helm 合并 values 时，默认是把 map 合并，而不是简单替换整个对象。某些场景下，你想删除 Chart 默认 values 中的某个 key，需要把它显式设为 null。

例如默认值中有：

livenessProbe:
  httpGet:
    path: /healthz
    port: http
  initialDelaySeconds: 30

如果你只添加 exec，可能会得到同时包含 httpGet 和 exec 的非法探针配置。此时需要把原来的 httpGet 清掉：

livenessProbe:
  httpGet: null
  exec:
    command:
      - cat
      - /tmp/healthy
  initialDelaySeconds: 30

命令行也可以写：

helm upgrade my-app ./chart \
  --set livenessProbe.httpGet=null \
  --set livenessProbe.exec.command='{cat,/tmp/healthy}'

不过这种复杂结构更建议写到 values 文件里。

22.9 values.schema.json#

values.schema.json 用来校验 values 的结构、类型和必填项。它对 Chart 维护非常有价值，尤其是多人协作或提供给其他团队使用的 Chart。

例如：

{
  "$schema": "https://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        }
      },
      "required": ["repository", "tag"]
    }
  },
  "required": ["replicaCount", "image"]
}

这样可以提前发现：

• replicaCount 写成字符串。
• 忘记配置 image.tag。
• 某个字段类型不符合预期。
• 必填配置缺失。

如果临时不希望执行 schema 校验，Helm 命令提供了跳过校验的选项，但生产环境不建议长期依赖跳过校验。

22.10 values 的命名和结构设计#

设计 values 时，不只是给自己看，也是在设计 Chart 的配置 API。

推荐规则：

• key 使用小写开头的 camelCase，例如 replicaCount、serviceAccount。
• 避免 key 中使用连字符，例如不要写 service-account。
• 字符串显式加引号，例如 tag: "1.20"。
• 能扁平就不要过度嵌套。
• 强关联的一组配置可以用 map 嵌套。
• 避免用数组表达需要频繁覆盖的配置，优先用 map。
• 每个重要 key 都写注释或在 README 中说明。

不太好覆盖的写法：

servers:
  - name: api
    port: 8080
  - name: admin
    port: 9090

更容易覆盖的写法：

servers:
  api:
    port: 8080
  admin:
    port: 9090

这样覆盖 api 端口时更直观：

helm upgrade my-app ./chart --set servers.api.port=8081

22.11 Subchart 与 global values 管理#

父 Chart 可以通过子 Chart 名称覆盖子 Chart values：

redis:
  auth:
    enabled: true
    password: example

这里的 redis 通常对应依赖 Chart 的名称或 alias。

如果多个子 Chart 需要共享同一类配置，可以使用 global：

global:
  imageRegistry: registry.example.com
  storageClass: fast-ssd

但 global 不应滥用。它适合放真正跨 Chart 的公共配置，例如镜像仓库前缀、集群域名、统一 storageClass。业务私有配置仍然应该留在各自 Chart 的 values 作用域内。

22.12 Secret values 管理#

Values 里经常会出现密码、token、证书路径等敏感信息。需要明确一点：values 本身不是安全边界。

风险包括：

• values 文件明文提交到 Git。
• --set password=... 进入 shell history。
• helm install --debug 输出敏感值。
• helm get values 被有权限的人读取。
• 渲染后的 manifest 中包含 Secret 数据。

常见处理方式：

推荐优先让 Helm values 引用 Secret 名称，而不是直接承载 Secret 明文：

database:
  existingSecret: my-app-database
  usernameKey: username
  passwordKey: password

模板再引用这个 Secret：

env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: {{ .Values.database.existingSecret }}
        key: {{ .Values.database.passwordKey }}

这样 Helm 管理的是引用关系，敏感值由专门的 Secret 管理链路负责。

22.13 多环境 values 示例#

一个可维护的多环境结构可以长这样：

deploy/
  helm/
    values-common.yaml
    values-dev.yaml
    values-staging.yaml
    values-prod.yaml
    secrets-prod.enc.yaml

values-common.yaml：

image:
  repository: registry.example.com/my-app
service:
  type: ClusterIP
resources:
  requests:
    cpu: "100m"
    memory: "128Mi"

values-prod.yaml：

replicaCount: 4
ingress:
  enabled: true
  hosts:
    - host: app.example.com
resources:
  requests:
    cpu: "500m"
    memory: "512Mi"
  limits:
    cpu: "1"
    memory: "1Gi"

部署：

helm upgrade --install my-app ./charts/my-app \
  -n production \
  -f deploy/helm/values-common.yaml \
  -f deploy/helm/values-prod.yaml \
  --set-string image.tag="${IMAGE_TAG}" \
  --wait \
  --timeout 5m

这里公共配置、生产配置和动态镜像 tag 各自有清晰边界。

22.14 values 变更前的检查流程#

生产环境 values 变更建议按这个顺序检查：

helm lint ./charts/my-app -f deploy/helm/values-prod.yaml
helm template my-app ./charts/my-app -f deploy/helm/values-prod.yaml > manifest.yaml
helm upgrade my-app ./charts/my-app -f deploy/helm/values-prod.yaml --dry-run --debug
helm diff upgrade my-app ./charts/my-app -f deploy/helm/values-prod.yaml

重点看：

• computed values 是否符合预期。
• manifest 是否出现意外删除或重命名资源。
• Secret 是否被打印到日志。
• Deployment、Service、Ingress、PVC 等关键资源是否变化。
• 不可变字段是否被修改，例如某些 Service 字段、PVC 字段。

22.15 values 管理反模式#

常见反模式：

• 生产配置长期只存在某个人的终端命令历史里。
• 大量 --set 拼接成一条很长的发布命令。
• 把第三方 Chart 解压后直接改它的 values.yaml。
• 明文密码写入 values 文件并提交 Git。
• Chart 大版本升级时盲目 --reuse-values。
• 多个环境复制整份 values，只有少数字段不同，导致配置漂移。
• 子 Chart 配置和父 Chart 配置边界混乱，到处依赖 global。
• 不使用 values.schema.json，错误配置只能等安装失败才发现。

一个比较稳的经验是：长期配置进文件，动态发布参数走流水线，敏感信息进密钥系统，升级前看 computed values 和 manifest diff。

23. Template#

Template 是 Helm Chart 中的模板文件，通常放在 templates/ 目录下。

模板不是最终 YAML。模板里可以包含 Go template 语法和 Helm 提供的对象：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}

Helm 会在安装、升级或执行 helm template 时渲染这些模板。

模板常用能力：

• 读取 .Values。
• 读取 .Release。
• 读取 .Chart。
• 使用 if、with、range 控制结构。
• 使用函数和管道处理字符串、默认值、缩进、YAML 转换。
• 使用命名模板复用 labels、fullname 等片段。

24. Built-in Objects#

Helm 模板中有一些内置对象。

例如：

metadata:
  name: {{ .Release.Name }}
  labels:
    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}

这里 .Release.Name 来自安装命令中的 release name，.Chart.Name 和 .Chart.Version 来自 Chart.yaml。

25. Manifest#

Manifest 是 Helm 渲染模板后生成的 Kubernetes YAML。

命令文档中：

helm get manifest my-nginx
helm template my-app ./my-chart > manifest.yaml

helm template 生成的是 manifest，但不会提交给 Kubernetes。helm install 和 helm upgrade 会把生成的 manifest 提交给 Kubernetes API。

要区分三种文件：

排查模板问题时，先看 manifest 往往比直接看模板更直观。

26. helm template#

命令文档中：

helm template my-app ./my-chart
helm template my-app ./my-chart -f values.yaml
helm template my-app ./my-chart --set replicaCount=2

helm template 是本地渲染命令。它不需要真的在集群里创建资源，适合：

• 检查最终 YAML 长什么样。
• 在 CI 中做静态检查。
• 和 kubectl diff、kubeconform 等工具配合。
• 排查 values 是否生效。
• 排查模板语法和缩进问题。

不过要注意，helm template 不等价于真实安装。真实安装时，Kubernetes API 还会做权限校验、资源字段校验、准入控制、调度等后续动作。

27. Dry Run#

命令文档中：

helm install my-nginx bitnami/nginx --dry-run
helm install --dry-run --debug my-app ./my-chart

--dry-run 表示模拟执行。它会尽量走安装或升级流程，但不真正把结果落到集群资源上。

常见用途：

• 预览安装输出。
• 检查 values 合并结果。
• 检查模板渲染是否失败。
• 与 --debug 组合查看更多细节。

需要注意：CRD 场景下 dry-run 可能有局限，因为 CRD 会改变 Kubernetes API 可识别的资源类型，而 dry-run 不会真的先安装 CRD。

28. Debug#

--debug 会输出更多 Helm 内部处理信息，常与 --dry-run、helm template、helm lint 一起使用。

例如：

helm install --debug --dry-run my-app ./my-chart
helm template my-app ./my-chart --debug
helm lint ./my-chart --debug

它适合用于模板渲染失败、values 不符合预期、Chart 结构异常等问题。

29. Release#

Release 是一个 Chart 安装到 Kubernetes 集群后的实例。

命令文档中：

helm install my-nginx bitnami/nginx

这里 my-nginx 是 release name，bitnami/nginx 是 Chart。

同一个 Chart 可以安装多次，只要 release name 不同：

helm install nginx-a bitnami/nginx
helm install nginx-b bitnami/nginx

这会得到两个独立 Release。它们可以有不同 values、不同 namespace、不同生命周期。

可以这样理解：

Chart 是类
Release 是对象实例
values 是实例化参数

30. Release Name#

Release name 是一次安装的名字。它会影响：

• Helm 管理该 Release 时的标识。
• 模板中的 .Release.Name。
• 很多 Chart 生成 Kubernetes 资源名称的前缀。

例如：

helm install my-wordpress bitnami/wordpress

Chart 模板中如果使用：

metadata:
  name: {{ .Release.Name }}-service

最终资源名可能是：

my-wordpress-service

Release name 在同一 namespace 下通常需要唯一。命名要稳定，不建议随意改，否则 Helm 会认为是另一个 Release。

31. Install#

helm install 的本质是创建一个新 Release。

大致流程：

读取 Chart
读取并合并 values
安装 crds/ 中的 CRD
渲染 templates/
执行 pre-install hooks
提交普通资源到 Kubernetes
如果设置 --wait，等待资源 Ready
执行 post-install hooks
保存 Release 记录
输出 NOTES

命令文档中：

helm install my-nginx bitnami/nginx --wait --timeout 5m

这表示安装后等待资源达到就绪状态，最长等待 5 分钟。

32. Wait 与 Timeout#

--wait 表示 Helm 不只提交资源，还要等待资源进入就绪状态。

常见等待对象包括：

• Pod 是否 Ready。
• Deployment 是否完成 rollout。
• StatefulSet 是否准备好。
• Job 是否完成。
• PVC 是否绑定。

--timeout 表示最长等待时间。

helm install my-app ./my-chart --wait --timeout 5m

生产环境推荐使用 --wait 和明确的 --timeout，否则 Helm 可能已经返回成功，但实际 Pod 还在拉镜像、CrashLoop 或等待调度。

33. Status#

helm status 查看 Release 当前状态。

helm status my-nginx

它通常会展示：

• Release 名称。
• Namespace。
• 当前状态。
• Revision。
• 最近部署时间。
• Chart 信息。
• 用户说明，也就是 NOTES.txt 渲染结果。

常见状态包括：

如果 helm status 显示成功，但业务不可用，还需要继续用 kubectl get pods、kubectl describe、kubectl logs 检查 Kubernetes 层面的状态。

34. Revision#

Revision 是 Release 的历史修订号。

第一次安装：

REVISION: 1

每次成功或失败的升级、回滚都可能产生新的 revision。可以用：

helm history my-nginx

查看历史。

Revision 是 Helm 对 Release 生命周期的记录，不是 Git commit，也不是 Chart version。

35. Upgrade#

helm upgrade 用来更新已有 Release。

命令文档中：

helm upgrade my-nginx bitnami/nginx
helm upgrade my-nginx bitnami/nginx --version 13.2.2
helm upgrade my-nginx bitnami/nginx -f new-values.yaml
helm upgrade my-nginx bitnami/nginx --set replicaCount=5

升级可能包含多种变化：

• Chart 版本变化。
• 应用镜像版本变化。
• values 变化。
• 模板结构变化。
• Kubernetes 资源字段变化。
• 子 Chart 依赖变化。

升级不是简单地“重新安装”。Helm 会把新 manifest 与当前 Release 记录对比，然后对 Kubernetes 资源执行创建、更新或删除。

36. Reset Values、Reuse Values 与 Reset Then Reuse#

命令文档中出现：

helm upgrade my-nginx bitnami/nginx --reset-values

升级时 values 的处理很关键。

如果 Chart 默认值在新版本中变化很大，盲目 --reuse-values 可能保留旧配置导致新 Chart 行为异常。如果你希望完全采用新 Chart 默认配置，则使用 --reset-values 更清晰。

37. History#

helm history 查看某个 Release 的 revision 列表。

helm history my-nginx
helm history my-nginx --max 10

历史记录中通常能看到：

• revision 编号。
• 更新时间。
• 状态。
• Chart 版本。
• appVersion。
• 描述信息。

它是 rollback 的基础。没有历史，就无法指定过去的 revision 回滚。

38. Rollback#

helm rollback 把 Release 回退到某个历史 revision。

命令文档中：

helm rollback my-nginx
helm rollback my-nginx 2
helm rollback my-nginx 2 --wait

需要注意：rollback 本身也会创建一个新的 revision。

例如历史是：

1 deployed
2 superseded
3 failed

执行：

helm rollback my-nginx 2

成功后可能变成：

4 deployed

也就是说，Release 并不是“穿越回 revision 2”，而是“用 revision 2 的配置和 manifest 创建一个新的当前 revision”。

39. Uninstall#

helm uninstall 卸载 Release。

命令文档中：

helm uninstall my-nginx
helm uninstall my-nginx --keep-history
helm uninstall my-nginx --no-hooks

默认情况下，Helm 会删除这个 Release 管理的 Kubernetes 资源，并删除 Release 记录。

--keep-history 表示保留 Release 历史，使它仍然能在历史中被看到。

--no-hooks 的准确含义是不执行卸载相关 hooks，并不是“强制删除所有资源”。如果卸载问题来自 hook 卡住，--no-hooks 可能绕开 hook；如果问题来自 Kubernetes 资源 finalizer、权限或 API 异常，则仍需要到 Kubernetes 层面处理。

40. hooks#

Hook 是 Helm 生命周期钩子。Chart 作者可以声明某些资源在安装、升级、回滚、删除、测试等阶段执行。

常见 hook 类型：

Hook 本质上仍然是 Kubernetes manifest，只是带了特殊 annotation：

metadata:
  annotations:
    "helm.sh/hook": post-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded

常见用途：

• 安装前初始化数据库。
• 升级前备份数据。
• 安装后执行健康检查 Job。
• 删除前做外部系统解绑。

Hook 也容易带来复杂性。尤其要注意：hook 创建的资源不一定像普通资源那样被 Release 生命周期完整管理。需要通过 hook delete policy、Job TTL 或手动清理来避免残留。

41. Notes#

命令文档中出现：

helm get notes my-nginx

Notes 来自 Chart 中的：

templates/NOTES.txt

安装完成或执行 helm status 时，Helm 会渲染并输出这个文件。它通常用于告诉用户：

• 如何访问服务。
• 如何获取初始密码。
• 下一步该执行什么命令。
• 关键注意事项。

NOTES.txt 也是模板文件，可以使用 .Values、.Release 等对象。

42. helm get#

helm get 系列命令用于查看某个 Release 的细节。

命令文档中：

helm get manifest my-nginx
helm get values my-nginx
helm get all my-nginx
helm get hooks my-nginx
helm get notes my-nginx

它们对应不同信息层：

helm show values 看的是 Chart 默认 values。helm get values 看的是某个 Release 实际使用的 values。两者不要混淆。

43. CRD#

CRD 是 CustomResourceDefinition，用来扩展 Kubernetes API，让集群认识新的资源类型。

例如安装 cert-manager 时，可能会引入 Certificate、Issuer 等自定义资源类型。

Helm Chart 中的 CRD 通常放在：

crds/

CRD 有特殊处理逻辑：

• 安装时，crds/ 中的 CRD 会在普通 templates 前安装。
• CRD 文件不走普通模板渲染。
• 已存在的 CRD 通常不会被重复安装。
• Helm 通常不会在 upgrade 或 rollback 时自动升级 CRD。
• Helm uninstall 通常不会自动删除 CRD。

原因是 CRD 是集群级别能力，删除 CRD 可能会删除所有 namespace 中该类型的自定义资源，风险很高。

44. Dependency#

命令文档中：

helm dependency update ./my-chart
helm dependency build ./my-chart
helm dependency list ./my-chart

Dependency 是 Chart 依赖。一个 Chart 可以依赖其他 Chart。

例如你的应用需要 Redis，可以在 Chart.yaml 写：

dependencies:
  - name: redis
    version: 20.0.0
    repository: https://charts.bitnami.com/bitnami

父 Chart 安装时，依赖 Chart 会作为 subchart 一起渲染和安装。

45. Subchart#

Subchart 是子 Chart，通常来自依赖。

父 Chart 和子 Chart 的 values 有作用域边界：

• 子 Chart 可以有自己的 values.yaml。
• 父 Chart 可以覆盖子 Chart 的 values。
• 普通子 Chart 不应该直接依赖父 Chart 的内部 values。
• global values 可以被父子 Chart 共享。

父 Chart 覆盖子 Chart values 的常见写法：

redis:
  auth:
    enabled: true
    password: example

这里 redis 通常对应依赖 Chart 名称。具体 key 要看子 Chart 暴露了哪些 values。

46. Chart.lock#

Chart.lock 是依赖锁定文件。它记录依赖解析后的具体版本和摘要，确保不同环境构建出一致的依赖结果。

helm dependency update 和 helm dependency build 的区别：

如果仓库中提交了 Chart.lock，CI 中更推荐 helm dependency build，这样依赖版本更可控。

47. Chart Package 与 Chart Archive#

命令文档中：

helm package ./my-chart
helm package ./my-chart --version 1.2.3
helm package ./my-chart --app-version 2.0.0
helm package ./my-chart --destination ./packages

helm package 会把 Chart 目录打包为 .tgz 文件：

my-chart-1.2.3.tgz

这个 .tgz 就是 Chart archive，也就是可以被分发、上传、安装的 Chart 包。

打包时：

• --version 会覆盖 Chart.yaml 中的 Chart version。
• --app-version 会覆盖 Chart.yaml 中的 appVersion。
• --destination 指定输出目录。

发布到传统 Chart repository 或 OCI registry 前，通常都要先 package。

48. Lint#

helm lint 用于检查 Chart 是否符合基本规范。

命令文档中：

helm lint ./my-chart
helm lint ./my-chart --strict
helm lint ./my-chart --debug

它会检查：

• Chart 结构是否合理。
• Chart.yaml 是否有效。
• values schema 是否匹配。
• 模板是否能被解析。
• 一些常见最佳实践问题。

--strict 会把某些警告提升为错误，适合 CI。helm lint 不是完整的 Kubernetes 校验，它不能替代真实集群准入校验或策略校验。

49. Plugin#

Helm Plugin 是扩展 Helm CLI 的机制。插件不是 Helm 内置命令，但安装后可以通过 helm <plugin> 使用。

命令文档中：

helm plugin install https://github.com/databus23/helm-diff
helm plugin list
helm plugin update diff
helm plugin uninstall diff

常见插件：

插件会扩展本地 Helm 行为。生产环境使用插件时要注意版本一致性和安全性，尤其是会处理密钥、仓库凭证或执行外部命令的插件。

50. helm-diff#

命令文档中：

helm diff upgrade my-app ./my-chart

helm-diff 的核心价值是“升级前看差异”。它通常会比较当前 Release 和本次升级渲染出的 manifest 差异。

它适合回答：

• 这次升级会改哪些 Deployment、Service、ConfigMap？
• 镜像 tag 有没有变？
• replicas 有没有变？
• 是否会删除某些资源？
• 是否会修改不可变字段？

生产升级前先看 diff，是非常好的习惯。

51. helm-secrets#

命令文档中：

helm secrets install my-app ./my-chart -f secrets.yaml

helm-secrets 常用于管理加密 values。它通常配合 SOPS、age、GPG 或云 KMS 等工具，让 Git 仓库中保存的是加密后的 values 文件，部署时再解密传给 Helm。

需要注意：

• Helm values 最终仍可能进入 Kubernetes Secret 或 manifest。
• 加密 values 文件不等于运行时 Secret 安全。
• CI/CD 中要保护解密密钥。
• 避免在 --debug 输出、日志、终端历史中泄露敏感值。

52. HELM_NAMESPACE 与 HELM_KUBECONTEXT#

命令文档中：

export HELM_NAMESPACE=production
export HELM_KUBECONTEXT=prod-cluster

这些环境变量影响 Helm 默认行为。

可以用：

helm env

查看 Helm 当前环境配置。

在多集群、多 namespace 环境中，建议在生产操作前显式确认：

helm env
kubectl config current-context
helm list -n production

53. Kubernetes Event#

命令文档中：

kubectl get events --sort-by='.lastTimestamp'

Kubernetes Event 是集群记录资源变化和异常原因的一种对象。Helm 安装失败时，Helm 错误信息可能只告诉你等待超时，但真正原因在 Kubernetes events 里。

常见事件原因：

• 镜像拉取失败。
• PVC 无法绑定。
• Pod 调度失败。
• 探针失败。
• 权限不足。
• Ingress 或 LoadBalancer 创建异常。

排障顺序可以是：

helm status
helm get manifest
kubectl get pods
kubectl describe pod
kubectl get events
kubectl logs

54. Label Selector#

命令文档中：

kubectl get pods -l app=my-app

-l app=my-app 是 label selector。Kubernetes 资源经常通过 labels 建立关联和筛选。

Helm Chart 通常会给资源加标准 labels，例如：

app.kubernetes.io/name: my-app
app.kubernetes.io/instance: my-release
app.kubernetes.io/managed-by: Helm
helm.sh/chart: my-chart-1.2.3

这些 labels 的作用：

• 帮助查询某个 Release 相关资源。
• 帮助 Service 选择 Pod。
• 帮助监控、日志、成本分析系统归类资源。
• 标识资源由 Helm 管理。

排查时，比起只看资源名称，使用 labels 查询更稳定。

55. 常见命令背后的概念映射#

56. 从概念角度理解一次生产升级#

假设命令是：

helm diff upgrade my-app ./my-chart
helm upgrade my-app ./my-chart \
  --values values.yaml \
  --set image.tag=v2.0.0 \
  --wait \
  --timeout 5m

概念上发生了这些事：

1. Helm 读取当前 kube-context 和 namespace。
2. Helm 找到 my-app 这个 Release 的当前 revision。
3. Helm 读取本地 ./my-chart。
4. Helm 读取 Chart 默认 values.yaml。
5. Helm 合并命令行传入的 values.yaml。
6. Helm 再叠加 --set image.tag=v2.0.0。
7. Helm 渲染 templates/，生成新的 manifest。
8. helm-diff 展示新旧 manifest 差异。
9. helm upgrade 把新 manifest 应用到 Kubernetes。
10. 如果存在 upgrade hooks，按生命周期执行。
11. 如果加了 --wait，Helm 等待资源就绪。
12. 成功或失败都会反映到 Release 状态和 revision 历史中。

57. 常见误区#

57.1 helm repo update 不是升级应用#

helm repo update 只是更新本地 Chart 仓库索引。它不会修改任何 Kubernetes 资源，也不会升级任何 Release。

升级应用必须使用：

helm upgrade

57.2 helm template 成功不代表安装一定成功#

helm template 只证明模板能渲染。真实安装还可能因为权限、CRD、配额、准入控制、镜像拉取、PVC、调度失败而失败。

57.3 helm uninstall --no-hooks 不是强制删除#

--no-hooks 是不执行 hooks。它不能解决所有资源删除失败问题。

57.4 Chart version 不等于应用版本#

Chart version 变了，应用镜像不一定变。应用版本变了，Chart version 也不一定自动变。生产发布时最好明确记录两者。

57.5 Release name 不是 Kubernetes 资源名的唯一来源#

很多 Chart 会用 release name 生成资源名，但最终资源名还受模板逻辑、fullnameOverride、nameOverride、namespace、labels 等影响。

57.6 values 文件不是 Kubernetes manifest#

values 文件只是输入配置，不会直接提交给 Kubernetes。真正提交的是模板渲染后的 manifest。

58. 建议的学习路径#

如果你已经掌握了常用命令，建议按这个顺序补概念：

1. 先理解 Chart、values、template、manifest 的关系。
2. 再理解 Release、revision、history、rollback。
3. 然后学习 Repository、Artifact Hub、OCI registry。
4. 接着学习 dependency、subchart、Chart.lock。
5. 最后再深入 hooks、CRD、插件、生产排障。

核心主线可以记成：

找 Chart -> 配 values -> 渲染 manifest -> 创建 Release -> 通过 revision 管理生命周期

59. 资料来源#

• Helm Using Helm
• Helm Charts
• Helm Values Files
• Helm Values Best Practices
• Helm Built-in Objects
• Helm Chart Repository Guide
• Helm OCI-based Registries
• Helm Chart Hooks
• Helm install command
• Helm upgrade command