跳转至

593_Helm包管理器

一句话概述：Helm 是 Kubernetes 的包管理器（相当于 K8s 的 apt/yum），用 Chart 模板打包应用的所有 K8s 资源，一条命令安装、升级、回滚复杂应用，是 K8s 生态最核心的工具之一。

核心知识点表

概念白话解释
Chart图表/包，一组 K8s 资源的模板集合（类似 RPM/DEB 包）
Release发布，Chart 安装到集群后的一个实例
Repository仓库，存放 Chart 的地方（类似 apt 源）
Values值文件，自定义 Chart 参数的 YAML 配置
Template模板，用 Go 模板语法生成 K8s YAML
Hook钩子，在安装/升级/删除的特定阶段执行操作
OCI Registry用容器镜像仓库存储 Chart（新标准）

安装配置

安装 Helm

# macOS
brew install helm                       # Homebrew 安装

# Linux（官方脚本）
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
# 脚本会自动检测系统架构并安装最新版

# Ubuntu/Debian
curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt update && sudo apt install helm

# 验证安装
helm version                            # 查看版本（当前 v4.x）

添加 Chart 仓库

# 添加官方仓库
helm repo add bitnami https://charts.bitnami.com/bitnami   # Bitnami（最大第三方仓库）
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx  # Nginx Ingress
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts  # Prometheus

# 更新仓库索引
helm repo update                        # 拉取最新 Chart 列表

# 查看已添加的仓库
helm repo list                          # 列出所有仓库

# 搜索 Chart
helm search repo nginx                  # 在本地仓库索引中搜索
helm search hub wordpress               # 在 Artifact Hub 中搜索

基本使用

安装应用

# 安装 Nginx（最简方式）
helm install my-nginx bitnami/nginx     # helm install <发布名> <Chart>
# my-nginx → Release 名称（自定义）
# bitnami/nginx → 仓库名/Chart 名

# 查看安装结果
helm list                               # 列出所有 Release
helm status my-nginx                    # 查看 Release 状态

# 自定义参数安装
helm install my-nginx bitnami/nginx \
  --set service.type=ClusterIP \        # 设置 Service 类型
  --set replicaCount=3                  # 设置副本数

# 使用 values 文件安装（推荐）
helm install my-nginx bitnami/nginx \
  -f my-values.yaml                     # 指定自定义值文件

# 安装到指定命名空间
helm install my-nginx bitnami/nginx \
  --namespace web \                     # 目标命名空间
  --create-namespace                    # 不存在则自动创建

Values 文件

# my-values.yaml — 自定义 Nginx 配置
replicaCount: 3                         # 3 个副本

image:
  tag: "1.27"                           # 指定镜像版本

service:
  type: LoadBalancer                    # Service 类型
  port: 80                              # 端口

resources:
  requests:
    memory: "64Mi"                      # 最低内存
    cpu: "100m"                         # 最低 CPU
  limits:
    memory: "128Mi"                     # 最大内存
    cpu: "250m"                         # 最大 CPU

ingress:
  enabled: true                         # 启用 Ingress
  hostname: nginx.example.com           # 域名
  tls: true                             # 启用 HTTPS

# 查看 Chart 的所有可配置参数
helm show values bitnami/nginx          # 显示默认 values
helm show values bitnami/nginx > default-values.yaml  # 保存到文件

升级和回滚

# 升级 Release
helm upgrade my-nginx bitnami/nginx \
  --set replicaCount=5                  # 修改副本数为 5
# 或
helm upgrade my-nginx bitnami/nginx \
  -f my-values.yaml                     # 使用新的 values 文件

# 查看历史版本
helm history my-nginx                   # 查看所有版本记录

# 回滚到上一个版本
helm rollback my-nginx                  # 回滚到前一版本

# 回滚到指定版本
helm rollback my-nginx 2               # 回滚到版本 2

# 卸载 Release
helm uninstall my-nginx                 # 删除所有相关 K8s 资源

高级用法

创建自己的 Chart

# 创建 Chart 骨架
helm create my-app                      # 生成标准目录结构

# my-app/
# ├── Chart.yaml          → Chart 元信息（名称、版本、描述）
# ├── values.yaml          → 默认参数值
# ├── charts/              → 依赖的子 Chart
# ├── templates/           → K8s 资源模板
# │   ├── deployment.yaml  → Deployment 模板
# │   ├── service.yaml     → Service 模板
# │   ├── ingress.yaml     → Ingress 模板
# │   ├── _helpers.tpl     → 模板辅助函数
# │   └── NOTES.txt        → 安装后提示信息
# └── .helmignore          → 打包时忽略的文件

# Chart.yaml — Chart 元信息
apiVersion: v2                          # Helm v3+ 使用 v2
name: my-app                            # Chart 名
description: 我的应用 Helm Chart         # 描述
type: application                       # 类型：application 或 library
version: 0.1.0                          # Chart 版本
appVersion: "1.0.0"                     # 应用版本

# templates/deployment.yaml — 使用 Go 模板语法
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}    # 引用 _helpers.tpl 的函数
  labels:
    {{- include "my-app.labels" . | nindent 4 }}  # 引用标签模板
spec:
  replicas: {{ .Values.replicaCount }}       # 从 values.yaml 读取副本数
  selector:
    matchLabels:
      {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}            # 使用 Chart 名
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"  # 镜像
          ports:
            - containerPort: {{ .Values.service.port }}  # 容器端口
          {{- if .Values.resources }}         # 条件判断
          resources:
            {{- toYaml .Values.resources | nindent 12 }}  # 转为 YAML
          {{- end }}

# 调试和测试 Chart
helm template my-app ./my-app           # 渲染模板（不安装）
helm template my-app ./my-app -f custom.yaml  # 用自定义值渲染
helm lint ./my-app                      # 检查 Chart 语法
helm install my-app ./my-app --dry-run  # 模拟安装（不实际执行）

# 打包和发布
helm package ./my-app                   # 打包为 .tgz 文件
helm push my-app-0.1.0.tgz oci://registry.example.com/charts  # 推送到 OCI 仓库

OCI Registry（新标准）

# 登录 OCI 仓库
helm registry login registry.example.com  # 登录镜像仓库

# 推送 Chart 到 OCI 仓库
helm push my-app-0.1.0.tgz oci://registry.example.com/charts

# 从 OCI 仓库安装
helm install my-app oci://registry.example.com/charts/my-app \
  --version 0.1.0                       # 指定版本

# 拉取 Chart
helm pull oci://registry.example.com/charts/my-app --version 0.1.0

依赖管理

# Chart.yaml — 声明依赖
dependencies:
  - name: postgresql                    # 依赖 PostgreSQL Chart
    version: "15.x.x"                   # 版本范围
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled        # 条件启用
  - name: redis                         # 依赖 Redis
    version: "19.x.x"
    repository: https://charts.bitnami.com/bitnami

# 下载依赖
helm dependency update ./my-app         # 下载到 charts/ 目录
helm dependency build ./my-app          # 构建依赖
helm dependency list ./my-app           # 查看依赖列表

常见报错

报错信息原因解决方案
Error: INSTALLATION FAILED: cannot re-use a nameRelease 名已存在换名或 helm uninstall 旧的
Error: chart requires kubeVersionK8s 版本不兼容升级集群或使用旧版 Chart
Error: template: ... not defined模板引用了不存在的变量检查 values.yaml 和模板
Error: UPGRADE FAILED: has no deployed releasesRelease 处于失败状态helm uninstall 后重新安装
Error: repo not found仓库未添加helm repo add 添加仓库

速查表

# === 仓库管理 ===
helm repo add NAME URL          # 添加仓库
helm repo update                # 更新索引
helm repo list                  # 列出仓库
helm repo remove NAME           # 删除仓库
helm search repo KEYWORD        # 搜索 Chart

# === Release 管理 ===
helm install NAME CHART         # 安装
helm upgrade NAME CHART         # 升级
helm rollback NAME [REVISION]   # 回滚
helm uninstall NAME             # 卸载
helm list                       # 列出 Release
helm status NAME                # 查看状态
helm history NAME               # 查看历史

# === Chart 开发 ===
helm create NAME                # 创建 Chart
helm template NAME PATH         # 渲染模板
helm lint PATH                  # 语法检查
helm package PATH               # 打包
helm push FILE REGISTRY         # 推送

# === 常用参数 ===
-f values.yaml                  # 指定 values 文件
--set key=value                 # 设置单个值
--namespace NS                  # 指定命名空间
--create-namespace              # 自动创建命名空间
--dry-run                       # 模拟运行
--wait                          # 等待资源就绪
--timeout 5m                    # 超时时间

同类对比

特性HelmKustomizeJsonnetCDK8s
方式模板化叠加补丁编程编程
语言Go 模板YAMLJsonnetTypeScript等
包管理有（Chart）无无无
学习曲线中等低高中等
回滚内置需 GitOps需 GitOps需 GitOps
生态最大K8s 内置小发展中
适合场景通用简单定制复杂配置程序员

选型建议：K8s 应用打包分发首选 Helm（生态最成熟、Chart 仓库最丰富）；简单的环境差异配置用 Kustomize（K8s 原生支持）；两者可以结合使用。