包管理器 Helm

文档用途

介绍 Kubernetes 的包管理器 Helm.
示例工程 whisperpine/my-first-chart.

简介

helm 与 k8s 的关系就像 apt/yum 之于 Linux.
如果把 k8s 当做 "云原生操作系统", 那么 helm 就是这个操作系统的 "包管理器".

使用场景

• 方便安装已经被封装成 helm chart 的第三方服务.
• 能为那些 "需要多种资源才能部署服务" 提供简单的部署方案.
• 灵活性 (开发, 测试, 生产环境的配置不同).
• 安全性 (制作 chart 时只将 "打算做调整的参数" 暴露出来).
• 可以直接将 chart 与容器镜像一同注册在云服务商.
• helm 提供了测试框架, 可以用于自动化测试.

重要概念

术语	含义
Chart	k8s 配置文件工程, 包含模板和默认值
Repository	用于存储和分享 Chart 的仓库
Release	每个 Release 都是特定 Chart 的部署实例

Helm 中的重要概念 (ChatGPT)

1. Chart（图表）：一个 Helm Chart 是一个预定义的应用程序资源的集合。它包括了在 Kubernetes 上运行一个应用程序所需的所有资源，比如部署、服务、持久卷声明等。通过使用 Helm，你可以将这些资源打包到一个易于分享和部署的单元中。
2. Repository（仓库）：Helm 仓库是一个存储和分享 Helm Charts 的地方。它可以是一个简单的 HTTP 服务器，也可以是像 Artifact Hub 这样的更复杂的系统。仓库包含了一个或多个 Helm Charts，用户可以从中获取 Charts 并部署到他们自己的 Kubernetes 环境中。
3. Release（发布）：一个 Release 是一个特定 Chart 的一个部署实例。这意味着你可以在同一个 Kubernetes 集群中多次安装相同的 Chart，每次安装都会创建一个新的 Release。Release 包括了 Chart 的版本号以及与之相关的配置信息，使得每个 Release 可以独立地管理。

简而言之，Chart 是应用程序的打包形式，Repository 是存储和分享 Charts 的地方，Release 是特定 Chart 的一个部署实例。

TIP

在使用 helm 的子命令时, 要注意区分某个命令与以上哪个概念有关.

准备工作

确保有可用的 k8s 集群, 最简单的方式是用 Docker Desktop 在本地设备中部署.
在 VS Code 中建议安装 Kubernetes 和 Yaml 插件, 方便编辑配置文件.
确保可以使用 helm 命令行工具, 通过以下命令安装:

Windows

scoop install helm

macOS

brew install helm

制作 Chart

详见 制作 Helm Chart 文档.

部署相关

仓库与搜索

# 添加 chart 仓库
helm repo add [alias] [url]
# 例如添加名为 bitnami 的 chart 仓库
helm repo add bitnami https://charts.bitnami.com/bitnami

以下命令会在所有 手动添加的 repository 中搜索:

# 在仓库中搜索
helm search repo [app-name]

Helm 有官方的 repository, 即 artifacthub.io , 无需手动添加.
想要在 artifacthub.io 中搜索, 可以使用以下命令:

# 在 https://artifacthub.io/ 中搜索
helm search hub [app-name]

安装与卸载

在添加 repository 并找到想要部署的 chart 后, 使用以下命令部署一个 release:

# 开始安装前记得更新仓库元数据
helm repo update

# [release-name] 可以任意取名, [chart] 可以是 某个 repository 中的
helm install [release-name] [chart]

# 如果不打算取名, 也可以使用 --generate-name 来自动命名
helm install --generate-name [chart]

# 使用 --values 或 -f 指定自定义的值, 用于覆盖默认值
helm install [release-name] [chart] --values my-values.yaml
# 可以多次使用 -values 或 -f 来应用多个文件中的值
helm install [release-name] [chart] -f aaa.yaml -f bbb.yaml

多种方式来指定 chart

helm install my-maria example/mariadb  # By chart reference
helm install my-nginx ./nginx-1.2.3.tgz  # By path to a packaged chart
helm install my-nginx ./nginx  # By path to an unpacked chart directory
helm install my-nginx https://example.com/charts/nginx-1.2.3.tgz  # By absolute URL
helm install --repo https://example.com/charts/ my-nginx nginx  # By chart reference and repo url
helm install my-nginx --version 1.2.3 oci://example.com/charts/nginx  # By OCI registries

TIP

为了提前确认操作的会造成的影响, 可以使用 --dry-run 选项.
默认情况下只会在本地执行, 若希望连接远程的 k8s 集群, 则需要使用 --dry-run=server.

安装完成后, 可以通过以下命令查看所有已安装的 release:

helm ls -A                # 短选项
helm ls --all-namespaces  # 长选项

通过以下命令卸载指定的 release:

# 其中 [release-name] 可以通过 helm list 命令查看
helm uninstall [release-name]

# 若希望保留历史信息, 则可以在卸载时使用 --keep-history 选项
helm uninstall --keep-history [release-name]

INFO

对于那些已经被卸载但保留的历史的 release, 可以通过 helm list --all 来找到.
如果看到 STATUS 为 uninstalled, 就是已经被卸载但保留的历史的 release.
可以进一步通过 helm get all [release-name] 来查看这个 release 的完成信息.

更新与回滚

helm upgrade 命令用于更新 release, 这可能是最常用的 helm 命令.
每次如果成功执行 helm upgrade, 那么对应的 release 中的 revision 就会 +1.

INFO

revision 记录在了 k8s 中的 secret 类型的资源中, 通过以下命令可以查看.

kubectl get secret -A --field-selector type="helm.sh/release.v1"

可以通过 --history-max 来设置上限 (若不设置或设置为 0 则没有上限).
在 helmfile 中也可以通过 releases.historyMax 字段来设置上限.

# 升级, 默认不会使用上次部署时设置的 value
helm upgrade [release] [chart]
# 升级, 并保留之前 values, 这让更新命令更简单, 也可以用于安全要求较强的场景
# (例如首次部署时的 value 包含敏感的 token, 之后更新时的命令就不再需要包含 token)
helm upgrade --reuse-values [release] [chart]

helm upgrade 命令的选项非常多, 建议通过 helm upgrade --help 查看命令提示.
如果在更新 release 之后发现有问题, 需要回滚到更新前的状态, 可以使用以下命令:

# 回滚, 默认回滚到上一个 revision
helm rollback [release]
# 回滚到指定的 revision
helm rollback [release] [revision]

# 查看某个 release 的历史
helm history [release]

查看信息

# 获取某个 release 的信息
helm get [sub-command] [release]
# 例如此命令可以查看 "非默认的 value" (部署时自定义的那些)
helm get values [release]
# 例如此命令可以查看通过模板文件生成的 k8s 配置文件
helm get manifest [release]

如果只想查看 metadata 和 notes, 则可以通过此命令完成:

# 查看某个 release 的状态
helm status [release]

# 相当于连续执行了以下两条命令
helm get metadata [release]
helm get notes [release]

Helmfile

INFO

Helm 已经极大简化服务在 k8s 中的部署, 如果想要更进一步, 可以使用 Helmfile.
参考 Helmfile 的 GitHub 仓库 helmfile/helmfile 以及 官方文档.

安装的方式

通常我们会在 CI/CD 中使用 helmfile 的官方 Docker image.
如果考虑在个人设备上安装, 为了方便使用, 建议安装命令行工具.

Docker

docker pull ghcr.io/helmfile/helmfile-debian-stable-slim

Windows

scoop install helmfile

macoS

brew install helmfile

TIP

在首次使用 helmfile 命令之前, 建议执行 helmfile init.
这将会检查必要的依赖项是否安装, 若缺失则可以进一步选择安装.

使用案例

创建名为 helmfile.yaml 的文件并编辑:
编辑完成后在当前路径下使用 helmfile apply 即可完成部署.

# helmfile.yaml
repositories:
  - name: bitnami
    url: https://charts.bitnami.com/bitnami/

releases:
  - name: nginx
    namespace: dev
    chart: bitnami/nginx
    createNamespace: true
    values:
      - replicaCount: 3
      - image:
          tag: stable

以上配置对应的 helm 命令:

helm repo add bitnami https://charts.bitnami.com/bitnami/ --force-update
helm repo update
helm upgrade --install nginx bitnami/nginx \
    --namespace dev --create-namespace \
    --set replicaCount=3 --set image.tag=stable

显然, 当 helm 命令比较复杂时, 使用 helmfile 将会是个不错的选择.
但即使 helm 命令简单, 也建议使用 helmfile, 毕竟它让 "命令" 变成了 "文件".
因此可以减少输入命令式的错误, 还可以使用 git 做配置文件的版本管理.

命令笔记

命令	作用	备注
helmfile apply	若发现修改则更新 (对比上次的配置文件)	不会发现 k8s 中的手动修改
helmfile sync	不论是否发生修改都会更新	release 的 revision 总会 +1

编辑技巧

helmfile.yaml 并不是标准的 yaml 文件, 它包含了类似于 helm chart template 的模板语法.
例如下面这个例子中, 将会获取名为 ACCESS_TOKEN 的环境变量的值, 并添加双引号:

releases:
  - name: xxx
    chart: xxx
    values:
      - token: {{ requiredEnv "ACCESS_TOKEN" | quote }}  

如果代码编辑器设置了 auto format on save, 那么很可能在保存文件时会 错误地 格式化代码.
这就会导致模板语法出问题, 因为必须要有两个连续的大括号, 中间不能有空格.

releases:
  - name: xxx
    chart: xxx
    values:
      - token: {{ requiredEnv "ACCESS_TOKEN" | quote }}    # 自动格式化前, 符合语法 #
      - token: { { requiredEnv "ACCESS_TOKEN" | quote } }  # 自动格式化后, 有语法错误 #

此时的解决方案是: 修改 yaml 文件的自动格式化规则, 使得大括号之间没有空格.
为此可以在 vscode 全局设置中将 Yaml 的 Format: Bracket Spacing 取消勾选.

也可修改 Workspace 中的设置, 在 .vscode/settings.json 中添加:

// .vscode/settings.json
"yaml.format.bracketSpacing": false