2. Helm 安装与配置：客户端安装、仓库管理与基础操作

Helm 是 Kubernetes 生态中事实上的包管理标准。在生产环境中，Helm 客户端安装的正确性、仓库源的稳定性以及基础命令的熟练度，直接决定了后续 Chart 发布与治理的效率。本章将围绕 Helm 客户端的安装方式、仓库的增删改查、以及最常用的 repo update、search、list 操作展开，确保你能够快速搭建一个可用的 Helm 工作环境。

2.1 Helm 客户端安装

Helm 客户端是一个二进制工具，支持多种安装方式。生产环境推荐使用官方脚本或包管理器进行安装，以确保版本一致性和可追溯性。

2.1.1 安装方式对比

安装方式 适用场景 命令示例 注意事项
官方脚本 快速安装、CI/CD 环境 curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash 需确保网络可达 GitHub
包管理器（Linux） 本地开发、服务器管理 apt install helm / yum install helm 版本可能滞后，需确认仓库源
Homebrew（macOS） macOS 开发者 brew install helm 自动处理依赖
二进制下载 离线环境、版本锁定 从 https://get.helm.sh 下载 tar.gz 需手动配置 PATH
生产建议： 在离线或内网环境中，优先使用二进制下载方式，并将 Helm 二进制文件纳入公司制品库管理，避免因外网源不可用导致安装失败。

2.1.2 验证安装

安装完成后，执行以下命令验证版本和集群连通性：

# 查看 Helm 版本
helm version

# 查看 Helm 环境变量
helm env

# 测试与 Kubernetes 集群的连通性（需已配置 kubeconfig）
helm list -n kube-system

如果 helm version 正常输出，且 helm list 不报错，则说明客户端安装成功且已正确连接到集群。

2.2 添加与移除仓库

Helm 仓库（Repository）是存储 Chart 包的 HTTP 服务器。添加仓库后，你可以从仓库中搜索和安装 Chart。生产环境中，通常需要添加官方稳定仓库、内部私有仓库以及第三方可信仓库。

2.2.1 常用仓库添加

# 添加官方稳定仓库（Bitnami 是社区最活跃的 Chart 源之一）
helm repo add bitnami https://charts.bitnami.com/bitnami

# 添加官方 Helm 稳定仓库（已归档，但部分旧 Chart 仍可用）
helm repo add stable https://charts.helm.sh/stable

# 添加内部私有仓库（示例地址，请替换为实际仓库 URL）
helm repo add internal-repo https://harbor.company.com/chartrepo/library

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

2.2.2 查看与移除仓库

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

# 移除指定仓库
helm repo remove bitnami

# 移除所有仓库（谨慎使用）
helm repo remove $(helm repo list -q)
注意： 移除仓库后，之前从该仓库安装的 Chart 不会自动删除，但后续的 helm search 和 helm upgrade 将无法从该仓库获取更新。建议在移除前确认没有正在使用的 Chart 依赖该仓库。

2.3 helm repo update：同步仓库索引

添加仓库后，本地并不会立即拥有该仓库的 Chart 列表。必须执行 helm repo update 命令，从远程仓库下载最新的 index.yaml 索引文件，才能进行搜索和安装。

# 更新所有已添加的仓库
helm repo update

# 更新指定仓库
helm repo update bitnami

# 查看更新后的仓库状态
helm repo list

helm repo update 会将远程仓库的索引缓存到本地 ~/.cache/helm/repository/ 目录下。缓存文件默认保留 24 小时，但建议在每次执行 helm search 或 helm install 前手动更新，以确保获取到最新版本。

运维要点： 在 CI/CD 流水线中，建议在每次 Helm 操作前显式执行 helm repo update，避免因缓存过期导致安装到旧版本 Chart。

2.4 helm search：搜索 Chart

helm search 命令支持两种搜索模式：hub（搜索 Helm Hub 上的所有仓库）和 repo（搜索本地已添加的仓库）。生产环境中，helm search repo 是更常用的方式。

2.4.1 搜索语法

# 搜索本地仓库中的 Chart（模糊匹配）
helm search repo nginx

# 搜索指定仓库中的 Chart
helm search repo bitnami/nginx

# 使用正则表达式搜索
helm search repo 'nginx.*ingress'

# 搜索 Helm Hub（需联网）
helm search hub nginx

2.4.2 搜索结果解读

字段 说明 示例
NAME Chart 全名（仓库名/Chart名） bitnami/nginx
CHART VERSION Chart 的版本号 18.0.3
APP VERSION Chart 内包含的应用版本号 1.25.3
DESCRIPTION Chart 的简要描述 NGINX web server
最佳实践： 搜索时注意区分 CHART VERSION 和 APP VERSION。Chart 版本由 Chart 维护者控制，App 版本由上游应用控制。在治理过程中，应优先锁定 Chart 版本，而非 App 版本。

2.5 helm list：查看已安装的 Release

helm list 用于查看当前集群中已部署的 Helm Release。这是日常运维中最频繁使用的命令之一。

2.5.1 基本用法

# 列出当前命名空间下的所有 Release
helm list

# 列出所有命名空间下的 Release
helm list --all-namespaces

# 列出已卸载但未清理的 Release
helm list --uninstalled

# 列出所有状态（包括已卸载、已失败等）
helm list --all

# 按名称过滤
helm list --filter 'nginx*'

2.5.2 输出字段说明

字段 说明 示例
NAME Release 名称 my-nginx
NAMESPACE Release 所在的命名空间 default
REVISION 当前 Release 的修订版本号 3
UPDATED 最近一次更新的时间 2024-01-15 10:30:00
STATUS Release 的当前状态 deployed
CHART 使用的 Chart 名称和版本 nginx-18.0.3
APP VERSION Chart 内应用的实际版本 1.25.3

2.5.3 Release 状态说明

  • deployed：Release 已成功部署并正在运行。
  • failed：Release 部署失败，需要排查原因。
  • pending-install：正在安装中，尚未完成。
  • pending-upgrade：正在升级中，尚未完成。
  • uninstalled：Release 已被卸载，但历史记录保留。
  • superseded：Release 已被新版本替代，历史版本保留。
注意： 如果 helm list 输出为空，请确认当前 kubeconfig 的上下文是否正确，以及是否指定了正确的命名空间。使用 kubectl config current-context 检查当前集群。

2.6 基础操作流程 SVG 图

下图展示了 Helm 客户端安装完成后，从仓库管理到 Release 查看的完整基础操作流程：

Helm 基础操作流程 Helm 基础操作流程 1. 安装 Helm 客户端 2. helm repo add 3. helm repo update 4. helm search repo 5. helm list 提示：每次执行 helm search 或 helm install 前，建议先执行 helm repo update 确保索引最新

2.7 仓库管理与 Release 状态 SVG 图

下图展示了 Helm 仓库的生命周期管理以及 Release 在不同状态之间的转换关系：

Helm 仓库与 Release 状态转换 Helm 仓库与 Release 状态转换 仓库生命周期 helm repo add helm repo update helm repo list helm repo remove Release 状态转换 deployed（已部署） pending-upgrade（升级中） failed（失败） uninstalled（已卸载） 仓库索引提供 Chart 版本 最佳实践：生产环境中建议使用 helm list --all-namespaces 定期巡检所有 Release 状态

2.8 常见问题与避坑指南

问题 1： helm repo update 报错 failed to fetch 或 timeout。
原因： 网络不通或仓库 URL 已变更。
解决： 检查网络代理设置，使用 curl -I <仓库URL> 测试连通性；确认仓库 URL 是否仍有效，必要时联系仓库维护者。
问题 2： helm search repo 找不到刚添加的 Chart。
原因： 忘记执行 helm repo update 或仓库索引尚未同步。
解决： 先执行 helm repo update，再重新搜索。
问题 3： helm list 输出为空，但集群中确实有 Release。
原因： 当前 kubeconfig 的命名空间或集群上下文不正确。
解决： 使用 kubectl config current-context 确认上下文；使用 helm list --all-namespaces 跨命名空间搜索。

2.9 本章小结

通过本章的学习，你应掌握以下核心技能：

  • 能够通过多种方式安装 Helm 客户端，并验证安装结果。
  • 熟练使用 helm repo add、helm repo remove、helm repo list 管理仓库。
  • 理解 helm repo update 的作用，并养成在操作前更新索引的习惯。
  • 能够使用 helm search repo 快速定位目标 Chart。
  • 通过 helm list 查看 Release 状态，并理解不同状态的含义。

这些基础操作是后续进行 Chart 安装、升级、回滚以及治理策略的前提。请务必在真实环境中反复练习，直到形成肌肉记忆。

← 上一章 📖 返回目录 下一章 →