Helm3 完整安装配置教程

1. Helm3 完整安装+配置教程

核心概念 Helm 3 彻底移除 Tiller，纯客户端运行，通过 kubeconfig 直接调用 apiserver，是生产标准部署方式。

2. 前置说明

当前生产统一使用 Helm 3，已废弃 Helm2（带Tiller，架构缺陷），下文全部基于 Helm 3.14+ 稳定版。

环境：CentOS / Ubuntu，Kubernetes 1.24+，containerd。

3. Helm 客户端安装（单机安装，只需装本地工具）

4. 方式1：官方脚本一键安装（推荐，通用）


# 下载执行官方安装脚本

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 验证安装

helm version

输出类似代表成功：


version.BuildInfo{Version:"v3.15.2", GitCommit:"...", GoVersion:"go1.22.4"}

5. 方式2：手动二进制包安装（离线内网环境）

下载对应系统安装包：
https://github.com/helm/helm/releases
示例 linux amd64：helm-v3.15.2-linux-amd64.tar.gz


# 解压

tar -zxvf helm-v3.15.2-linux-amd64.tar.gz

# 移动二进制到系统PATH

mv linux-amd64/helm /usr/local/bin/

# 赋权

chmod +x /usr/local/bin/helm

# 验证

helm version

6. 方式3：yum/apt包管理器


# CentOS/RHEL

yum install helm -y

# Ubuntu

apt update && apt install helm -y

7. 环境变量补全（可选，方便运维）

7.1. 命令自动补全


# bash

helm completion bash > /etc/bash_completion.d/helm

source /etc/profile

# zsh

helm completion zsh > ~/.zsh/_helm

source ~/.zshrc

7.2. 配置helm全局缓存目录（多用户/离线场景）

helm 默认缓存路径：~/.cache/helm

可自定义环境变量永久修改：


echo 'export HELM_CACHE_HOME=/data/helm/cache' >> /etc/profile

echo 'export HELM_CONFIG_HOME=/data/helm/config' >> /etc/profile

echo 'export HELM_DATA_HOME=/data/helm/data' >> /etc/profile

source /etc/profile

8. 核心前置依赖：kubeconfig 连通集群

helm 本身无服务端，完全依赖本地 kubeconfig 访问 apiserver。

9. 默认读取规则

helm 自动读取：~/.kube/config

10. 多集群切换方式

10.1. 方式A：环境变量指定kubeconfig


export KUBECONFIG=/root/kube-prod.config

helm list -n default

10.2. 方式B：切换kubectl上下文（helm共用）


kubectl config use-context prod-cluster

helm list

11. 校验连通性


helm ls --all-namespaces

# 无报错、正常列出release代表集群连通正常

12. 仓库 Repo 配置（最常用配置）

13. 基础命令语法


# 添加仓库

helm repo add [仓库名] [仓库地址]

# 更新仓库索引（拉取chart列表）

helm repo update

# 查看已添加仓库

helm repo list

# 删除仓库

helm repo remove [仓库名]

14. 常用公有仓库示例


# Bitnami 主流中间件 mysql/redis/nginx

helm repo add bitnami https://charts.bitnami.com/bitnami

# NVIDIA GPU Operator

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia

# Prometheus Operator

helm repo add prom-community https://prometheus-community.github.io/helm-charts

# 更新所有源

helm repo update

15. 私有OCI仓库（Harbor，企业主流）

Helm3 原生支持 OCI 镜像仓库，替代旧ChartMuseum：


# 登录harbor OCI仓库

helm registry login harbor.example.com -u admin -p Harbor12345

# 拉取私有chart

helm pull oci://harbor.example.com/library/mysql --version 9.0.0

# 直接安装OCI chart

helm install mysql oci://harbor.example.com/library/mysql -n db

16. 仓库搜索、查看参数


# 搜索mysql

helm search repo mysql

# 查看chart默认values配置

helm show values bitnami/mysql

# 查看chart详细信息

helm show chart bitnami/mysql

17. Chart 部署相关配置（安装/升级核心配置）

18. values 配置文件分层覆盖规则

优先级从低到高：

chart 内置 values.yaml
自定义环境文件 -f values-dev.yaml、-f values-prod.yaml
命令行临时覆盖 --set / --set-string / --set-json 示例多文件叠加：


# 基础通用配置 + 生产覆盖配置

helm install app ./mychart -n prod \

-f ./mychart/values.yaml \

-f ./values-prod.yaml

19. 常用覆盖参数示例


# 普通字符串/数字

helm upgrade app ./chart --set replicaCount=3

# 字符串避免自动转数字

--set-string image.tag="v1.2.0"

# 数组覆盖

--set env[0].name="HTTP_PROXY",env[0].value="http://proxy:8080"

# json复杂结构

--set-json resources.limits='{"cpu":"2","memory":"4Gi"}'

# 布尔开关

--set ingress.enabled=true

20. 安装全局公共参数（运维必记）


-n/--namespace       指定命名空间

--create-namespace   不存在则自动创建ns

--dry-run            模拟安装，仅渲染不提交API，校验语法

--debug              输出完整渲染日志，排错用

--version            指定chart版本安装

--wait               等待所有pod就绪才返回（超时5m）

--timeout 10m        自定义就绪等待超时

--atomic             安装失败自动回滚（生产强烈推荐）

--cleanup-on-fail    失败清理资源

生产标准安装命令模板：


helm install web ./web-chart -n online \

-f values-prod.yaml \

--version 1.2.0 \

--wait --timeout 5m --atomic

21. 生产环境高阶配置

22. 配置仓库本地缓存（离线机房）

内网无法访问外网源，提前pull chart到本地打包部署：


# 拉取chart到本地

helm pull bitnami/mysql --untar --version 9.0.0

# 本地目录直接安装，无需外网仓库

helm install mysql ./mysql -n db

23. 依赖管理配置（Chart内部子依赖）

Chart.yaml 中定义依赖：


dependencies:

  - name: redis

    repository: "oci://harbor.example.com/bitnami"

    version: "18.x.x"

    condition: redis.enabled

下载依赖到本地 charts/ 目录：


helm dependency update ./mychart

# 校验依赖完整性

helm dependency build ./mychart

24. values.schema.json 参数校验配置

在Chart目录新建 values.schema.json，限制参数类型、必填项，安装前自动校验，避免配置错误：


{

  "$schema": "https://json-schema.org/draft-07/schema#",

  "type": "object",

  "properties": {

    "replicaCount": {

      "type": "integer",

      "minimum": 1

    },

    "image.repository": {

      "type": "string"

    }

  },

  "required": ["image.repository"]

}

执行安装时自动校验，参数非法直接终止发布。

25. 全局TLS/代理配置（内网代理环境）

25.1. （1）全局HTTP代理


# 永久写入环境变量

echo 'export HTTP_PROXY=http://10.0.0.10:8080' >> /etc/profile

echo 'export HTTPS_PROXY=http://10.0.0.10:8080' >> /etc/profile

echo 'export NO_PROXY=127.0.0.1,localhost,.svc.cluster.local' >> /etc/profile

source /etc/profile

25.2. （2）私有仓库自签证书

存放证书到系统信任目录，或指定证书文件：


helm registry login harbor.example.com --ca-file /etc/pki/harbor.crt

26. RBAC 权限配置（多租户集群核心配置）

helm 无独立权限体系，完全复用 k8s RBAC，需要给执行helm的账号分配对应权限。

27. 场景：开发仅拥有test命名空间部署权限

创建serviceAccount、Role、RoleBinding


apiVersion: v1

kind: ServiceAccount

metadata:

  name: helm-user

  namespace: test

---

apiVersion: rbac.authorization.k8s.io/v1

kind: Role

metadata:

  namespace: test

  name: helm-deploy

rules:

- apiGroups: ["*"]

  resources: ["*"]

  verbs: ["create","update","patch","delete","get","list","watch"]

---

apiVersion: rbac.authorization.k8s.io/v1

kind: RoleBinding

metadata:

  namespace: test

  name: helm-deploy-bind

subjects:

- kind: ServiceAccount

  name: helm-user

roleRef:

  kind: Role

  name: helm-deploy

  apiGroup: rbac.authorization.k8s.io

导出sa token作为kubeconfig，给开发使用helm操作test命名空间。

28. CI/CD流水线标准配置（企业自动化）

流水线预装helm客户端；
注入kubeconfig secret到CI环境；
内置私有Harbor OCI登录凭证；
发布流程标准步骤：


# 1. 更新依赖

helm dependency update ./chart

# 2. 语法、参数校验

helm lint ./chart

# 3. 模拟渲染校验

helm template ./chart -f values-prod.yaml

# 4. 正式升级，失败自动回滚

helm upgrade --atomic --wait app ./chart -f values-prod.yaml

29. 常见配置问题排查

helm connect refused / apiserver 连接失败
检查kubeconfig、集群LB、安全组是否放行6443端口；
pull chart 超时
配置HTTP代理或切换内网私有仓库；
OCI仓库登录证书报错
导入Harbor自签CA证书，或命令指定—ca-file；
权限不足 forbidden
给当前ServiceAccount补充对应命名空间RBAC权限；
模板渲染报错缩进/变量不存在
使用 helm template --debug 输出详细报错定位模板行。

YancheBlog

热门标签

Helm3 完整安装配置教程

Helm3 完整安装配置教程

1. Helm3 完整安装+配置教程

2. 前置说明

3. Helm 客户端安装（单机安装，只需装本地工具）

4. 方式1：官方脚本一键安装（推荐，通用）

5. 方式2：手动二进制包安装（离线内网环境）

6. 方式3：yum/apt包管理器

7. 环境变量补全（可选，方便运维）

7.1. 命令自动补全

7.2. 配置helm全局缓存目录（多用户/离线场景）

8. 核心前置依赖：kubeconfig 连通集群

9. 默认读取规则

10. 多集群切换方式

10.1. 方式A：环境变量指定kubeconfig

10.2. 方式B：切换kubectl上下文（helm共用）

11. 校验连通性

12. 仓库 Repo 配置（最常用配置）

13. 基础命令语法

14. 常用公有仓库示例

15. 私有OCI仓库（Harbor，企业主流）

16. 仓库搜索、查看参数

17. Chart 部署相关配置（安装/升级核心配置）

18. values 配置文件分层覆盖规则

19. 常用覆盖参数示例

20. 安装全局公共参数（运维必记）

21. 生产环境高阶配置

22. 配置仓库本地缓存（离线机房）

23. 依赖管理配置（Chart内部子依赖）

24. values.schema.json 参数校验配置

25. 全局TLS/代理配置（内网代理环境）

25.1. （1）全局HTTP代理

25.2. （2）私有仓库自签证书

26. RBAC 权限配置（多租户集群核心配置）

27. 场景：开发仅拥有test命名空间部署权限

28. CI/CD流水线标准配置（企业自动化）

29. 常见配置问题排查

目录