2026-05-20-helm介绍及使用
Helm
一、Helm是什么?
Helm 是一个用于 Kubernetes 应用的包管理器,类似 Linux 的
apt/yum,它使安装和升级复杂应用变得简单。
核心概念(Chart / Release / Repository / Values)
1 2 3 4 5 6 7 8 9 10 没有 Helm: kubectl apply -f deployment.yaml kubectl apply -f service.yaml kubectl apply -f configmap.yaml kubectl apply -f ingress.yaml ... 一堆文件分开管理 有了 Helm: helm install myapp ./mychart 一条命令部署所有资源,版本化管理,支持回滚
概念
说明
类比
Chart
应用的打包格式(一堆模板文件)
deb/rpm 包
Release
Chart 的一次部署实例
已安装的软件
Repository
Chart 仓库
apt 源/yum 源
Values
配置参数文件
配置文件
Revision
Release 的每次变更版本号
提交记录
二、Chart 文件结构 —
完整目录树
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 mychart/ ← Chart 根目录(即 Chart 名称) │ ├── Chart.yaml ← Chart 元数据(必须) ├── values.yaml ← 默认配置参数(必须) ├── values.schema.json ← values 的 JSON Schema 校验(可选) │ ├── charts/ ← 子 Chart 依赖目录 │ ├── redis-17.0.0.tgz ← 依赖的其他 Chart(打包后) │ └── postgresql/ ← 或者解压的依赖 Chart │ ├── templates/ ← 模板文件目录(必须) │ ├── _helpers.tpl ← 模板辅助函数(下划线开头不渲染) │ ├── NOTES.txt ← 安装完成后的提示信息 │ ├── deployment.yaml ← Deployment 模板 │ ├── service.yaml ← Service 模板 │ ├── ingress.yaml ← Ingress 模板 │ ├── configmap.yaml ← ConfigMap 模板 │ ├── secret.yaml ← Secret 模板 │ ├── serviceaccount.yaml ← ServiceAccount 模板 │ ├── hpa.yaml ← HPA 模板 │ └── tests/ ← 测试模板目录 │ └── test-connection.yaml ← 连接测试 Pod │ ├── crds/ ← CRD 资源定义目录(安装时最先应用) │ └── myresource.yaml │ └── .helmignore ← 打包时忽略的文件(类似 .gitignore)
三、核心文件详解
Chart.yaml(Chart 描述文件)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 apiVersion: v2 name: mychart version: 1.0 .0 appVersion: "2.11.0" description: A Helm chart type: application keywords: - harbor - registry home: https://github.com/xxx sources: - https://github.com/xxx maintainers: - name: xy email: xy@example.com icon: https://example.com/icon.png dependencies: - name: redis version: "17.x.x" repository: https://charts.bitnami.com/bitnami condition: redis.enabled - name: postgresql version: "12.x.x" repository: https://charts.bitnami.com/bitnami
values.yaml(默认配置文件)
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 28 29 30 31 32 33 34 replicaCount: 1 image: repository: nginx pullPolicy: IfNotPresent tag: "1.25" service: type: ClusterIP port: 80 ingress: enabled: false className: nginx hosts: - host: myapp.local paths: - path: / pathType: Prefix resources: requests: memory: 128Mi cpu: 100m limits: memory: 256Mi cpu: 500m nodeSelector: {}tolerations: []affinity: {}
templates/_helpers.tpl(模板辅助函数)
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 {{/* 生成应用名称 */ }} {{- define "mychart.name" - }} {{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }} {{- end }} {{/* 生成完整的 release 名称 */ }} {{- define "mychart.fullname" - }} {{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }} {{- end }} {{/* 通用标签 */ }} {{- define "mychart.labels" - }}helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }} app.kubernetes.io/name: {{ include "mychart.name" . }}app.kubernetes.io/instance: {{ .Release.Name }}app.kubernetes.io/version: {{ .Chart.AppVersion }}app.kubernetes.io/managed-by: {{ .Release.Service }} {{- end }}
templates/deployment.yaml(模板文件示例)
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 28 apiVersion: apps/v1 kind: Deployment metadata: name: {{ include "mychart.fullname" . }} labels: {{- include "mychart.labels" . | nindent 4 }}spec: replicas: {{ .Values.replicaCount }} selector: matchLabels: app.kubernetes.io/name: {{ include "mychart.name" . }} template: metadata: labels: app.kubernetes.io/name: {{ include "mychart.name" . }} spec: containers: - name: {{ .Chart.Name }} image: "{{ .Values.image.repository }} :{{ .Values.image.tag }} " imagePullPolicy: {{ .Values.image.pullPolicy }} ports: - containerPort: 80 resources: {{- toYaml .Values.resources | nindent 10 }} {{- with .Values.nodeSelector }} nodeSelector: {{- toYaml . | nindent 8 }} {{- end }}
NOTES.txt(安装提示)
1 2 3 4 5 6 7 8 9 10 11 12 安装完成后显示给用户的提示信息,支持模板语法 1. 获取应用 URL: {{- if .Values.ingress.enabled }} http:// {{ (index .Values.ingress.hosts 0 ).host }} {{- else }} export POD_NAME=$(kubectl get pods -l "app= {{ include "mychart.name" . }} " -o jsonpath="{.items[0].metadata.name}") kubectl port-forward $POD_NAME 8080:80 {{- end }} 2. 管理员密码: kubectl get secret {{ include "mychart.fullname" . }} -o jsonpath="{.data.password}" | base64 -d
.helmignore(打包忽略)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 .git/ .gitignore README.md docs/ *.tmp *.bak .DS_Store .github/ .gitlab-ci.yml
values.schema.json(参数校验)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { "$schema" : "http://json-schema.org/draft-07/schema" , "properties" : { "replicaCount" : { "type" : "integer" , "minimum" : 1 , "description" : "副本数量" } , "image" : { "type" : "object" , "properties" : { "repository" : { "type" : "string" } , "tag" : { "type" : "string" } } , "required" : [ "repository" ] } } }
四、常用命令手册
4.1 仓库管理
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 helm repo add <仓库名> <URL> helm repo add stable https://charts.helm.sh/stable helm repo add harbor https://helm.goharbor.io helm repo add prometheus-community http://mirror.azure.cn/kubernetes/charts-prometheus-community/ helm repo add grafana http://mirror.azure.cn/kubernetes/charts-grafana/ helm repo list helm repo update helm repo update prometheus-community helm repo remove <仓库名> helm repo remove harbor helm search repo <关键词> helm search repo harbor helm search repo prometheus-community/prometheus helm search repo harbor/harbor --versions
4.2 安装(install)
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 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 helm install <release名> <chart> helm install harbor harbor/harbor helm install harbor harbor/harbor -n harbor helm install harbor harbor/harbor -n harbor --create-namespace helm install harbor harbor/harbor -f values.yaml helm install harbor harbor/harbor -f values.yaml -f override.yaml helm install harbor harbor/harbor --set harborAdminPassword=Harbor12345 helm install harbor harbor/harbor --set core.replicas=2,portal.replicas=2 helm install harbor harbor/harbor --set-string image.tag="v2.11.0" helm install harbor harbor/harbor --version 1.14.0 helm install harbor harbor/harbor --timeout 15m helm install harbor harbor/harbor --wait helm install harbor harbor/harbor -f values.yaml --dry-run helm install harbor harbor/harbor -f values.yaml --dry-run --debug helm install myapp ./mychart helm install myapp ./mychart-1.0.0.tgz helm upgrade --install harbor harbor/harbor -f values.yaml -n harbor --create-namespace
4.3 查看(list / get)
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 helm list helm list -A helm list -n harbor helm list --all helm list --failed helm list --uninstalled helm status harbor -n harbor helm get values harbor -n harbor helm get values harbor -n harbor --all helm get manifest harbor -n harbor helm get hooks harbor -n harbor helm get all harbor -n harbor helm history harbor -n harbor
4.4 升级(upgrade)
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 28 29 30 helm upgrade harbor harbor/harbor -f values.yaml -n harbor helm upgrade harbor harbor/harbor --reuse-values -n harbor helm upgrade harbor harbor/harbor --reuse-values \ --set harborAdminPassword=NewPassword -n harbor helm upgrade harbor harbor/harbor --version 1.15.0 -n harbor helm upgrade harbor harbor/harbor -f values.yaml \ --atomic \ --timeout 10m \ -n harbor helm upgrade harbor harbor/harbor \ -f values.yaml \ --dry-run \ -n harbor helm upgrade harbor harbor/harbor \ -f values.yaml \ --force \ -n harbor
4.5 回滚(rollback)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 helm history harbor -n harbor helm rollback harbor -n harbor helm rollback harbor 1 -n harbor helm rollback harbor 2 -n harbor helm rollback harbor 1 --wait -n harbor helm rollback harbor 1 --cleanup-on-fail -n harbor
4.6 卸载(uninstall)
1 2 3 4 5 6 7 8 9 10 11 helm uninstall harbor -n harbor helm uninstall harbor -n harbor --keep-history helm list --uninstalled -n harbor helm rollback harbor 1 -n harbor
4.7 Chart 开发
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 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 helm create mychart helm lint mychart helm lint mychart -f values.yaml helm template mychart ./mychart helm template mychart ./mychart -f values.yaml helm template mychart ./mychart --set image.tag=v1.0 helm template mychart ./mychart > rendered.yaml helm package mychart helm package mychart --version 1.0.0 helm package mychart -d ./output/ helm dependency update mychart helm dependency build mychart helm dependency list mychart helm push mychart-1.0.0.tgz oci://harbor.k8s.local /charts
4.8 查看 Chart 信息
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 helm show readme harbor/harbor helm show values harbor/harbor helm show chart harbor/harbor helm show all harbor/harbor helm show values harbor/harbor > harbor-default-values.yaml helm show values harbor/harbor --version 1.14.0
4.9 插件管理
1 2 3 4 5 6 7 8 9 10 11 12 13 14 helm plugin install https://github.com/chartmuseum/helm-push helm plugin install https://github.com/databus23/helm-diff helm plugin list helm plugin update <插件名> helm plugin update push helm plugin uninstall <插件名> helm plugin uninstall push
4.10 其他常用命令
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 28 29 helm version helm env helm completion bash > /etc/bash_completion.d/helmsource /etc/bash_completion.d/helm helm completion zsh > ~/.zsh/completion/_helm helm verify mychart-1.0.0.tgz helm pull harbor/harbor helm pull harbor/harbor --version 1.14.0 helm pull harbor/harbor --untar helm pull harbor/harbor --untar -d ./charts/
五、Helm 模板语法速查
5.1 基本语法
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 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 {{ .Values.replicaCount }} {{ .Values.image.repository }} {{ .Chart.Name }} {{ .Chart.Version }} {{ .Chart.AppVersion }} {{ .Release.Name }} {{ .Release.Namespace }} {{ .Release.Service }} {{- if .Values.ingress.enabled }} {{- else }} {{- end }} {{- range .Values.ingress.hosts }}- host: {{ .host }} {{- end }} {{- with .Values.nodeSelector }}nodeSelector: {{- toYaml . | nindent 8 }} {{- end }} {{ .Values.image.tag | default "latest" }} {{ default "nginx" .Values.image.repository }} {{ .Values.name | upper }} {{ .Values.name | lower }} {{ .Values.name | title }} {{ .Values.name | trunc 63 }} {{ .Values.name | trimSuffix "-" }} {{ .Values.name | quote }} {{- toYaml .Values.resources | nindent 10 }} {{- toJson .Values.config | nindent 4 }} {{- include "mychart.labels" . | nindent 4 }} {{- - }}
5.2 常用内置函数
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 28 29 30 31 32 33 34 35 36 37 {{ "hello" | upper }} {{ "hello world" | replace " " "-" }} {{ printf "%s-%s" "foo" "bar" }} {{ contains "cat" "catch" }} {{ add 1 2 }} {{ sub 5 3 }} {{ mul 2 3 }} {{ div 10 2 }} {{ mod 10 3 }} {{ max 3 5 }} {{ min 3 5 }} {{ list 1 2 3 }} {{ has "cat" (list "cat" "dog" ) }} {{ len (list 1 2 3 ) }} {{ dict "key" "value" }} {{ get .Values.map "key" }} {{ hasKey .Values.map "key" }} {{ "123" | int }} {{ 123 | toString }} {{ "true" | toBool }} {{ "hello" | b64enc }} {{ "aGVsbG8=" | b64dec }} {{ "hello" | sha256sum }} {{ .Files.Get "config.yaml" }}
六、常用操作场景
场景 1:安装并自定义配置
1 2 3 4 5 6 7 8 9 10 11 12 helm show values prometheus-community/prometheus > prom-values.yaml helm install prometheus prometheus-community/prometheus \ -f prom-values.yaml \ -n monitoring \ --create-namespace helm list -n monitoring kubectl get pods -n monitoring
场景 2:升级时不改 values
1 2 3 4 5 helm upgrade harbor harbor/harbor \ --reuse-values \ --version 1.15.0 \ -n harbor
场景 3:查看某次部署用的配置
1 2 helm get values harbor -n harbor helm get values harbor -n harbor --all
场景 4:回滚误操作
1 2 3 4 5 6 7 8 helm history harbor -n harbor helm rollback harbor 2 -n harbor helm rollback harbor 2 --wait -n harbor
场景 5:调试模板
1 2 3 4 5 6 7 8 9 10 11 helm template harbor harbor/harbor -f values.yaml helm template harbor harbor/harbor -f values.yaml > rendered.yaml helm install harbor harbor/harbor \ -f values.yaml \ --dry-run \ --debug 2>&1 | grep -A 10 "harbor-ingress"
场景 6:备份和迁移
1 2 3 4 5 6 7 8 9 10 11 helm get values harbor -n harbor > harbor-backup-values.yaml helm get manifest harbor -n harbor > harbor-manifest-backup.yaml helm install harbor harbor/harbor \ -f harbor-backup-values.yaml \ -n harbor \ --create-namespace
场景 7:使用 OCI
仓库(Harbor 存 Chart)
1 2 3 4 5 6 7 8 9 10 11 helm registry login harbor.k8s.local \ --username admin \ --password Harbor12345 helm push mychart-1.0.0.tgz oci://harbor.k8s.local /charts helm install myapp oci://harbor.k8s.local /charts/mychart \ --version 1.0.0
七、Helm 目录和配置文件位置
1 2 3 4 5 6 7 8 9 10 helm env ~/.cache/helm/repository/ ~/.config/helm/repositories.yaml ~/.local/share/helm/plugins/ rm -rf ~/.cache/helm/repository/ helm repo update
八、常见问题速查
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 28 29 30 helm show values <chart> helm get manifest <release> -n <namespace> helm status <release> -n <namespace> helm search repo <chart> --versions helm uninstall <release> -n <namespace> helm uninstall <release> -n <namespace> helm install <release> <chart> -f values.yaml -n <namespace> helm upgrade <release> <chart> \ --reuse-values \ --set key=value \ -n <namespace> helm lint <chart目录> helm template <release> <chart> -f values.yaml | kubectl apply --dry-run=client -f -
九、命令速查表
分类
命令
说明
仓库
helm repo add <名> <URL>
添加仓库
helm repo list
查看仓库
helm repo update
更新索引
helm repo remove <名>
删除仓库
helm search repo <关键词>
搜索 Chart
安装
helm install <release> <chart> -f values.yaml -n <ns>
安装
helm upgrade --install <release> <chart> -f values.yaml
不存在就装
helm install ... --dry-run
模拟安装
查看
helm list -A
查看所有 Release
helm status <release>
查看状态
helm get values <release>
查看配置
helm get manifest <release>
查看资源 YAML
helm history <release>
查看历史
升级
helm upgrade <release> <chart> -f values.yaml
升级
helm upgrade ... --reuse-values
保留原配置升级
helm upgrade ... --atomic
失败自动回滚
回滚
helm rollback <release> <版本号>
回滚到指定版本
helm rollback <release>
回滚到上一版本
卸载
helm uninstall <release> -n <ns>
卸载
helm uninstall ... --keep-history
卸载保留历史
开发
helm create <名>
创建 Chart
helm lint <chart>
校验 Chart
helm template <release> <chart>
渲染模板
helm package <chart>
打包 Chart
helm show values <chart>
查看默认 values
插件
helm plugin install <URL>
安装插件
helm plugin list
查看插件