Helm 操作手册

Helm 管理 chart 的 release 历史，Kubernetes 管理运行资源。先记录集群、namespace、release、chart 版本与 values 来源，才能解释“升级成功但行为没变”。示例使用本地 ./chart，执行前换成经过审阅的 chart。

当前任务	入口
看当前装了什么	版本与配置来源
改 values 后发布	先渲染再发布
升级失败或回滚	历史与恢复范围

四种配置视图不要混用

固定版本与发布对象

# 确认本机 Helm 主版本
helm version --short

下文 your-context、default、web 分别是 context、namespace、release 的示例，每条命令显式指定。用 kubectl config get-contexts 核对 context；不要将 chart 名误当成 release 名。

# 包括失败和 pending 状态，列出目标 namespace 的 release
helm list --kube-context your-context -n default --all

查看 NAME、REVISION、STATUS、CHART 与 APP VERSION；CHART 版本和应用版本不是同一个概念。

# 读取该 release 的当前状态与说明
helm status web --kube-context your-context -n default

deployed 表示 Helm 记录的发布状态，不代替 Pod / 业务检查。pending 时先查仍在运行的发布任务。

按问题选择配置视图

# 读取本次 chart 包的默认值
helm show values ./chart

./chart 是准备发布的本地 chart 目录，不是 release 当前实际值。

# 读取 release 存储的用户覆盖值
helm get values web --kube-context your-context -n default

未设置过覆盖值可能为空；需要合并后值时，另选下面的 --all 查询。

# 读取默认值与用户值合并后的结果
helm get values web --all --kube-context your-context -n default

确认目标字段的最终值；这些是该 release 配置，不是控制器当前内存状态。输出可能含敏感配置，分享前检查。

# 读取 release 保存的渲染清单
helm get manifest web --kube-context your-context -n default

与 kubectl --context your-context -n default get deployment web -o yaml 对照：API 对象可能经过默认化、控制器或人工修改。对象名依 chart 而定，从清单取得。

来源	回答的问题
helm show values ./chart	chart 作者提供的默认值
helm get values RELEASE	release 存储的用户覆盖值；--all 显示合并结果
helm get manifest RELEASE	该 revision 生成并保存的清单
kubectl get ... -o yaml	API 当前对象，可能被默认化、控制器或人工修改

values 的覆盖顺序与发布验证

正在呈现知识画面

选择本次 values 的来源

下面使用“chart 默认值 + 本次 values.yaml”，明确 --reset-values；需要继承旧值时应先导出、审阅并纳入本次输入，而不是无意保留上次配置。值文件和 chart 一起纳入版本管理，敏感值按项目密钥方案处理。

# 在发布前检查 chart 与本次 values
helm lint ./chart -f values.yaml

先解决模板/结构错误；lint 不能证明集群接纳清单或应用启动成功。

# 把本次渲染清单保存为可审阅文件
helm template web ./chart -n default -f values.yaml > rendered.yaml

目标文件会被覆盖，使用本次工作目录。检查镜像、端口、namespace、存储与 Secret；不应直接把完整输出贴入工单。

# 对照 API 当前对象审阅发布差异
kubectl --context your-context -n default diff -f rendered.yaml

返回 1 通常表示有差异。此处只借用 kubectl 比较；实际发布仍由 Helm 执行，避免两套管理方式交错写入。

# 发布已审阅配置，并等待资源达到等待条件
helm upgrade --install web ./chart \
  --kube-context your-context -n default \
  -f values.yaml --reset-values --wait --timeout 5m

namespace 需已存在；--install 允许首次安装，--wait/--timeout 控制等待，不是业务测试或自动回滚。完成后检查 helm status、Pod Events 和实际请求；失败先保留证据并进入恢复流程。

这里明确从 chart 默认值和本次 values 构建配置，不无意继承旧 release 的值。多个 -f 按从左到右覆盖，--set 优先级更高；列表通常整体替换，不能把数组当成按元素补丁。通过仓库或 OCI 安装时固定 chart 版本，并审阅来源。

template 是本地渲染，不证明 API 支持、admission 接受或运行成功；lookup 等依赖集群的模板还会有差异。upgrade --dry-run 的客户端/服务端形式随版本确认，输出可能含 Secret。Helm 3 的 --atomic 与 Helm 4 的失败回滚选项不同，先看本机 helm upgrade --help，不要混用版本参数。

回滚 release，不等于回滚全部业务状态

回滚前读历史与目标输入

# 找出目标 revision 的时间、状态和 chart 版本
helm history web --kube-context your-context -n default

不要假定 revision 2 正常；先确认上一次业务验证通过的版本。

# 读取候选 revision 的用户值
helm get values web --revision 2 --kube-context your-context -n default

再以 helm get manifest web --revision 2 加相同 context / namespace 检查实际镜像与对象；要恢复的数据状态需要单独方案。

# 把已核对的 revision 作为新一次恢复发布
helm rollback web 2 --kube-context your-context -n default --wait --timeout 5m

将 2 替换为确认值；成功后用 history 查看新增 revision，再查 status、Pod 与业务。回滚失败先读 Events / hook Job 日志，不直接删除 release 存储对象。

revision 2 是示例，先确认其中镜像和 values。回滚会形成新的 release revision；PVC 数据、外部服务、hook 的副作用和数据库迁移不能依赖 Helm 自动逆转。pending 状态先查是否仍有发布进程、Job/Pod Events 和 release 历史，不直接删 release Secret 解锁。

查询仓库版本与使用说明

# 确认已配置的传统 chart 仓库与 URL
helm repo list

仓库更新以 helm repo update 单独执行，只刷新本地索引，不升级已安装 release。OCI 引用不依赖 repo list 的索引。

# 查找可用 chart 版本，选择并固定目标
helm search repo web --versions

实际从 repo/chart 安装时加 --version VERSION；VERSION 从此清单选择，安装前用相同版本 show values/template 审阅。

# 读取 chart 为当前 release 提供的访问说明
helm get notes web --kube-context your-context -n default

说明中的地址和密码获取方式仍要与实际资源核对；notes 不是运行健康证明。

卸载是删除资源的独立任务

# 删除已确认可退役的 release 管理资源
helm uninstall web --kube-context your-context -n default --wait --timeout 5m

执行前审阅 manifest、hook、PVC/CRD 与备份；成功后以 helm list --all 和 kubectl 逐项确认残留。--keep-history 是备选的历史保留策略，不是数据保留策略。

卸载用 helm uninstall RELEASE -n NAMESPACE 并固定 context；先读 chart 对 PVC、CRD、hook 和 external 资源的策略。--keep-history 只保留 release 历史，不等于保留全部 Kubernetes 资源或数据。

helm upgrade · helm rollback · Values files