helm —— K8s 应用包管理器

一句话定义

helm 把"一坨 K8s yaml + 一份 values"打包成 Chart，让你用 helm install 一键部署、helm upgrade 升级、helm rollback 回滚。是 K8s 生态里最普及的"应用包格式"——Cilium、Prometheus、Grafana、Argo CD、ingress-nginx 等几乎所有主流组件都用 helm chart 发布。

典型场景

训练营文档里 helm 出场 55 次，主要在 Day4-9 装各种组件：

# 装 ingress-nginx
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx -n ingress-nginx --create-namespace

# 装 Prometheus 全家桶
helm install prom prometheus-community/kube-prometheus-stack \
  -n monitoring --create-namespace \
  -f my-values.yaml

# 看一个 release 装了什么
helm get manifest prom -n monitoring | head -100

# 改配置升级
helm upgrade prom prometheus-community/kube-prometheus-stack \
  -n monitoring -f my-values.yaml

# 回滚
helm rollback prom 1 -n monitoring

Helm 的核心概念

Chart       ←  应用模板（一堆 yaml + values 默认值）
  ↓ + values.yaml
Release     ←  一次具体部署（chart + values 的实例）
  ↓ stored in
Secret/CM   ←  K8s 集群里记录这个 release 的状态（在某 ns 的 secret 里）

概念	类比
Chart	Docker 镜像 / npm 包 / apt 包
Release	安装实例（同一个 chart 可以 `helm install` 多次）
Repository	Chart 源（类似 Docker Hub / npm registry）
values	部署时的配置（chart 的"环境变量"）

五大动作（90% 用法）

1. `repo` —— 管理仓库

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo add cilium https://helm.cilium.io
helm repo list                              # 列已加的 repo
helm repo update                            # 同步最新 chart 列表
helm repo remove bitnami

每个 chart 安装前一般要先 repo add + repo update。

2. `search` —— 找 chart

helm search repo nginx                      # 在已加的 repo 里找
helm search repo nginx --versions           # 列所有版本
helm search hub nginx                       # 在 Artifact Hub 上找（含未加的）

3. `install` —— 部署

helm install <release-name> <chart> [flags]

常用形态：

# 最常见：用 repo 里的 chart
helm install nginx bitnami/nginx -n web --create-namespace

# 指定版本（生产强烈推荐——别用 latest）
helm install nginx bitnami/nginx --version 15.4.0 -n web

# 自定义 values
helm install nginx bitnami/nginx -n web \
  -f values-prod.yaml \                     # values 文件
  --set replicaCount=3 \                    # 命令行 set
  --set image.tag=1.25

# 本地 chart 目录
helm install nginx ./my-chart -n web

# tarball
helm install nginx nginx-15.4.0.tgz

# 远程 URL
helm install nginx https://...nginx-15.4.0.tgz

-n <ns> 是要指定的目标 namespace，helm 不像 kubectl 自动 default——不指定就部到 default。

4. `upgrade` —— 升级 / 改配置

helm upgrade nginx bitnami/nginx -n web -f values-prod.yaml

# upsert：装过就升、没装过就装（最常用，幂等）
helm upgrade --install nginx bitnami/nginx -n web -f values-prod.yaml

# 短写
helm upgrade -i nginx bitnami/nginx -n web -f values-prod.yaml

upgrade --install (或 -i) 应该是脚本里的默认形态。比单独 install 安全：

第一次跑 → 安装
之后跑 → 升级
不需要预先判断 release 是否存在

5. `rollback` —— 回滚

helm history nginx -n web                   # 看历史 revision
# REVISION  UPDATED                   STATUS      CHART
# 1         2026-05-27 10:00:00      superseded   nginx-15.0.0
# 2         2026-05-27 11:00:00      superseded   nginx-15.1.0
# 3         2026-05-27 12:00:00      deployed     nginx-15.4.0   ← 当前

helm rollback nginx 1 -n web                # 回到 revision 1
helm rollback nginx 0 -n web                # 0 表示上一个

values 是 helm 的灵魂

每个 chart 都有 values.yaml 作为默认配置。绝大多数 chart 都有几十到几百个可配置项。

看 chart 默认 values

helm show values bitnami/nginx                          # 看全部默认
helm show values bitnami/nginx | grep -i resource       # 找某段
helm show values bitnami/nginx > defaults.yaml          # 保存看
helm show readme bitnami/nginx                          # 文档
helm show chart bitnami/nginx                           # 元数据

写自己的 values

只写要覆盖的部分（不用复制整个 defaults）：

# values-prod.yaml
replicaCount: 3

image:
  tag: "1.25"

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

ingress:
  enabled: true
  hostname: nginx.prod.example.com

helm install nginx bitnami/nginx -f values-prod.yaml

`--set` 命令行覆盖

helm install nginx bitnami/nginx \
  --set replicaCount=3 \
  --set image.tag=1.25 \
  --set ingress.hostname=nginx.prod.example.com

--set 用点号表示嵌套。

多文件 + `--set` 组合（按顺序合并）

helm install x mychart \
  -f values-base.yaml \           # 基础
  -f values-prod.yaml \           # 环境覆盖
  --set debug=true                # 命令行最后一道覆盖

合并顺序：后面的覆盖前面的，--set 最后。

看 helm 即将生成什么：`template`

helm template nginx bitnami/nginx -f values-prod.yaml > rendered.yaml
# 不装，只渲染 → 输出最终 yaml

helm template nginx bitnami/nginx -f values-prod.yaml | kubectl apply -f -
# 用 helm 渲染 + 直接 kubectl apply（绕过 helm release）

template 是调试 chart 必备：在 install 之前先看会生成什么。

`--debug` + `--dry-run`

helm install nginx bitnami/nginx --dry-run --debug -f values-prod.yaml
# 模拟安装并打印渲染结果（含 helm hooks）

dry-run 和 template 区别：

template —— 纯客户端渲染
dry-run —— 发到 apiserver 做 validation（更严格，会查 admission webhook）

写新 chart 时 dry-run 更安全。

看已安装的 release

helm list                            # 当前 ns
helm list -A                          # 所有 ns
helm list -n monitoring               # 指定 ns
helm list --all                       # 含失败的、卸载未清理的

输出：

NAME    NAMESPACE   REVISION  UPDATED                STATUS    CHART          APP VERSION
prom    monitoring  3         2026-05-27 12:00:00    deployed  kube-prom-...  v0.65.0

详查某 release

helm status prom -n monitoring                       # 状态 + 安装时输出
helm get values prom -n monitoring                   # 看用了哪些 values
helm get values prom -n monitoring --all             # 含默认值
helm get manifest prom -n monitoring                 # 看生成的所有 yaml
helm get manifest prom -n monitoring | head -100
helm get notes prom -n monitoring                    # 安装时的 NOTES.txt
helm get hooks prom -n monitoring                    # 钩子（pre/post-install 等）

排查 release 行为不对：

helm get manifest prom -n monitoring | grep -A 20 'kind: Deployment'
# 看 helm 实际给你下发了什么

卸载

helm uninstall nginx -n web                          # 卸载
helm uninstall nginx -n web --keep-history           # 保留历史（万一想 rollback）

uninstall 默认删除所有 release 产生的 K8s 资源。但有时会留尾巴：

PVC 通常不删（数据保护，要手动）
CRD 通常不删（防止破坏其它依赖此 CRD 的资源）
自己生成的 secret / configmap 不一定清

# 看是否真的清干净
kubectl get all,pvc,secret,configmap,crd -n web -l app.kubernetes.io/instance=nginx

Chart 仓库 / 私有 chart

用本地 chart

helm install x ./my-chart                # 本地目录
helm install x ./my-chart-1.0.0.tgz      # 本地 tarball

打包

helm lint ./my-chart                     # 检查语法
helm package ./my-chart                  # 输出 my-chart-1.0.0.tgz

推到 OCI registry（K8s 推荐方式）

helm registry login registry.example.com
helm push my-chart-1.0.0.tgz oci://registry.example.com/charts
helm pull oci://registry.example.com/charts/my-chart --version 1.0.0
helm install x oci://registry.example.com/charts/my-chart --version 1.0.0

新版 helm（v3.8+）支持 OCI artifact，不用再单独搭 ChartMuseum / Harbor chart repo。

实战例子

例 1：装 Prometheus 全家桶

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

# 先看默认 values，找你要改的字段
helm show values prometheus-community/kube-prometheus-stack > defaults.yaml
less defaults.yaml

# 写自己的 values
cat > prom-values.yaml <<'EOF'
grafana:
  adminPassword: changeme
  ingress:
    enabled: true
    hosts:
      - grafana.example.com
prometheus:
  prometheusSpec:
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: local-path
          resources:
            requests:
              storage: 50Gi
EOF

# upsert（幂等）
helm upgrade -i prom prometheus-community/kube-prometheus-stack \
  -n monitoring --create-namespace \
  -f prom-values.yaml

例 2：用 `helm template` 给 GitOps 用

很多团队用 helm 写 chart、但部署用 Argo CD（不直接 helm install）：

helm template my-app ./my-chart -f values-prod.yaml > manifests/all.yaml
git add manifests/all.yaml
git commit -m "deploy"
# Argo CD 监听 git，自动 apply

这样把 helm 当成"模板引擎"，rollback 走 git revert。

例 3：dry-run 验改动

helm upgrade prom prometheus-community/kube-prometheus-stack \
  -n monitoring -f prom-values.yaml --dry-run | grep -B 1 -A 5 image:
# 检查镜像 tag 改对没

常见踩坑

坑 1：忘了 `-n <ns>`，部到了 default

helm install nginx bitnami/nginx                     # 部到了 default ns
helm uninstall nginx -n web                          # web 里找不到
helm list -A                                          # 噢，在 default

养成 -n 习惯。或者用 kubens 切默认 ns。

坑 2：`--set` 把数组覆盖了不是合并

# values.yaml
args: ["--verbose", "--port=8080"]

helm upgrade x ./chart --set args[0]="--new"
# 结果：args 整个数组被覆盖成 ["--new"]

数组类配置用 -f values.yaml 而不是 --set，更直观也避免坑。

坑 3：升级时 immutable 字段冲突

helm upgrade x ./chart
# Error: ... field is immutable

某些字段（service 的 clusterIP、deployment 的 selector）一旦设了就不能改。修：

改的话先 uninstall + reinstall
或者 --force（用 delete + create 替代 patch；会断服务）

坑 4：CRD 升级问题

CRD 在 helm 里是个特殊存在：

Chart/crds/ 下的 CRD —— 只在 install 时安装，upgrade 不动
templates/ 里的 CRD —— 正常 templating

升级 chart 时如果 CRD 也升了，helm 不会自动升 CRD。要手动：

helm pull bitnami/something --untar
kubectl apply -f something/crds/
helm upgrade ...

或者新版有 hook 处理，看 chart 文档。

坑 5：`helm uninstall` 卡住

helm uninstall x -n foo
# 卡在那里

通常是 K8s 删除某个资源卡 finalizer。

# 先看哪些资源没删
kubectl get all,pvc,secret -n foo

# 强删卡住的资源
kubectl patch <res> <name> -n foo -p '{"metadata":{"finalizers":[]}}' --type=merge

坑 6：用 `--reuse-values` 行为不对

helm upgrade x ./chart --set debug=true --reuse-values

--reuse-values 复用上次的 values 再叠新 --set。但新版 chart 的默认值变了——这种叠加可能让你跑老配置 + 新 chart 模板，行为很怪。

推荐：每次都明确 -f values.yaml（values 存 git）；--reuse-values 只在你确定要的时候用。

坑 7：使用 `latest`

helm install x mychart            # 默认装最新版

下次别人或你自己跑同一条命令，可能拿到不同版本。生产明确 --version 1.2.3，配 git 一起管。

坑 8：chart 自带的 hook 把你的资源删了

某些 chart 在 pre-upgrade hook 里跑 job、生成新证书 / 清理旧资源。升级失败时这些 hook 可能让数据丢。

读 chart 的 templates 找 helm.sh/hook annotation 看有哪些 hook：

helm get hooks x -n foo

升级前对有状态服务做备份。

helm + values 的版本管理建议

把 values 文件放 git：

infra/
├── helm-releases/
│   ├── prometheus/
│   │   ├── values.yaml          ← 共用
│   │   └── values-prod.yaml      ← prod 覆盖
│   └── ingress-nginx/
│       └── values.yaml
└── Makefile / scripts / argocd-app.yaml

部署脚本：

prom:
	helm upgrade -i prom prometheus-community/kube-prometheus-stack \
	  -n monitoring --create-namespace \
	  --version 55.5.0 \
	  -f helm-releases/prometheus/values.yaml \
	  -f helm-releases/prometheus/values-prod.yaml

这样 chart 版本 + values + 命令全都在 git，rollback 走 git revert + 重跑 make。

关联命令

kubectl —— helm 本质是生成 yaml + kubectl apply 的封装
kustomize —— 另一种打包方式（K8s 原生，比 helm 简单但弱）
jq —— helm get manifest | yq 处理 yaml
yq —— YAML 版 jq，配 helm template 二次过滤
Argo CD / Flux —— GitOps 工具，常用 helm chart 作 source