Kubernetes Helm 使用手册

1. Helm 是什么？

Helm 是 Kubernetes 的包管理器，相当于 K8s 界的 apt / yum / Homebrew。

1.1 没有 Helm 之前

部署一个应用（如 Prometheus）需要：

写 Deployment.yaml
写 Service.yaml
写 ConfigMap.yaml
写 ServiceAccount.yaml
写 RBAC.yaml
写 Ingress.yaml
一份份 kubectl apply -f

升级时还要管理版本号、记录变更、回滚困难。

1.2 使用 Helm 之后

把一组 K8s 资源打包成一个 Chart
用 values.yaml 管理可配置参数
用一条命令完成部署 / 升级 / 回滚 / 卸载
内置 release 版本管理（每次升级都是一次 revision）

1.3 三个版本

版本	说明	备注
Helm v2	旧版本，需要 Tiller（服务端组件）	已废弃，不再使用
Helm v3	主流稳定版本，无 Tiller，架构简化	几乎所有 Chart 兼容
Helm v4	当前最新（v4.2.4，2025 年后主流）	大多数命令兼容 v3，本手册以 v4 为准

2. 核心概念

术语	含义
Chart	一组描述 K8s 资源的文件集合（类似软件包）
Release	Chart 在 K8s 集群中的一次运行实例（部署一次 = 一个 Release）
Repository	Chart 仓库（存放 Chart 的地方，类似 yum 源）
values.yaml	Chart 的参数配置文件（用户可定制 Chart 行为）
Revision	Release 的每次变更（部署 / 升级）记为一个版本号
Templates	Chart 中带模板语法的 Kubernetes YAML 文件

2.1 Chart、Release、Repository 三者关系

text

┌─────────────────────┐    helm install     ┌─────────────────┐
│  Chart Repository   │ ──────────────────► │   K8s Cluster   │
│ (artifacthub.io)    │                     │   (Releases)    │
└─────────────────────┘                     └─────────────────┘
        │                                          │
        │ helm pull                                │ helm list
        ▼                                          ▼
   ┌──────────┐                              ┌──────────────┐
   │  Chart   │  ───── helm install ──────►  │   Release    │
   │  (.tgz)  │                              │  rev: 1..N   │
   └──────────┘                              └──────────────┘

3. 安装 Helm

Helm 是单个二进制文件，只需要装在管理节点（如 k8s-master01）即可，不需要装到所有节点。

3.1 在线安装（Linux）

bash

# 进入工作目录
cd /etc/kubernetes/addons

# 下载（以 v4.2.4 为例，可以去 https://github.com/helm/helm/releases 选最新稳定版）
wget https://get.helm.sh/helm-v4.2.4-linux-amd64.tar.gz

# 解压
tar -xf helm-v4.2.4-linux-amd64.tar.gz

# 安装到 PATH
install -m 0755 linux-amd64/helm /usr/local/bin/helm

# 验证
helm version

3.2 验证 Helm 能访问集群

bash

# 当前 kubeconfig 上下文
kubectl config current-context

# 节点是否正常
kubectl get nodes

# 列出已有 release（首次应为 NAMESPACE 列为空）
helm list -A

# 输出所有 release，含失败状态的
helm list -A --all

Helm 通过当前用户的 $HOME/.kube/config 访问集群，不需要任何额外认证配置。

4. Helm 仓库（Repo）管理

Chart 仓库就是存放 Chart 的地方。最常用的是 Artifact Hub 和 prometheus-community GitHub Pages 仓库。

4.1 添加仓库

bash

# 添加 Prometheus 社区仓库
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

# 添加 Bitnami 仓库（最丰富的应用 Chart 库）
helm repo add bitnami https://charts.bitnami.com/bitnami

# 添加 Kubernetes 官方插件仓库
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

# 自定义名称 + 自定义源
helm repo add <repo-name> <repo-url>

# 添加示例（添加 Harbor）
helm repo add harbor https://helm.goharbor.io

4.2 列出已添加的仓库

bash

helm repo list

输出示例：

text

NAME                            URL
prometheus-community            https://prometheus-community.github.io/helm-charts
bitnami                         https://charts.bitnami.com/bitnami

4.3 更新仓库索引

bash

helm repo update

什么时候需要执行？
添加新仓库后
想查看 chart 最新版本前
升级 chart 到新版前

4.4 删除仓库

bash

helm repo remove <repo-name>

4.5 用本地 Chart 文件（不依赖仓库）

bash

# 从本地 .tgz 文件安装
helm install my-release ./my-chart-1.0.0.tgz

# 从本地解压后的 Chart 目录安装
helm install my-release ./my-chart/

5. 查找与查看 Chart

5.1 搜索 Chart

bash

# 在已添加的仓库中搜索关键字
helm search repo nginx

# 模糊搜索
helm search repo "nginx"

# 显示所有版本
helm search repo prometheus-community/kube-prometheus-stack --versions | head

# 限定显示前 N 个版本
helm search repo bitnami/redis --versions --max-col-width 50 | head -20

5.2 查看 Chart 元信息（Chart.yaml）

bash

helm show chart prometheus-community/kube-prometheus-stack --version 90.0.0

输出字段：

text

apiVersion: v2
name: kube-prometheus-stack
description: ...
type: application
version: 90.0.0        # Chart 版本
appVersion: v0.84.1    # 应用版本（被部署的程序自身的版本）

字段	含义
`version`	Chart 本身的版本号（用 `--version` 指定时用这个）
`appVersion`	Chart 所部署的应用版本（如 nginx 1.27）
`apiVersion: v2`	Helm 3/4 标准的 Chart（v1 是 Helm 2）

5.3 `helm show values` 看默认值

helm show values 把 Chart 内置的 values.yaml 默认值全量打出来。这是为自定义 values 打地基的关键命令——通常流程是：

① helm show values 看默认 → ② 复制需要的字段到自己的 my-values.yaml → ③ 改值 → ④ helm install -f my-values.yaml

示例 1：直接打印到终端

bash

helm show values prometheus-community/kube-prometheus-stack --version 90.0.0

输出是一个超大 YAML（这种 chart 通常 8000+ 行），不方便编辑，要先导出文件。

示例 2：导出到文件（最常用）

bash

# 一次性导出当前 Chart 的完整默认 values 到文件
helm show values bitnami/nginx \
  > nginx-default-values.yaml

# 文件可大可小，建议先 wc 看看
wc -l nginx-default-values.yaml

示例 3：导出指定版本的默认值（生产环境常用）

bash

# 为某个版本留档，方便升级时对比差异
helm show values bitnami/nginx --version 18.0.0 \
  > nginx-values-v18.0.0.yaml

helm show values bitnami/nginx --version 19.0.0 \
  > nginx-values-v19.0.0.yaml

# 对比两个版本默认值变化
diff -u nginx-values-v18.0.0.yaml nginx-values-v19.0.0.yaml | less

示例 4：只查某一个或几个字段

bash

# 找出所有 image 字段
helm show values bitnami/nginx | grep -A 5 "^image:"

# 找出 service 相关块
helm show values bitnami/nginx | sed -n '/^service:/,/^[a-z]/p'

# 找出资源 requests/limits 段
helm show values bitnami/nginx | grep -A 20 "^resources:"

示例 5：以 JSON 输出，便于 jq 处理

bash

# Helm 自身不带 --json，但可以借助 yq/jq
helm show values bitnami/nginx --version 18.0.0 | \
  yq -P > nginx-values.json.yaml   # 规范化输出

# 或直接用 kubectl 内置功能
helm show values bitnami/nginx --version 18.0.0 | \
  python3 -c "import sys,yaml,json;print(json.dumps(yaml.safe_load(sys.stdin),indent=2))" \
  > nginx-values.json

# 提取 image.tag 的当前默认值
helm show values bitnami/nginx --version 18.0.0 | \
  python3 -c "import sys,yaml;d=yaml.safe_load(sys.stdin);print(d['image']['tag'])"
# 输出：1.27.0

# 提取所有顶层 key
helm show values bitnami/nginx --version 18.0.0 | \
  python3 -c "import sys,yaml;print('\n'.join(yaml.safe_load(sys.stdin).keys()))"

没装 yq/jq？Python3 自带的 yaml 通常够用；如果不行也可以 pip3 install pyyaml。

示例 6：结合 git 做基线管理（推荐做法）

bash

mkdir -p ~/helm-values-baseline
cd ~/helm-values-baseline

# 为每个 chart/version 留基线
helm show values bitnami/nginx --version 18.0.0 > nginx-18.0.0.yaml
helm show values prometheus-community/kube-prometheus-stack --version 90.0.0 > kps-90.0.0.yaml

# 提交到 git，下次升级只对比变化
git init
git add . && git commit -m "baseline: helm charts default values"

# 升级到新版本时，对比变化
helm show values bitnami/nginx --version 19.0.0 > nginx-19.0.0.yaml
git diff --no-color nginx-18.0.0.yaml nginx-19.0.0.yaml | less

示例 7：和 `helm show` 其他子命令组合

bash

# 一键看 Chart.yaml + values.yaml + README（输出顺序：Chart.yaml → values.yaml → README）
helm show all bitnami/nginx | less

# 分屏查看
helm show all bitnami/nginx | \
  awk '/^---$/{count++;next} count==1{print > "values.yaml"} count==2{print > "readme.md"} count==0{print > "chart.yaml"}'

# 只看 Chart.yaml
helm show chart bitnami/nginx

# 只看 README
helm show readme bitnami/nginx | less

示例 8：从本地 Chart 包/目录查看 values

bash

# 本地 .tgz
helm show values ./kube-prometheus-stack-90.0.0.tgz

# 本地解压目录
helm show values ./my-nginx/

# 本地 chart + 自定义 values 在同一目录（避免混淆）
ls ./my-nginx/
# Chart.yaml  README.md  values.yaml  charts/  templates/

实战注意

坑	解决
默认值太大，终端翻不完	一定先 `> 导出文件` 再编辑
`helm install` 没传 `--values` 时，默认值与 Chart 内置 `values.yaml` 一致	升级时若只 `--reuse-values` 即可保留之前覆盖的值；不写明 `-f` 会回到默认值
不同 Chart/版本的默认值结构变化很大（如 `service.nodePort` 在 v1 是数字、v2 是对象）	升级前先看新 chart 默认值再调整自己的 `my-values.yaml`
默认值里有 `null` 代表"不渲染该资源"	不要传 `null`，可以用 `false` 或省略

5.4 拉取 Chart 到本地

bash

# 拉到当前目录
helm pull prometheus-community/kube-prometheus-stack --version 90.0.0

# 自动解压
helm pull prometheus-community/kube-prometheus-stack --version 90.0.0 --untar

6. Chart 目录结构详解

一个标准 Chart 目录长这样：

text

mychart/
├── Chart.yaml              # Chart 元信息（必须）
├── values.yaml             # 默认配置（必须）
├── charts/                 # 依赖的子 Chart（可选）
├── templates/              # K8s 资源模板（必须）
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── _helpers.tpl        # 模板辅助函数（可复用片段）
│   ├── serviceaccount.yaml
│   ├── configmap.yaml
│   ├── secret.yaml
│   ├── NOTES.txt           # 安装成功后显示的提示
│   └── tests/              # Helm test 用例
├── .helmignore             # 打包时排除的文件
└── README.md               # Chart 说明

6.1 Chart.yaml 最小示例

yaml

apiVersion: v2
name: my-nginx
description: A simple nginx chart demo
type: application       # application 或 library
version: 1.0.0          # Chart 版本（SemVer）
appVersion: "1.27.0"    # 应用自身版本

6.2 values.yaml 最小示例

yaml

replicaCount: 2

image:
  repository: nginx
  tag: "1.27.0"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 100m
    memory: 128Mi

6.3 templates/deployment.yaml 示例

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-nginx.fullname" . }}
  labels:
    app: {{ include "my-nginx.name" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ include "my-nginx.name" . }}
  template:
    metadata:
      labels:
        app: {{ include "my-nginx.name" . }}
    spec:
      containers:
        - name: nginx
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: 80
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

是 Go template 语法，Helm 在 helm install 时把它替换成实际值。

7. values.yaml 编写规范

7.1 命名约定

使用驼峰命名（camelCase），如 replicaCount、serviceAccountName
用嵌套结构组织复杂参数：

yaml

image:
  repository: nginx
  tag: "1.27.0"
  pullPolicy: IfNotPresent

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 200m
    memory: 256Mi

7.2 注释和条件

yaml

# 这是注释，会在 helm show values 时显示

# 默认开启
ingress:
  enabled: false

# 仅在 enabled: true 时生效
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific

7.3 多文件拆分

复杂场景可拆分：

yaml

# values.yaml
replicaCount: 2
image:
  repository: myapp
  tag: latest

# 引入其他文件
database:
  <<: (*导入方式不可用*)

# 实际做法：使用 --values 多个文件
# helm install -f values.yaml -f values-prod.yaml ...

8. `helm install` 部署应用

helm install 是最核心的命令。

8.1 命令格式

bash

helm install <RELEASE_NAME> <CHART> [flags]

8.2 常用 flag

Flag	含义
`-n, --namespace`	部署到指定 namespace
`--create-namespace`	自动创建 namespace（不存在时）
`-f, --values`	指定自定义 values 文件（可多次使用叠加）
`--set key=value`	单值覆盖 values.yaml
`--set-string key=value`	强制字符串覆盖（适合数字）
`--set-file key=path`	用文件内容作为值
`--version`	指定 Chart 版本
`--dry-run`	只试运行，不实际部署（强烈推荐排错用）
`--debug`	输出详细渲染结果（配合 `--dry-run`）
`--atomic`	安装失败时自动回滚
`--wait`	等待所有资源 Ready
`--timeout 5m`	等待超时（默认 5m）
`--generate-name`	自动生成 release 名（不用手动指定 RELEASE_NAME）

8.3 部署示例 1：直接指定 Chart 名

bash

# 用 Bitnami 仓库的 nginx，创建名为 my-nginx 的 release
helm install my-nginx bitnami/nginx \
  --namespace web \
  --create-namespace

8.4 部署示例 2：使用自定义 values

bash

helm install my-nginx bitnami/nginx \
  --namespace web \
  --create-namespace \
  --values my-nginx-values.yaml

8.5 部署示例 3：使用 `--set` 覆盖

bash

helm install my-nginx bitnami/nginx \
  --set replicaCount=3 \
  --set service.type=NodePort \
  --set service.nodePort=30080

8.6 部署示例 4：安装kube-prometheus-stack

bash

# 1) 添加仓库
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

# 2) 创建 namespace
kubectl create namespace monitoring

# 3) 编写 kps-values.yaml（自定义 values）

# 4) 安装 release，名为 kps
helm install kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --version 90.0.0 \
  --values kps-values.yaml \
  --wait \
  --timeout 10m

8.7 `--dry-run` 排错（强烈推荐）

部署前先 dry-run，看实际生成的资源：

bash

helm install kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --values kps-values.yaml \
  --dry-run \
  --debug | less

8.8 安装成功的标志

bash

NAME: kps
LAST DEPLOYED: Tue Sep  8 17:50:00 2026
NAMESPACE: monitoring
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
kube-prometheus-stack has been installed.
...

9. 查看 Release 状态

9.1 列出所有 Release

bash

# 当前 namespace
helm list

# 所有 namespace
helm list -A

# 显示更多信息
helm list -A --output json
helm list -A -o yaml

# 显示字段（自定义列）
helm list -A \
  -o custom-columns=NAME:.name,NS:.namespace,STATUS:.status,REVISION:.revision,CHART:.chart,APP_VERSION:.appVersion

9.2 查看某个 Release 的详细状态

bash

helm status kps -n monitoring

9.3 查看 release 的 values

bash

helm get values kps -n monitoring

# 包含用户传的所有 values
helm get values kps -n monitoring --all

9.4 查看 release 的 manifest（实际渲染结果）

bash

# 所有资源
helm get manifest kps -n monitoring | less

# 只有某个资源
helm get manifest kps -n monitoring | grep -A 20 "kind: Prometheus"

9.5 查看 release 历史

bash

helm history kps -n monitoring

输出：

text

REVISION  UPDATED                   STATUS      CHART                         DESCRIPTION
1         Tue Sep  8 17:00:00 2026  superseded  kube-prometheus-stack-90.0.0  Install complete
2         Tue Sep  8 17:30:00 2026  deployed    kube-prometheus-stack-90.0.0  Upgrade complete

9.6 查看 chart 信息

bash

helm get notes kps -n monitoring          # 安装后的提示信息
helm get hooks kps -n monitoring          # 钩子信息

10. `helm upgrade` 升级应用

升级是 Helm 的强项。每次升级都生成一个 新 revision，可随时回滚。

10.1 命令格式

bash

helm upgrade [RELEASE] [CHART] [flags]

10.2 常用场景

场景 1：修改 values 后升级

bash

# 编辑 values 文件后升级
helm upgrade kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --reuse-values \
  --values kps-values.yaml \
  --wait

场景 2：仅覆盖一个参数

bash

helm upgrade kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --reuse-values \
  --set prometheus.prometheusSpec.retention=30d \
  --wait

--reuse-values 表示复用已有 values，只在基础上覆盖指定字段。不加 --reuse-values 就必须重新提供完整 -f values.yaml，否则会回归默认值！

场景 3：升级 Chart 到新版本

bash

helm repo update

helm upgrade kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --version 90.1.0 \
  --values kps-values.yaml \
  --atomic \
  --wait

--atomic：升级失败时自动回滚到上一个 revision。

场景 4：dry-run 升级排错

bash

helm upgrade kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --reuse-values \
  --set prometheus.prometheusSpec.retention=30d \
  --dry-run \
  --debug | less

10.3 install + upgrade 一体化

如果你想同时支持"首次安装"和"后续升级"，用 helm upgrade --install：

bash

helm upgrade --install kps prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace \
  --values kps-values.yaml \
  --wait

这是最常用的写法，CI/CD 流水线几乎都用这个。

11. `helm rollback` 回滚版本

11.1 命令格式

bash

helm rollback <RELEASE> [REVISION] [flags]

11.2 常用操作

bash

# 查看历史
helm history kps -n monitoring

# 回滚到上一个版本（不指定 REVISION）
helm rollback kps -n monitoring

# 回滚到指定 revision
helm rollback kps 1 -n monitoring

# 回滚时等待
helm rollback kps 1 -n monitoring --wait --wait-for-jobs

# 回滚并清理
helm rollback kps 1 -n monitoring --cleanup-on-fail

11.3 回滚后的检查

bash

helm history kps -n monitoring

text

REVISION  UPDATED                   STATUS      CHART                         DESCRIPTION
1         Tue Sep  8 17:00:00 2026  superseded  kube-prometheus-stack-90.0.0  Install complete
2         Tue Sep  8 17:30:00 2026  superseded  kube-prometheus-stack-90.0.0  Upgrade complete
3         Tue Sep  8 18:00:00 2026  deployed    kube-prometheus-stack-90.0.0  Rollback to 1

12. `helm uninstall` 卸载应用

12.1 命令格式

bash

helm uninstall <RELEASE> [flags]

12.2 常用操作

bash

# 基础卸载
helm uninstall kps -n monitoring

# 保留 namespace 不删
helm uninstall kps -n monitoring --keep-history
# 删除 release 但保留历史，可用于回滚到"已卸载"的版本

# 不保留历史（默认就保留 revision 记录）
helm uninstall kps -n monitoring --keep-history=false

12.3 卸载后的清理

Helm 默认只删除 Chart 创建的资源，不会删除：
你手动创建的 Namespace、Secret、PV
你手动在 namespace 里创建的其他资源
Helm 自己管理的 CRD（如果 Chart 带了 CRD，需要单独清理）

bash

# 检查是否还有残留资源
kubectl get all -n monitoring

# 删除整个 namespace（包括所有资源和 CRD）
kubectl delete namespace monitoring

12.4 卸载后历史未清除

bash

# 查看包括已卸载的所有 release
helm list -A --all

# 彻底清理历史（让 list 不再显示）
kubectl -n monitoring delete secret \
  -l "owner=helm,name=kps,status=release-status" \
  2>/dev/null

Helm 把每个 release 的元信息存在对应 namespace 下的 secret 里，名称形如 sh.helm.release.v1.kps.v1。

13. `helm template` 本地渲染与调试

helm template 在不连集群的情况下，把 Chart + values 渲染成最终的 K8s YAML 输出。

它是排查模板错误、对比 values 效果、生成可 apply 的离线 manifest 的必备工具。

13.1 基础用法

bash

# 渲染到终端
helm template my-nginx bitnami/nginx

# 渲染到文件
helm template my-nginx bitnami/nginx > manifest.yaml

# 指定 namespace
helm template my-nginx bitnami/nginx --namespace web

# 指定 values 文件
helm template my-nginx bitnami/nginx --values my-values.yaml

# 同时叠加多个 values（后写的覆盖前写的）
helm template my-nginx bitnami/nginx \
  --values values-base.yaml \
  --values values-prod.yaml

# 模拟 `helm install` 后的实际渲染（推荐）
helm template my-nginx bitnami/nginx \
  --values my-values.yaml \
  --namespace web \
  --include-crds \
  --show-only templates/deployment.yaml

13.2 常用 flag

Flag	含义
`--show-only templates/deployment.yaml`	只渲染某个模板
`--include-crds`	同时输出 Chart 自带的 CRD
`--skip-tests`	跳过 test manifest
`-s, --set`	临时覆盖 values
`--debug`	调试模式
`-n, --namespace`	替换模板里的 namespace
`--release-name`	显式指定 release 名
`--kube-version`	指定 K8s 版本，影响一些判断
`--output-dir`	输出到目录而不是 stdout

13.3 实战示例合集

场景 1：渲染到本地文件，离线 apply（CI/CD 友好）

bash

# 把 chart + values 渲染成 manifest.yaml
helm template my-nginx bitnami/nginx \
  --values my-values.yaml \
  --namespace web \
  --include-crds \
  > rendered.yaml

# 看看里面有几个资源
grep -E "^kind:" rendered.yaml | sort | uniq -c

# 输出示例：
#   2 ConfigMap
#   2 Deployment
#   2 Service
#   1 ServiceAccount

# 离线推到集群（不需要 helm，也不需要 chart 仓库）
kubectl apply -f rendered.yaml -n web

生产意义：在 CI 里 helm template ... > manifest.yaml 然后 kubectl apply -f，可以让"渲染"和"部署"在不同机器/不同权限账号上完成。

场景 2：只渲染某一个文件调试

bash

# 只看 deployment.yaml 渲染结果
helm template my-nginx bitnami/nginx \
  --values my-values.yaml \
  --show-only templates/deployment.yaml

# 只看 service.yaml
helm template my-nginx bitnami/nginx \
  --values my-values.yaml \
  --show-only templates/service.yaml

# 同时看多个文件（--show-only 多次写）
helm template my-nginx bitnami/nginx \
  --values my-values.yaml \
  --show-only templates/deployment.yaml \
  --show-only templates/service.yaml

场景 3：渲染出 CRD（Chart 自定义资源）

bash

# 默认不输出 CRD，必须 --include-crds
helm template kps prometheus-community/kube-prometheus-stack \
  --version 90.0.0 \
  --values kps-values.yaml \
  --namespace monitoring \
  --include-crds \
  > kps-rendered.yaml

# 看 CRD 段（kind: CustomResourceDefinition）
awk '/^kind: CustomResourceDefinition/{flag=1} /^---$/{if(flag){print;flag=0;next}} flag' kps-rendered.yaml | less

场景 4：配合 `--set` 临时改值

bash

# 把副本数临时改成 5 看渲染效果（不会真正安装）
helm template my-nginx bitnami/nginx \
  --set replicaCount=5 \
  --set service.type=NodePort \
  --set "service.nodePorts.http=30080"

# 渲染到分页查看
helm template my-nginx bitnami/nginx \
  --values my-values.yaml \
  --set replicaCount=5 \
  --debug 2>&1 | less

场景 5：分目录渲染（每个文件一个）

bash

# 输出到目录，每个 k8s 资源一个 yaml 文件
helm template my-nginx bitnami/nginx \
  --values my-values.yaml \
  --namespace web \
  --output-dir ./rendered/

# 看输出
ls -la ./rendered/my-nginx/templates/
# deployment.yaml  service.yaml  configmap.yaml  ...

配合 --output-dir 之后，每个 template 渲染成一个文件，适合 git diff。

场景 6：对比不同 values 的渲染差异（升级排错神器）

bash

# 用旧 values 渲染
helm template my-nginx bitnami/nginx \
  --values old-values.yaml \
  > rendered-old.yaml

# 用新 values 渲染
helm template my-nginx bitnami/nginx \
  --values new-values.yaml \
  > rendered-new.yaml

# 对比
diff -u rendered-old.yaml rendered-new.yaml | less

# 只看 Deployment 部分差异
diff \
  <(sed -n '/kind: Deployment/,/^---$/p' rendered-old.yaml) \
  <(sed -n '/kind: Deployment/,/^---$/p' rendered-new.yaml)

场景 7：和 `helm install --dry-run` 对比

bash

# 几乎一致，区别是：
#   - helm template 不调 K8s API，不创建 release
#   - helm install --dry-run 会试调 K8s API（创建 plan）

# 离线调试模板语法 → 用 helm template
helm template my-release ./my-chart/

# 模拟一次完整安装（不真正写入） → 用 helm install --dry-run
helm install my-release ./my-chart/ \
  --namespace web \
  --values my-values.yaml \
  --dry-run \
  --debug | less

用途	用什么
改 chart 模板语法排错	`helm template`
验证 release 能否被 K8s 接受	`helm install --dry-run`
升级前看会创建/修改/删除哪些资源	`helm diff upgrade`（需 helm-diff 插件）

场景 8：渲染时指定 `--kube-version` 影响 CRD 版本

bash

# 一些 chart 会按 K8s 版本判断 apiVersions
helm template kps prometheus-community/kube-prometheus-stack \
  --values kps-values.yaml \
  --kube-version 1.36.0

13.4 调试模板语法错误

bash

# 报错信息很关键
helm template my-nginx ./my-chart/
# Error: error parsing template files: template: mychart/templates/deployment.yaml:12: unexpected "}"

# 用 --debug 看更多上下文
helm template my-nginx ./my-chart/ --debug 2>&1 | head -100

13.5 完整工作流：写自己的 Chart 时

bash

# 1. 创建 chart
helm create my-nginx
cd my-nginx

# 2. 改 templates 模板（加个特殊字段）
vim templates/deployment.yaml

# 3. 改 values，加新字段
echo "myCustomField: hello" >> values.yaml

# 4. 离线渲染看效果（不动集群）
helm template test-render . \
  --set myCustomField=world \
  --debug 2>&1 | grep -A 5 "myCustomField"

# 5. 检查 lint
helm lint .

# 6. 满意后真部署
helm install my-nginx . --namespace web --create-namespace

14. 编写自己的 Chart

14.1 创建 Chart 骨架

bash

# 自动生成 chart 目录结构
helm create my-nginx

生成结构：

text

my-nginx/
├── .helmignore
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   ├── ingress.yaml
│   ├── _helpers.tpl
│   ├── hpa.yaml
│   ├── NOTES.txt
│   └── tests/
│       └── test-connection.yaml
└── charts/

14.2 修改 Chart.yaml

yaml

apiVersion: v2
name: my-nginx
description: My first custom nginx chart
type: application
version: 0.1.0
appVersion: "1.27.0"

14.3 修改 values.yaml

yaml

replicaCount: 2

image:
  repository: nginx
  tag: "1.27"
  pullPolicy: IfNotPresent

service:
  type: NodePort
  port: 80
  nodePort: 30080

ingress:
  enabled: false

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi

14.4 验证 Chart

bash

# 语法检查
helm lint ./my-nginx

# 带 values 检查
helm lint ./my-nginx --values my-nginx/values.yaml

# 严格模式
helm lint ./my-nginx --strict

14.5 本地安装自己的 Chart

bash

# install 本地目录
helm install my-nginx ./my-nginx \
  --namespace web \
  --create-namespace

# 指定 values
helm install my-nginx ./my-nginx \
  --namespace web \
  --create-namespace \
  --values my-nginx/values-prod.yaml

14.6 打包 Chart

bash

# 打 .tgz 包
helm package ./my-nginx

# 输出 my-nginx-0.1.0.tgz

# 通过 -d 指定输出目录
helm package ./my-nginx -d ./dist/

14.7 创建 Chart 仓库

bash

# 1. 准备目录
mkdir -p my-repo
mv my-nginx-0.1.0.tgz my-repo/

# 2. 生成 index.yaml
helm repo index my-repo/

# 3. 把 my-repo 上传到 http 服务器（如 nginx、GitHub Pages）

15. 常见命令速查表

仓库类

命令	用途
`helm repo add <name> <url>`	添加仓库
`helm repo list`	列出仓库
`helm repo update`	更新索引
`helm repo remove <name>`	删除仓库
`helm repo index <dir>`	生成仓库索引

Chart 类

命令	用途
`helm search repo <keyword>`	搜索 Chart
`helm show chart <chart>`	看 Chart 信息
`helm show values <chart>`	看默认 values
`helm show readme <chart>`	看 README
`helm show all <chart>`	看全部信息
`helm pull <chart>`	拉取 Chart
`helm create <name>`	创建 Chart 骨架
`helm lint <chart>`	校验 Chart
`helm package <chart>`	打包 Chart

Release 类

命令	用途
`helm install <name> <chart>`	安装
`helm upgrade <name> <chart>`	升级
`helm upgrade --install <name> <chart>`	安装或升级
`helm list` / `helm ls`	列 Release
`helm status <name>`	查状态
`helm history <name>`	查历史
`helm get values <name>`	取 values
`helm get manifest <name>`	取 manifest
`helm rollback <name> <rev>`	回滚
`helm uninstall <name>`	卸载

调试类

命令	用途
`helm version`	版本信息
`helm env`	环境信息
`helm template <name> <chart>`	本地渲染
`helm diff upgrade ...`	对比升级差异（需装 plugin）

16. 实战 Demo：使用国内 Helm 仓库部署 Nginx

第 14 章演示了如何自己编写 Chart，本章使用国内 KubeSphere Helm 仓库中已经打包好的 Nginx Chart，演示完整的安装、升级、回滚和卸载流程。

本例固定使用 Chart 1.3.5。该 Chart 发布时间较早，因此会通过 values 显式指定新版 Nginx 镜像，并使用 DaoCloud 国内镜像加速地址。

16.1 添加国内 Helm 仓库

bash

helm repo add kubesphere \
  https://charts.kubesphere.io/main \
  --force-update

helm repo update kubesphere
helm repo list

16.2 搜索并检查 Nginx Chart

bash

# 查看仓库中的 Nginx Chart 版本
helm search repo kubesphere/nginx --versions

# 查看 Chart 元数据和默认 values
helm show chart kubesphere/nginx --version 1.3.5
helm show values kubesphere/nginx --version 1.3.5 | less

这里涉及两个不同的仓库：

kubesphere/nginx 是 Helm Chart，里面保存 Kubernetes 资源模板。
image.nginx.repository 是容器镜像地址，部署后由 Kubernetes 节点拉取。

16.3 创建自定义 values

新建 nginx-values.yaml：

yaml

fullnameOverride: nginx-demo

replicaCount: 2

image:
  nginx:
    repository: m.daocloud.io/docker.io/library/nginx
    tag: "1.31.5-alpine"
    pullPolicy: IfNotPresent

service:
  name: http
  type: NodePort
  port: 80
  nodePort: 30180

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    cpu: 100m
    memory: 128Mi

m.daocloud.io/docker.io/library/nginx 是 Docker Hub 官方 Nginx 镜像的国内代理地址。如公司已有私有镜像仓库，建议换成内部已扫描并固定 digest 的镜像。

16.4 渲染预览

bash

# 本地渲染 Kubernetes YAML
helm template my-nginx kubesphere/nginx \
  --namespace web \
  --version 1.3.5 \
  --values nginx-values.yaml

# 模拟安装，不向集群写入资源
helm upgrade --install my-nginx kubesphere/nginx \
  --namespace web \
  --create-namespace \
  --version 1.3.5 \
  --values nginx-values.yaml \
  --dry-run \
  --debug

16.5 正式部署

bash

helm upgrade --install my-nginx kubesphere/nginx \
  --namespace web \
  --create-namespace \
  --version 1.3.5 \
  --values nginx-values.yaml \
  --rollback-on-failure \
  --timeout 5m

helm upgrade --install 可以重复执行：release 不存在时安装，已经存在时升级。Helm 4 使用 --rollback-on-failure，失败时会自动回滚，并隐含启用 --wait。

16.6 验证部署

bash

# 查看 release、Pod 和 Service
helm status my-nginx -n web
kubectl get pods -n web -l app.kubernetes.io/instance=my-nginx -o wide
kubectl get svc -n web nginx-demo -o wide

通过 NodePort 访问：

看到 Welcome to nginx! 页面内容即表示部署成功。

16.7 升级

先把 nginx-values.yaml 中的副本数改为：

yaml

replicaCount: 3

执行升级：

bash

helm upgrade my-nginx kubesphere/nginx \
  --namespace web \
  --version 1.3.5 \
  --values nginx-values.yaml \
  --rollback-on-failure \
  --timeout 5m

# 验证副本数和实际生效的 values
kubectl get deployment -n web nginx-demo
helm get values my-nginx -n web
helm history my-nginx -n web

长期维护时，推荐把配置固化在 values 文件中并纳入版本控制；--set 更适合临时覆盖。

16.8 回滚

bash

# 查看历史，确定要回滚到的 revision
helm history my-nginx -n web

# 回滚到首次安装的 revision 1
helm rollback my-nginx 1 \
  --namespace web \
  --wait \
  --timeout 5m

# 验证状态和副本数
helm status my-nginx -n web
kubectl get deployment -n web nginx-demo

16.9 卸载

bash

helm uninstall my-nginx -n web --wait
helm list -n web

如果 web 命名空间仅用于本 Demo，可以继续删除它：

bash

kubectl delete namespace web

附录 A：常用 Chart 推荐清单

Chart	仓库	用途
`kubesphere/nginx`	kubesphere	Nginx Web 服务器 / 反向代理
`bitnami/redis`	bitnami	Redis 缓存
`bitnami/postgresql`	bitnami	PostgreSQL
`bitnami/mysql`	bitnami	MySQL
`bitnami/kafka`	bitnami	Kafka
`prometheus-community/kube-prometheus-stack`	prometheus-community	Prometheus + Grafana 全套
`prometheus-community/prometheus`	prometheus-community	Prometheus
`grafana/grafana`	grafana	Grafana
`argo/argo-cd`	argo	GitOps
`ingress-nginx/ingress-nginx`	ingress-nginx	K8s Ingress
`jetstack/cert-manager`	jetstack	证书管理
`harbor/harbor`	harbor	镜像仓库
`kubernetes-dashboard/kubernetes-dashboard`	kubernetes-dashboard	Web UI

去 Artifact Hub 搜索更多。

附录 B：Helm v3 / v4 主要变化

类别	Helm v2	Helm v3 / v4
架构	Client + Tiller（服务端）	只有 Client，无服务端
Release 信息存储	ConfigMap	Secret
仓库管理	helm init	helm repo add
命名空间	默认 kube-system	任意 namespace
升级回滚	需要 kube serviceaccount 权限	用 kubeconfig

附录 C：CI/CD 中使用 Helm

bash

# 一行命令：部署 / 升级
helm upgrade --install kps \
  prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace \
  --values kps-values.yaml \
  --atomic \
  --wait \
  --timeout 10m

参数解释：

--install：首次安装或后续升级
--atomic：失败自动回滚
--wait：等待所有 Pod Ready 才返回
--timeout 10m：超时保护

Jenkins 优秀插件讲解

MySQL 5.7

MySQL 8.0

Xtrabackup

Kubernetes Helm 使用手册 ​

1. Helm 是什么？ ​

1.1 没有 Helm 之前 ​

1.2 使用 Helm 之后 ​

1.3 三个版本 ​

2. 核心概念 ​

2.1 Chart、Release、Repository 三者关系 ​

3. 安装 Helm ​

3.1 在线安装（Linux） ​

3.2 验证 Helm 能访问集群 ​

4. Helm 仓库（Repo）管理 ​

4.1 添加仓库 ​

4.2 列出已添加的仓库 ​

4.3 更新仓库索引 ​

4.4 删除仓库 ​

4.5 用本地 Chart 文件（不依赖仓库） ​

5. 查找与查看 Chart ​

5.1 搜索 Chart ​

5.2 查看 Chart 元信息（Chart.yaml） ​

5.3 helm show values 看默认值 ​

示例 1：直接打印到终端 ​

示例 2：导出到文件（最常用） ​

示例 3：导出指定版本的默认值（生产环境常用） ​

示例 4：只查某一个或几个字段 ​

示例 5：以 JSON 输出，便于 jq 处理 ​

示例 6：结合 git 做基线管理（推荐做法） ​

示例 7：和 helm show 其他子命令组合 ​

示例 8：从本地 Chart 包/目录查看 values ​

实战注意 ​

5.4 拉取 Chart 到本地 ​

6. Chart 目录结构详解 ​

6.1 Chart.yaml 最小示例 ​

6.2 values.yaml 最小示例 ​

6.3 templates/deployment.yaml 示例 ​

7. values.yaml 编写规范 ​

7.1 命名约定 ​

7.2 注释和条件 ​

7.3 多文件拆分 ​

8. helm install 部署应用 ​

8.1 命令格式 ​

8.2 常用 flag ​

8.3 部署示例 1：直接指定 Chart 名 ​

8.4 部署示例 2：使用自定义 values ​

8.5 部署示例 3：使用 --set 覆盖 ​

8.6 部署示例 4：安装kube-prometheus-stack ​

8.7 --dry-run 排错（强烈推荐） ​

8.8 安装成功的标志 ​

9. 查看 Release 状态 ​

9.1 列出所有 Release ​

9.2 查看某个 Release 的详细状态 ​

9.3 查看 release 的 values ​

9.4 查看 release 的 manifest（实际渲染结果） ​

9.5 查看 release 历史 ​

9.6 查看 chart 信息 ​

10. helm upgrade 升级应用 ​

10.1 命令格式 ​

10.2 常用场景 ​

场景 1：修改 values 后升级 ​

场景 2：仅覆盖一个参数 ​

场景 3：升级 Chart 到新版本 ​

场景 4：dry-run 升级排错 ​

10.3 install + upgrade 一体化 ​

11. helm rollback 回滚版本 ​

Kubernetes Helm 使用手册

1. Helm 是什么？

1.1 没有 Helm 之前

1.2 使用 Helm 之后

1.3 三个版本

2. 核心概念

2.1 Chart、Release、Repository 三者关系

3. 安装 Helm

3.1 在线安装（Linux）

3.2 验证 Helm 能访问集群

4. Helm 仓库（Repo）管理

4.1 添加仓库

4.2 列出已添加的仓库

4.3 更新仓库索引

4.4 删除仓库

4.5 用本地 Chart 文件（不依赖仓库）

5. 查找与查看 Chart

5.1 搜索 Chart

5.2 查看 Chart 元信息（Chart.yaml）

5.3 `helm show values` 看默认值

示例 1：直接打印到终端

示例 2：导出到文件（最常用）

示例 3：导出指定版本的默认值（生产环境常用）

示例 4：只查某一个或几个字段

示例 5：以 JSON 输出，便于 jq 处理

示例 6：结合 git 做基线管理（推荐做法）

示例 7：和 `helm show` 其他子命令组合

示例 8：从本地 Chart 包/目录查看 values

实战注意

5.4 拉取 Chart 到本地

6. Chart 目录结构详解

6.1 Chart.yaml 最小示例

6.2 values.yaml 最小示例

6.3 templates/deployment.yaml 示例

7. values.yaml 编写规范

7.1 命名约定

7.2 注释和条件

7.3 多文件拆分

8. `helm install` 部署应用

8.1 命令格式

8.2 常用 flag

8.3 部署示例 1：直接指定 Chart 名

8.4 部署示例 2：使用自定义 values

8.5 部署示例 3：使用 `--set` 覆盖

8.6 部署示例 4：安装kube-prometheus-stack

8.7 `--dry-run` 排错（强烈推荐）

8.8 安装成功的标志

9. 查看 Release 状态

9.1 列出所有 Release

9.2 查看某个 Release 的详细状态

9.3 查看 release 的 values

9.4 查看 release 的 manifest（实际渲染结果）

9.5 查看 release 历史

9.6 查看 chart 信息

10. `helm upgrade` 升级应用

10.1 命令格式

10.2 常用场景

场景 1：修改 values 后升级

场景 2：仅覆盖一个参数

场景 3：升级 Chart 到新版本

场景 4：dry-run 升级排错

10.3 install + upgrade 一体化

11. `helm rollback` 回滚版本