安装、升级与回滚

核心问题：Helm 怎样管理应用的完整生命周期——首次安装、版本升级、配置变更，以及出问题时快速回滚？

Helm Release 生命周期

每次 install / upgrade / rollback 都创建一个新的 Release 修订版本（Revision），历史记录保存在集群的 Secret 中。

helm install

# 基本安装
helm install <release-name> <chart> [flags]
# 示例：安装到 production 命名空间，使用自定义 values
helm install my-api ./my-app \
--namespace production \
--create-namespace \
-f values/prod.yaml \
--set image.tag=v1.2.3 \
--set replicaCount=3
# 等待部署完成（readiness 通过）
helm install my-api ./my-app \
--namespace production \
-f values/prod.yaml \
--wait \
--timeout 5m
# 如果已存在则升级，不存在则安装（CI 常用）
helm upgrade --install my-api ./my-app \
--namespace production \
--create-namespace \
-f values/prod.yaml \
--wait

helm upgrade

# 升级应用版本
helm upgrade my-api ./my-app \
--namespace production \
-f values/prod.yaml \
--set image.tag=v1.3.0 \
--wait
# 只更新配置，不改镜像
helm upgrade my-api ./my-app \
--namespace production \
-f values/prod.yaml \
--reuse-values \        # 复用上次安装时的所有 values
--set config.logLevel=debug
# 升级失败自动回滚
helm upgrade my-api ./my-app \
--namespace production \
-f values/prod.yaml \
--wait \
--atomic              # 失败时自动回滚到上一个稳定版本
# 清理旧版本 Secret（保留最近 5 个修订）
helm upgrade my-api ./my-app \
--namespace production \
-f values/prod.yaml \
--history-max 5

helm rollback

# 查看 Release 历史
helm history my-api -n production
# REVISION  UPDATED          STATUS     CHART         APP VERSION  DESCRIPTION
# 1         2026-03-10 ...   superseded my-app-1.0.0  v1.1.0       Install complete
# 2         2026-03-15 ...   superseded my-app-1.1.0  v1.2.0       Upgrade complete
# 3         2026-03-20 ...   deployed   my-app-1.2.0  v1.3.0       Upgrade complete
# 回滚到上一个版本
helm rollback my-api -n production
# 回滚到指定修订版本
helm rollback my-api 2 -n production --wait
# 强制重建（解决资源状态异常）
helm rollback my-api 2 -n production --force

值的优先级（从高到低）

# 命令行 --set（最高优先级）
helm install my-api ./my-app \
-f values/base.yaml \         # 先加载
-f values/prod.yaml \         # 覆盖 base
--set image.tag=v1.3.0 \     # 最高优先级，覆盖所有文件
--set-string config.flag=true  # 强制字符串类型

多 values 文件组合（推荐模式）

values/
├── base.yaml          # 公共默认值（所有环境共用）
├── dev.yaml           # 开发环境差异
├── staging.yaml       # 测试环境差异
└── prod.yaml          # 生产环境差异

# 开发环境
helm upgrade --install my-api ./my-app -n dev \
-f values/base.yaml -f values/dev.yaml
# 生产环境
helm upgrade --install my-api ./my-app -n production \
-f values/base.yaml -f values/prod.yaml \
--set image.tag=$CI_COMMIT_SHA

管理第三方 Chart

# 添加仓库
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update      # 更新本地缓存
# 搜索 Chart
helm search repo postgresql
helm search hub nginx   # 搜索 Artifact Hub
# 查看 Chart 的 values 参数
helm show values bitnami/postgresql
helm show values bitnami/postgresql > postgresql-values.yaml  # 保存为文件再修改
# 安装 PostgreSQL
helm upgrade --install postgres bitnami/postgresql \
--namespace production \
--version 13.2.0 \          # 锁定 Chart 版本！
-f postgresql-values.yaml

Helmfile：多 Chart 统一管理

当一个环境需要安装多个 Chart 时，用 Helmfile 统一管理：

# helmfile.yaml
repositories:
- name: bitnami
url: https://charts.bitnami.com/bitnami
- name: ingress-nginx
url: https://kubernetes.github.io/ingress-nginx
releases:
- name: ingress-nginx
namespace: ingress-nginx
chart: ingress-nginx/ingress-nginx
version: "4.8.0"
values:
- controller:
replicaCount: 2
- name: cert-manager
namespace: cert-manager
chart: jetstack/cert-manager
version: "1.13.0"
set:
- name: installCRDs
value: "true"
- name: my-api
namespace: production
chart: ./charts/my-app
values:
- values/base.yaml
- values/{{ .Environment.Name }}.yaml   # 按环境加载
set:
- name: image.tag
value: {{ env "IMAGE_TAG" | default "latest" }}
needs:
- ingress-nginx/ingress-nginx    # 依赖顺序

# 安装所有
helmfile sync
# 只安装指定 release
helmfile -l name=my-api sync
# 查看差异
helmfile diff
# 环境切换
helmfile -e staging sync

常见错误

下一节：自定义 Chart 开发