一、安装

Github 仓库

Github Release竟然没有编译好的包。

  1. 下载
1
wget https://get.helm.sh/helm-v4.2.0-linux-amd64.tar.gz
  1. 解压
1
tar xf helm-v4.2.0-linux-amd64.tar.gz
  1. 移动
1
mv linux-amd64/helm /usr/local/bin

合并2、3

1
tar xf helm-v4.2.0-linux-amd64.tar.gz -C /usr/local/bin --strip-components=1 linux-amd64/helm
  1. 验证
1
helm version
  1. 自动补全
1
2
helm completion bash >> ~/.bashrc
source ~/.bashrc

二、问题

2.1 helm 命令补全乱码

解决方案：安装 bash-completion

1
dnf install -y bash-completion

安装完成后，需要让当前 shell 加载它：

1
source /etc/profile.d/bash_completion.sh

或者直接重新登录一下终端。

三、命令速查

3.1 概念

Charts 是一组 k8s 资源清单文件，Release 是一个个运行的实例。

3.2 仓库

  1. 仓库管理
1
2
3
4
5
6
helm repo add <名字> <仓库URL>     # 添加一个仓库
helm repo list                     # 列出已添加的仓库（简写 helm repo ls）
helm repo update                   # 更新所有仓库的索引（拉最新 chart 列表）
helm repo update <名字>            # 只更新某一个仓库
helm repo remove <名字>            # 删除仓库
helm repo index <目录>             # 给本地 chart 目录生成 index.yaml（自建 http 仓库时用）
  1. 搜索 chart
1
2
3
helm search repo <关键词>          # 在“已添加的本地仓库”里搜
helm search repo <关键词> -l       # 列出该 chart 的所有版本（-l = --versions）
helm search hub <关键词>           # 在 Artifact Hub（全网）搜，会告诉你该 add 哪个仓库

Artifact Hub（artifacthub.io）：CNCF 官方的发现门户，相当于 chart 界的搜索引擎。它是上一代 Helm Hub 的继任者。先来这搜，它告诉你该 add 哪个地址。

3.3 chart

  1. 查看 chart 内容（安装前先看清楚）
1
2
3
4
5
6
7
8
9
10
helm show chart  <仓库/chart>      # 看 Chart.yaml 元信息（版本、依赖等）
helm show values <仓库/chart>      # 看默认 values.yaml（最常用，看有哪些可配项）
helm show readme <仓库/chart>      # 看 README
helm show all    <仓库/chart>      # 全部都看

# 指定版本看
helm show values bitnami/redis --version 19.0.0

# 把默认 values 存下来当作自己的配置模板
helm show values ingress-nginx/ingress-nginx > my-values.yaml
  1. values 赋值的几种方式
1
2
3
4
5
6
7
-f values.yaml                     # 用文件（可多次 -f，后面的覆盖前面的）
--set key=value                    # 命令行单条覆盖
--set-string key=value             # 强制按字符串处理（避免 "true"/"123" 被转类型）
--set-file key=文件路径            # 把一个文件的内容塞进某个 value（如证书、脚本）

# 多文件叠加示例：通用配置 + 环境差异
helm install myapp ./myapp -f values.yaml -f values-prod.yaml --set image.tag=v1.2.3

3.4 渲染和调试

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# ① 纯本地渲染：把最终 YAML 打印出来，不连集群、不安装 —— 检查模板对不对的主力
helm template <release名> <chart> -f values.yaml

# 只看某个文件的渲染结果
helm template myapp ./myapp -s templates/deployment.yaml

# ② 连集群做服务端校验，但不真正安装
helm install myapp ./myapp --dry-run --debug

# ③ 语法 / 规范检查（chart 目录是否合法）
helm lint ./myapp

# ④ 看“已经装到集群里”的东西
helm get manifest <release名>      # 当前 release 实际生成的全部 YAML
helm get values   <release名>      # 当前 release 用的 values（加 -a 看含默认值的全量）
helm get notes    <release名>      # 安装后那段提示信息
helm get all      <release名>      # 全部信息

# ⑤ 升级前预览“会变哪些”（需装插件 helm-diff）
helm plugin install https://github.com/databus23/helm-diff
helm diff upgrade <release名> <chart> -f values.yaml

经验：改完模板 / values，先 helm template 肉眼看渲染，再 helm diff upgrade 看变更，最后才 helm upgrade。

3.5 安装 / 升级 / 回滚 / 卸载

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 安装（来源可以是 仓库 / 本地目录 / 本地tgz / OCI）
helm install <release名> <仓库/chart>           # 从仓库装
helm install <release名> ./mychart              # 从本地目录装
helm install <release名> ./mychart-1.0.0.tgz    # 从本地 tgz 包装
helm install <release名> oci://registry/xxx/chart --version 1.0.0   # 从 OCI 装

# 常用附加参数
  -n <命名空间> --create-namespace               # 指定/自动建命名空间
  --version <版本>                               # 固定 chart 版本（强烈建议生产always写）
  --atomic                                       # 失败自动回滚，不留半截状态
  --wait --timeout 5m                            # 等所有资源就绪再返回

# 升级（最常用写法：有就升、没有就装）
helm upgrade --install <release名> <chart> -f values.yaml -n <ns>

# 列出 / 查状态 / 历史
helm list -n <ns>                  # 列出 release（-A 看所有命名空间）
helm status <release名>
helm history <release名>           # 看版本历史（rollback 要用到这里的 revision 号）

# 回滚
helm rollback <release名>          # 回到上一个版本
helm rollback <release名> 3        # 回到第 3 个 revision

# 卸载
helm uninstall <release名> -n <ns>
helm uninstall <release名> --keep-history   # 卸载但保留历史（之后还能 rollback）

3.6 开发 chart

1
helm create mychart                # 生成一个标准 chart 脚手架

标准目录结构：

1
2
3
4
5
6
mychart/
├── Chart.yaml          # 元信息：name / version / appVersion / dependencies
├── values.yaml         # 默认取值
├── charts/             # 依赖的子 chart 会放在这（dependency update 后出现）
├── templates/          # 模板（_helpers.tpl 放复用片段，NOTES.txt 是安装提示）
└── .helmignore
1
2
3
4
5
helm lint ./mychart                          # 检查规范
helm template ./mychart                      # 看渲染
helm package ./mychart                       # 打包成 mychart-<version>.tgz
helm package ./mychart -d ./dist             # 指定输出目录
helm package ./mychart --version 1.2.3       # 打包时覆盖版本号

固定版本：chart 的版本由 Chart.yaml 里的 version: 决定。每次改 chart 就 +1，打出来的 tgz 文件名自带版本号，这就是“固定版本”的来源。

3.7 依赖管理

在 Chart.yaml 里声明依赖：

1
2
3
4
5
6
7
8
dependencies:
  - name: redis
    version: "19.0.0"              # ← 写死版本 = 固定版本
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled       # 可选：按 values 里的开关决定是否启用
  - name: common                   # library chart（只提供模板，不部署东西）
    version: "2.x.x"
    repository: "https://..."
1
2
3
helm dependency list <chart>       # 看依赖及状态（简写 helm dep list）
helm dependency update <chart>     # 按 Chart.yaml 拉取依赖到 charts/ 目录，并生成 Chart.lock
helm dependency build <chart>      # 按已有的 Chart.lock 还原依赖（CI 里常用，保证可复现）
  • subchart / umbrella：父 chart 把 redis、postgresql 等当依赖一起装。父的 values 里用 redis: {...} 这个 key 覆盖子 chart 的值。
  • library chart（type: library）：本身装不出任何东西，只导出模板片段，被别的 chart 用 {{ include "common.xxx" . }} 调用。这通常就是团队里那个“基础设施 chart”。
  • Chart.lock 锁定依赖的精确版本，提交进 git，保证每个人 / CI 拉到的依赖一致。

3.8 拉取 / 推送 / OCI 仓库

1
2
3
4
5
6
7
8
9
10
11
12
13
# 拉取 tgz 到本地（不安装）
helm pull <仓库/chart>                         # 下载 .tgz
helm pull <仓库/chart> --version 1.0.0         # 指定版本
helm pull <仓库/chart> --untar                 # 下载并解压成目录
helm pull oci://registry-1.docker.io/bitnamicharts/redis   # 从 OCI 拉

# OCI 仓库（chart 当镜像存，新版主流；Harbor/GHCR/DockerHub 都支持）
helm registry login <registry地址> -u <用户>   # 登录
helm push mychart-1.2.3.tgz oci://<registry>/<项目>   # 推送 tgz 到 OCI
helm pull   oci://<registry>/<项目>/mychart --version 1.2.3
helm install myapp oci://<registry>/<项目>/mychart --version 1.2.3
helm show values oci://<registry>/<项目>/mychart --version 1.2.3
helm registry logout <registry地址>

传统 HTTP 仓库的发布方式（了解即可）：helm package → helm repo index . 生成 index.yaml → 把 tgz 和 index.yaml 一起放到一个能 HTTP 访问的地方（如 GitHub Pages / Nginx）。新项目建议直接用 OCI，不用再维护 index.yaml。

3.9 典型工作流串一遍

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# A. 用现成 chart 部署
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm show values ingress-nginx/ingress-nginx > my-values.yaml   # 看配置并改
helm template ing ingress-nginx/ingress-nginx -f my-values.yaml # 渲染检查
helm upgrade --install ing ingress-nginx/ingress-nginx \
  -f my-values.yaml -n ingress --create-namespace --version 4.x.x

# B. 开发并发布自己的 chart
helm create myapp
# ...改 templates 和 values...
helm lint ./myapp
helm template ./myapp                 # 看渲染对不对
helm dependency update ./myapp        # 如果有依赖
helm package ./myapp                  # 得到 myapp-0.1.0.tgz
helm push myapp-0.1.0.tgz oci://<registry>/<项目>   # 推送
helm install myapp ./myapp-0.1.0.tgz  # 或本地直接装验证

# C. 出问题回滚
helm history myapp
helm rollback myapp 2