深色模式
Helm 包管理入门
摘要：本文从安装 Helm 开始，演示用官方 chart 部署应用、用 values.yaml 覆盖配置、版本升级与回滚，并带你从零创建一个自己的 chart，理解模板与目录结构。
适用环境
- 可用 K8s 集群 +
kubectl - 能访问 Helm chart 仓库
- 示例：部署一个 nginx
操作步骤
一、安装 Helm
bash
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm version1
2
2
二、仓库操作
bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm search repo nginx
helm search hub nginx # 搜 ArtifactHub 上的公共 chart
helm repo list1
2
3
4
5
2
3
4
5
三、安装一个 release
bash
helm install my-nginx bitnami/nginx
helm list
helm status my-nginx
kubectl get pod,svc -l app.kubernetes.io/instance=my-nginx1
2
3
4
2
3
4
四、用自定义 values 覆盖配置
先导出默认配置看看有哪些可调项：
bash
helm show values bitnami/nginx > values.yaml1
改写一份自己的：
yaml
replicaCount: 3
image:
registry: docker.io
repository: bitnami/nginx
tag: "1.27"
service:
type: ClusterIP
port: 80
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 512Mi1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
安装或更新时指定：
bash
helm install my-nginx bitnami/nginx -f values.yaml
# 或者只对单个参数覆盖
helm install my-nginx bitnami/nginx --set replicaCount=3 --set service.type=NodePort1
2
3
2
3
建议
-f values.yaml 优于 --set：values 文件可进版本库、可评审、可复现。--set 适合临时调试。
五、升级与回滚
bash
helm upgrade my-nginx bitnami/nginx -f values.yaml
helm history my-nginx
helm rollback my-nginx 1 # 回滚到 revision 1
helm list1
2
3
4
2
3
4
危险
helm upgrade 默认不会等待就绪就返回。生产发布务必加 --atomic --timeout 5m，失败时自动回滚，避免留下半更新状态。
六、卸载
bash
helm uninstall my-nginx
helm list --all # 能看到已卸载的 release 记录1
2
2
七、创建自己的 chart
bash
helm create myapp
tree myapp1
2
2
目录结构：
text
myapp/
├── Chart.yaml # chart 元信息（名称、版本）
├── values.yaml # 默认配置值
├── templates/ # Go template 模板
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── _helpers.tpl # 可复用的模板片段
│ └── tests/
└── charts/ # 子 chart 依赖1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
八、模板写法示例
templates/deployment.yaml 节选：
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "myapp.fullname" . }}
labels:
{{- include "myapp.labels" . | nindent 4 }}
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
{{- include "myapp.selectorLabels" . | nindent 6 }}
template:
spec:
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
resources:
{{- toYaml .Values.resources | nindent 12 }}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
内置对象：.Values（values.yaml）、.Release（release 名/命名空间）、.Chart（Chart.yaml 内容）。
九、调试与校验（写完必做）
bash
helm lint myapp # 语法与规范检查
helm template myapp # 本地渲染出最终 YAML，不连集群
helm install myapp ./myapp --dry-run --debug # 模拟安装
helm install myapp ./myapp --diff 2>/dev/null || true1
2
3
4
2
3
4
注意
helm template 不连集群，无法验证依赖的 API 版本是否存在。helm install --dry-run 会连集群做完整校验，发布前两者都跑一遍最稳妥。
十、打包与分发
bash
helm package myapp
helm install myapp ./myapp-0.1.0.tgz1
2
2
验证
- [ ]
helm list显示 release 状态为 deployed - [ ]
helm status能看到实际的 Pod 与 Service - [ ] 改 values 后
helm upgrade生效，helm history有多条记录 - [ ]
helm lint自建 chart 无 error
常见坑
Error: cannot re-use a name that is still in use：release 名重复，先 uninstall 或换名。UPGRADE FAILED: another operation (install/upgrade) is in progress：上次操作中断留下锁，用helm rollback恢复后再操作。- 改了 values 但没生效：缩进层级写错（如
image.tag写成顶层tag），用helm template渲染确认。 - 卸载后 PVC 还在：Helm 默认不删除 PVC，需手动清理
kubectl delete pvc。 - chart 版本与应用版本混淆：
Chart.yaml的version是 chart 版本，appVersion才是镜像版本，改镜像要改appVersion或 values 里的 tag。