Helm 基础命令

Helm 是 Kubernetes 的包管理工具,常用的命令按使用场景归类如下。

1. 命令总览

类别	命令
仓库管理	`helm repo`
Chart 搜索/拉取	`helm search` / `helm pull` / `helm show`
安装/升级/回滚	`helm install` / `helm upgrade` / `helm rollback`
卸载	`helm uninstall`
查询	`helm list` / `helm status` / `helm get`
模板渲染	`helm template`
Chart 制作	`helm create` / `helm package` / `helm lint`
依赖管理	`helm dependency`
插件	`helm plugin`
测试	`helm test`

2. 仓库管理(Repo)

# 添加仓库
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add stable https://charts.helm.sh/stable
helm repo add aliyun https://kubernetes.aliyun.com/charts
helm repo add harbor https://harbor.example.com/chartrepo/myproject \
  --username admin --password Harbor12345

# 列出已添加的仓库
helm repo list

# 更新仓库索引(拉取最新 chart 信息)
helm repo update

# 删除仓库
helm repo remove aliyun

# 查找某个 chart
helm search repo nginx
helm search repo nginx --versions
helm search hub nginx      # 在 Artifact Hub 全网搜索

3. Chart 信息查看(Show)

# 查看 chart 详情(替换 helm2 的 inspect)
helm show chart bitnami/nginx
helm show values bitnami/nginx
helm show all bitnami/nginx          # 包含 README + values + chart
helm show readme bitnami/nginx

4. 拉取 Chart(Pull)

# 拉取 chart 到当前目录
helm pull bitnami/nginx

# 指定版本
helm pull bitnami/nginx --version 15.5.0

# 拉取并解压(--untar)
helm pull bitnami/nginx --untar --version 15.5.0

# 下载到指定目录
helm pull bitnami/nginx --untar --version 15.5.0 -d /tmp/charts

5. 安装(Install)

# 最简单安装
helm install my-nginx bitnami/nginx

# 指定 namespace
helm install my-nginx bitnami/nginx -n my-ns --create-namespace

# 自动生成 release 名
helm install bitnami/nginx --generate-name

# 指定 values 文件
helm install my-nginx bitnami/nginx -f values.yaml -f prod-values.yaml

# 命令行覆盖单个值
helm install my-nginx bitnami/nginx --set replicaCount=3

# 干跑(只渲染,不真正部署)
helm install my-nginx bitnami/nginx --dry-run --debug

# 客户端管理 release 命名(2024 年 v3.14 引入)
helm install my-nginx bitnami/nginx --take-ownership

# 不等待 Pod 就绪,直接返回
helm install my-nginx bitnami/nginx --no-hooks

实战提示:生产环境强烈建议先 helm template 干跑,确认渲染结果再 install。

6. 升级(Upgrade)

# 升级 release(不存在则安装)
helm upgrade my-nginx bitnami/nginx

# 等价于 install + upgrade 的组合
helm upgrade --install my-nginx bitnami/nginx -n my-ns

# 指定新版本 / 新 values
helm upgrade my-nginx bitnami/nginx \
  --version 15.5.1 \
  -f values.yaml \
  --set image.tag=v2.0.0

# 强制替换(清理 hook 残留)
helm upgrade my-nginx bitnami/nginx --force

# 升级时重用已有 values
helm upgrade my-nginx bitnami/nginx --reuse-values

# 干跑升级
helm upgrade my-nginx bitnami/nginx --dry-run --debug

# 升级时记录备注(给历史回滚留线索)
helm upgrade my-nginx bitnami/nginx --history-max 10

关键:helm upgrade --install 是最常用的"幂等部署"姿势,新装或升级都走它。

7. 回滚(Rollback)

# 列出 release 历史版本
helm history my-nginx -n my-ns

# 回滚到上一个版本
helm rollback my-nginx -n my-ns

# 回滚到指定版本
helm rollback my-nginx 3 -n my-ns

# 干跑回滚
helm rollback my-nginx 3 --dry-run --debug

# 强制回滚(即使当前版本不健康)
helm rollback my-nginx 3 --force

8. 卸载(Uninstall)

# 卸载 release
helm uninstall my-nginx -n my-ns

# 保留历史记录(默认保留)
helm uninstall my-nginx -n my-ns --keep-history

# 干跑卸载
helm uninstall my-nginx -n my-ns --dry-run

# 彻底清理历史
helm uninstall my-nginx -n my-ns --keep-history=false

注意:helm2 是 helm delete <name> --purge,helm3 是 helm uninstall <name>,不要混用。

9. 列表与状态(List / Status)

# 列出当前 namespace 下的 release
helm list
helm list -n my-ns

# 列出所有 namespace
helm list --all-namespaces

# 包含已卸载的(需 --keep-history)
helm list --uninstalled

# 过滤部署状态
helm list --deployed
helm list --failed
helm list --pending
helm list --superseded

# 指定 selector
helm list -l app=nginx

# 查看 release 详细状态
helm status my-nginx -n my-ns
helm status my-nginx -n my-ns --show-resources    # 同时输出资源状态
helm status my-nginx -n my-ns --revision 3         # 看历史版本状态

10. 渲染模板(Template)

# 本地渲染 chart,只输出 YAML,不部署(等于 --dry-run --debug)
helm template my-nginx bitnami/nginx

# 指定 values
helm template my-nginx bitnami/nginx -f values.yaml --set replicaCount=2

# 渲染并直接 kubectl apply
helm template my-nginx bitnami/nginx | kubectl apply -f -

# 输出到文件
helm template my-nginx bitnami/nginx > rendered.yaml

CI/CD 最佳实践:用 helm template 做静态检查,再 helm upgrade --install。

11. 查看渲染后的清单(Get)

# 查看 release 实际部署的清单
helm get manifest my-nginx -n my-ns

# 查看使用的 values
helm get values my-nginx -n my-ns
helm get values my-nginx -n my-ns --revision 2

# 查看 hook
helm get hooks my-nginx -n my-ns

# 查看全部信息(manifest + values + hooks + notes)
helm get all my-nginx -n my-ns

12. Chart 制作(Create / Package / Lint)

# 创建 chart 骨架
helm create mychart
# 生成的目录:
# mychart/
# ├── Chart.yaml
# ├── values.yaml
# ├── templates/
# ├── charts/        # 依赖
# └── .helmignore

# 校验 chart 语法
helm lint mychart

# 校验 + 指定 values
helm lint mychart -f my-values.yaml

# 打包 chart(生成 .tgz)
helm package mychart
helm package mychart --version 1.0.0 --app-version 2.3.4

# 把 chart 推到仓库(需要 helm-push 插件)
helm cm-push mychart-1.0.0.tgz harbor

13. 依赖管理(Dependency)

# 在 Chart.yaml 中声明依赖
# dependencies:
#   - name: postgresql
#     version: 12.1.7
#     repository: https://charts.bitnami.com/bitnami

# 根据 Chart.yaml 下载依赖到 charts/ 目录
helm dependency update mychart

# 列出依赖
helm dependency list mychart

# 构建依赖(打包)
helm dependency build mychart

14. 插件(Plugin)

# 列出已装插件
helm plugin list

# 安装插件
helm plugin install https://github.com/chartmuseum/helm-push
helm plugin install https://github.com/databus23/helm-diff

# 升级插件
helm plugin update diff

# 卸载插件
helm plugin uninstall diff

# 常用插件
# - helm-diff:升级前看差异
# - helm-push(helm-cm-push):推 chart 到 chartmuseum
# - helm-secrets:用 sops 加密 values
# - helm-git:从 git 仓库装 chart
# - helm-s3:从 s3 仓库装 chart

15. 测试(Test)

# 跑 chart 自带的 test pod
helm test my-nginx -n my-ns

# 打印测试结果但不执行
helm test my-nginx --logs

chart 里需要在 templates/ 下放 test-connection.yaml 这样的 pod 资源,带 helm.sh/hook: test 注解。

16. 实战组合用法

16.1 干跑看差异(CI/CD 必用)

# 升级前用 helm-diff 看变化
helm diff upgrade my-nginx bitnami/nginx -f values.yaml

# 没有 helm-diff 插件时,用 template 模拟
diff <(helm get manifest my-nginx) \
     <(helm template my-nginx bitnami/nginx -f values.yaml)

16.2 批量回滚

# 把所有 release 回滚到上一版
for r in $(helm list -q); do
  echo "rolling back $r..."
  helm rollback "$r"
done

16.3 批量导出所有 release 的 manifest

helm list -q | xargs -I {} sh -c 'echo "=== {} ==="; helm get manifest {}'

16.4 给 release 加备注(便于审计)

helm install my-nginx bitnami/nginx \
  --set-string notes="deployed by CI run #1234"

16.5 等待 release 部署完成

helm 本身没有 wait 子命令,但可结合 kubectl 实现:

helm upgrade --install my-nginx bitnami/nginx
kubectl wait --for=condition=Available \
  deployment/my-nginx -n my-ns --timeout=5m

或用 helm-diff / helm-status 配合自定义脚本。

16.6 多 values 文件优先级

helm install my-nginx bitnami/nginx \
  -f base-values.yaml \
  -f prod-values.yaml \
  --set replicaCount=5

优先级:命令行 --set > 后面的 -f > 前面的 -f > values.yaml。

16.7 升级时跳过某些 hook

helm upgrade my-nginx bitnami/nginx --no-hooks

17. 常用环境变量

# kubeconfig 路径(默认 ~/.kube/config)
export KUBECONFIG=/path/to/kubeconfig

# helm 缓存目录(默认 ~/.cache/helm)
export HELM_CACHE_HOME=/tmp/helm-cache

# helm 配置目录(默认 ~/.config/helm)
export HELM_CONFIG_HOME=/tmp/helm-config

# helm 数据目录(默认 ~/.local/share/helm)
export HELM_DATA_HOME=/tmp/helm-data

# 指定 namespace(替代 -n)
export HELM_NAMESPACE=my-ns

# 启用 debug 日志
export HELM_DEBUG=true

18. 常见错误与排查

错误信息	原因	解决
`Error: INSTALLATION FAILED: rendered manifests contain a resource that already exists`	资源已存在且非 chart 管理	用 `kubectl delete` 删旧资源,或加 `--force`
`Error: another operation (install/upgrade/rollback) is in progress`	上一次操作未完成	删掉 `kubectl get configmap -n kube-system sh.helm.release.v1.<release>.v<rev>` 重建
`Error: failed to download chart`	repo 没更新	`helm repo update`
`Error: rendered manifests contain a resource that already exists. Unable to continue with install`	资源冲突	加 `--set` 改名字,或用 `helm upgrade --install`
`Error: validation: chart.metadata is required`	Chart.yaml 缺失	`helm create` 重新生成

19. helm2 vs helm3 命令对照

操作	helm2	helm3
安装	`helm install`	`helm install`
升级	`helm upgrade`	`helm upgrade`
回滚	`helm rollback`	`helm rollback`
卸载	`helm delete --purge`	`helm uninstall`
查看清单	`helm get manifest`	`helm get manifest`
查看 chart	`helm inspect`	`helm show`
拉取 chart	`helm fetch`	`helm pull`
必须 release 名	否	是(或 `--generate-name`)
客户端	helm + Tiller	helm + kubeconfig

20. 速记

装/升:helm upgrade --install 是最稳的幂等姿势
看:helm list + helm status + helm get all 三件套
干跑:helm template 渲染,--dry-run --debug 模拟
仓库:add → update → search → pull → install
回滚:helm history 看版本号,helm rollback <name> <rev> 回指定版
CI/CD:helm diff 升级前看差异,kubectl wait 升级后等就绪