用 Helm 搜索、安装、定制与升级 Kubernetes 应用

Helm 是 Kubernetes 的包管理工具，它把一组相关的 Kubernetes 资源打包成 chart，再以 release 为单位安装到集群里。这篇教程解决的是「拿到一个 chart 之后，怎么把它装对、改对、升级对」的问题：从搜索 chart 开始，到安装、查看状态、定制参数、升级、回滚，每一步都给出可以直接执行的命令。适合已经装好 Helm 客户端、对 chart、仓库、release 这几个概念有基本了解，但还没把日常操作流程走顺的读者。如果你只是想跑几条命令看看效果，可以先从更短的快速入门走一遍；本文覆盖的是命令细节与常见用法。站内也有对应的工具页可作参考：HELM。

文中涉及的具体版本号、chart 默认值、镜像大小等信息会随 chart 与 Helm 版本变化，实际执行时请以官网与 chart 仓库的当前信息为准。

准备工作

开始之前需要确认几件事，缺一件后面的命令就跑不通。

• Helm 客户端已安装：本文假设 helm 命令已经在 PATH 中可用。可以用 helm version 确认客户端能正常执行。
• 可用的 Kubernetes 集群与 kubeconfig：Helm 通过 kubeconfig 与集群通信，安装、升级、回滚都发生在集群里。确认 kubectl get nodes 能正常返回结果。
• 目标命名空间：默认安装到 default 命名空间，需要装到别处时用 --namespace 指定。
• 至少添加一个 chart 仓库：helm search repo 只搜索本地已添加的仓库，所以要先 helm repo add。如果只想浏览公共 chart，可以跳过这一步，直接用 helm search hub。
• 对 release 命名的约定：release 名由你自己取，同一个命名空间内不能重名。不想取名时可以让 Helm 生成，见下文 --generate-name。

另外要理解三个名词，后面会反复出现：chart 是打包好的应用定义；repository 是存放 chart 的仓库；release 是 chart 在集群中的一次具体安装实例，同一个 chart 可以装出多个互不影响的 release。

操作步骤

第一步：用 helm search 找到要装的 chart

helm search 支持两类数据源，用途不同。

搜索 Artifact Hub：helm search hub 查询 Artifact Hub 上列出的 chart，覆盖大量不同仓库。例如搜索 wordpress：

helm search hub wordpress

输出包含 URL、CHART VERSION、APP VERSION 和 DESCRIPTION 几列。不加任何过滤条件时，它会列出所有可用的 chart。

需要注意，helm search hub 默认给出的是 chart 在 Artifact Hub 上的页面地址，而不是真正的 Helm 仓库地址。想拿到可以直接用于 helm repo add 的仓库 URL，加上 --list-repo-url：

helm search hub --list-repo-url wordpress

搜索本地已添加的仓库：helm search repo 只在你已经通过 helm repo add 添加的仓库里查找，查询在本地数据上完成，不需要访问公网。先添加一个仓库再搜索：

helm repo add brigade
helm search repo brigade

输出会列出该仓库下所有 chart 的名称、chart 版本、应用版本与描述，名称形如 brigade/brigade、brigade/kashti。

搜索使用模糊字符串匹配，所以只输入单词的一部分也能命中。例如输入 kash 也能找到 brigade/kashti：

helm search repo kash

找到目标 chart 之后，就可以进入安装环节。

第二步：用 helm install 安装 chart

最简单的形式接受两个参数：你为这次安装取的 release 名，以及要安装的 chart 名。

helm install happy-panda bitnami/wordpress

执行后客户端会打印一段信息，包含 NAME、LAST DEPLOYED、NAMESPACE、STATUS、REVISION 以及 NOTES。STATUS 为 deployed 表示这次 release 已部署，REVISION 为 1 表示这是第一次修订。NOTES 里通常是 chart 作者写的后续操作提示，例如如何从集群内部访问服务、如何取得外部地址、如何读取登录凭据。

安装一个 chart 会创建一个新的 release 对象，上面这个 release 就叫 happy-panda。如果不想自己取名，可以省略 release 名并加上 --generate-name，由 Helm 生成名称。

安装源不止仓库一种。 helm install 还支持：

• 本地 chart 归档包：helm install foo foo-0.1.1.tgz
• 解包后的 chart 目录：helm install foo path/to/foo
• 完整的 URL 地址

资源创建顺序。 安装过程中 Helm 按固定顺序创建资源，大致是先命名空间与策略类资源，再是账号与配置类资源，然后是存储与权限类资源，最后是工作负载与入口类资源。这个顺序的意义在于：依赖关系靠前的资源先就位，后面的工作负载才能正常引用它们。

Helm 不会等所有资源都运行起来才退出。 很多 chart 依赖体积较大的容器镜像，拉取和启动可能耗时很久，所以 helm install 返回时 Pod 可能还在启动中。这是正常行为，不代表安装失败。

第三步：用 helm status 查看 release 状态

安装完成后想确认状态，或者想重新读一遍配置信息和 NOTES，用 helm status：

helm status happy-panda

输出与安装时打印的内容一致，包含 release 名、部署时间、命名空间、状态、修订号以及 NOTES。这是排查「装完之后到底怎么样了」的第一条命令。

第四步：用 helm show values 查看可配置项

直接安装只会使用 chart 的默认配置。要改成自己需要的配置，先得知道有哪些项可以改：

helm show values bitnami/wordpress

输出是一份完整的 values 内容，以 YAML 形式列出镜像仓库、镜像标签、全局参数等所有可覆盖的键。注释里会说明哪些参数会影响依赖组件、哪些参数是全局生效的。把这份输出当作定制清单来读，比凭猜测写配置可靠得多。

第五步：用 values 文件或 --set 覆盖配置

看到可配置项之后，把要改的值写进一个 YAML 文件，安装时用 -f 传入。例如：

echo '{mariadb.auth.database: user0db, mariadb.auth.username: user0}' > values.yaml
helm install -f values.yaml bitnami/wordpress --generate-name

这个例子的效果是：创建一个名为 user0 的 MariaDB 用户，并授予它访问新建 user0db 数据库的权限，其余配置全部沿用 chart 默认值。

传配置有两种方式：

• --values（简写 -f）：指定一个包含覆盖值的 YAML 文件。可以指定多次，最右边的文件优先级最高。
• --set：在命令行上直接指定覆盖值。

两者同时使用时，--set 的值会合并进 --values 的结果，并且优先级更高。通过 --set 设置的值会持久化保存在一个 Secret 中，可以用 helm get values <release-name> 查看某个 release 被 --set 覆盖过哪些值。想清除这些覆盖值，在 helm upgrade 时加上 --reset-values。

第六步：掌握 --set 的写法与限制

--set 接受零个或多个「名称=值」对。最简形式 --set name=value 等价于 YAML 中的：

name: value

多个值用逗号分隔，--set a=b,c=d 等价于：

a: b
c: d

嵌套结构用点号表达，--set outer.inner=value 等价于：

outer:
  inner: value

列表用花括号表达，--set name={a, b, c} 等价于：

name:
  - a
  - b
  - c

某个键可以设为 null 或空数组 []。例如 --set name=[],a=null 会把原本的列表清空、把 a 置为 null。

列表元素还可以用数组下标语法访问。例如 --set servers[0].port=80 等价于：

servers:
  - port: 80

同一行里设置多个下标值，--set servers[0].port=80,servers[0].host=example 等价于：

servers:
  - port: 80
    host: example

特殊字符要转义。 值里本身含逗号时，用反斜杠转义，--set name=value1\,value2 会得到 name: "value1,value2"。点号序列同样可以转义，这在 chart 用 toYaml 解析注解、标签和节点选择器时很有用。例如 --set nodeSelector."kubernetes\.io/role"=master 会得到：

nodeSelector:
  kubernetes.io/role: master

--set 的局限。 深层嵌套的数据结构用 --set 表达起来很吃力。chart 作者在设计 values.yaml 的格式时，应当把 --set 的使用场景考虑进去；作为使用者，遇到层级很深的配置，优先写 values 文件而不是硬拼命令行。

第七步：用 helm upgrade 升级 release

chart 发布了新版本，或者你想改已有 release 的配置，用 helm upgrade。它接收一个已存在的 release，按你提供的信息升级它。

helm upgrade -f panda.yaml happy-panda bitnami/wordpress

上面这条命令用同一个 chart 升级 happy-panda，同时传入新的 YAML 文件，其中把 mariadb.auth.username 改成了 user1。

因为 Kubernetes 的 chart 可能很大很复杂，Helm 会尽量做侵入性最小的升级：只更新自上次 release 以来发生变化的部分，而不是推倒重来。

升级后想确认新值是否生效，用 helm get values：

helm get values happy-panda

输出会显示 mariadb.auth.username: user1，说明新配置已经部署到集群。helm get 系列命令是查看集群中某个 release 实际配置的常用手段。

第八步：失败时用 helm rollback 回滚

升级不顺利时，Helm 提供了回滚能力，把 release 退回到之前的某个修订版本。回滚以修订号为目标，修订号可以从 helm status 或 helm history 的输出里看到。回滚之后同样可以用 helm status 确认当前状态与修订号。

回滚的价值在于：升级前的配置与资源状态被记录为历史修订，不需要手工把 values 文件改回去再重装一遍。

一个完整示例

下面把前面的步骤串成一条从搜索到回滚的完整链路。示例使用 wordpress 这个 chart，实际执行时 chart 版本与默认值请以仓库当前信息为准。

1. 搜索 chart。 先在 Artifact Hub 上找，并拿到可用于添加仓库的地址：

helm search hub --list-repo-url wordpress

2. 添加仓库并确认 chart 存在。 假设已按输出中的仓库地址添加了仓库，用本地搜索确认：

helm repo add bitnami
helm search repo wordpress

3. 查看可配置项。 把输出读一遍，确定要改哪些键：

helm show values bitnami/wordpress

4. 写一份覆盖配置。 只写需要改的键，其余沿用默认值：

echo '{mariadb.auth.database: user0db, mariadb.auth.username: user0}' > values.yaml

5. 安装并指定 release 名。

helm install happy-panda bitnami/wordpress -f values.yaml

记下输出里的 STATUS 与 REVISION，并阅读 NOTES 中关于访问方式和凭据的提示。

6. 确认状态。

helm status happy-panda

7. 修改配置并升级。 把用户名从 user0 改成 user1，写入新文件后升级：

echo '{mariadb.auth.database: user0db, mariadb.auth.username: user1}' > panda.yaml
helm upgrade -f panda.yaml happy-panda bitnami/wordpress

8. 验证新值已生效。

helm get values happy-panda

输出中应能看到 mariadb.auth.username: user1。

9. 需要时回滚。 查看修订历史，确定要退回的修订号，然后回滚：

helm history happy-panda
helm rollback happy-panda 1

回滚后再执行一次 helm status happy-panda，确认状态与修订号符合预期。

注意事项

• helm search hub 与 helm search repo 的数据源不同。 前者查 Artifact Hub，后者只查本地已添加的仓库，且不需要公网连接。用 helm search repo 搜不到东西时，先确认仓库是否已经添加。
• hub 搜索默认不给仓库地址。 想用搜索结果去 helm repo add，必须加 --list-repo-url，否则拿到的是 Artifact Hub 页面地址。
• 安装返回不等于资源就绪。 Helm 不会等所有资源运行起来才退出，镜像较大的 chart 尤其如此。安装后应结合 helm status 与集群侧的查询确认工作负载状态。
• release 名在同一命名空间内不可重复。 重复使用会报错；不想取名时用 --generate-name。
• --set 的值会存进 Secret。 敏感信息通过 --set 传入时要注意这一点；同时可以用 helm get values 审计某个 release 被覆盖过哪些值。
• 清除 --set 覆盖要显式指定。 在 helm upgrade 时加 --reset-values 才会清除，单纯不传不会自动清掉。
• 多个 values 文件的优先级按位置决定。 -f 可以重复指定，最右边的文件覆盖左边的；--set 又覆盖所有 -f 文件。
• 特殊字符必须转义。 值中含逗号、键中含点号时，漏掉反斜杠会导致解析结果与预期不符，这是 --set 最常见的坑。
• 深层嵌套优先用 values 文件。 --set 表达深层结构既难写又易错，层级一深就改用 YAML 文件。
• 升级是增量式的。 Helm 只更新自上次 release 以来变化的部分，所以升级前确认 values 文件里写的是完整意图，而不是只写增量。
• 回滚以修订号为目标。 回滚前先用 helm history 确认要退回的修订号，回滚后再用 helm status 核对结果。

把上面这套流程走顺之后，日常使用 Helm 基本就是「搜索 → 看 values → 写覆盖 → 安装 → 查状态 → 升级 → 必要时回滚」这个循环。每一步都有对应的命令可以核对结果，不需要靠猜。