Helm 常用命令技术文档

This article is extracted from the chat log with AI. Please identify it with caution.

AI 协助说明： 本页由 Codex 协助核验和修复站内链接；正文的技术事实和适用范围未因本次修改而改变，仍以文中来源及当前官方文档为准。

本文边界：本文是 Helm CLI 的常用命令速查，重点回答如何执行；Chart、values 与 Release 的概念和状态边界请参阅概念文档。

推荐深读：Helm 核心概念详解。

1. 概述#

Helm 是 Kubernetes 的包管理器，用于简化应用的部署、升级和管理。本文档介绍 Helm 的常用命令及其用法。

2. 环境准备与初始化#

2.1 安装 Helm#

# macOS (Homebrew)
brew install helm

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

# Windows (Chocolatey)
choco install kubernetes-helm

2.2 验证安装#

helm version
# 或
helm version --short

3. 仓库管理命令#

3.1 添加仓库#

# 添加官方稳定仓库
helm repo add stable https://charts.helm.sh/stable

# 添加 Bitnami 仓库
helm repo add bitnami https://charts.bitnami.com/bitnami

# 添加自定义仓库
helm repo add myrepo http://myrepo.example.com/charts

3.2 列出仓库#

# 查看已添加的仓库
helm repo list

# 详细输出
helm repo list -o yaml

3.3 更新仓库#

# 更新所有仓库
helm repo update

# 更新特定仓库
helm repo update stable

3.4 移除仓库#

helm repo remove bitnami

4. 搜索与查找命令#

4.1 搜索 Chart#

# 从所有仓库搜索
helm search repo nginx

# 从特定仓库搜索
helm search repo bitnami/nginx

# 搜索所有版本
helm search repo nginx -l

# 从 Artifact Hub 搜索（无需添加仓库）
helm search hub wordpress

4.2 查看 Chart 信息#

# 查看 Chart 详情
helm show chart bitnami/nginx

# 查看所有信息
helm show all bitnami/nginx

# 查看 values.yaml
helm show values bitnami/nginx

# 查看 README
helm show readme bitnami/nginx

5. 安装与部署命令#

5.1 基本安装#

# 从仓库安装
helm install my-nginx bitnami/nginx

# 指定命名空间
helm install my-nginx bitnami/nginx -n my-namespace
# 或
helm install my-nginx bitnami/nginx --namespace my-namespace

# 安装时指定 values 文件
helm install my-nginx bitnami/nginx -f custom-values.yaml

# 安装时覆盖参数
helm install my-nginx bitnami/nginx --set replicaCount=3
helm install my-nginx bitnami/nginx --set service.type=LoadBalancer

5.2 高级安装选项#

# 指定版本
helm install my-nginx bitnami/nginx --version 13.2.1

# 生成 manifest 但不安装（dry-run）
helm install my-nginx bitnami/nginx --dry-run

# 调试模式（显示详细输出）
helm install my-nginx bitnami/nginx --debug

# 等待部署完成
helm install my-nginx bitnami/nginx --wait

# 设置超时时间
helm install my-nginx bitnami/nginx --timeout 5m

5.3 从本地文件安装#

# 从本地 Chart 目录安装
helm install my-app ./my-chart

# 从打包的 Chart 安装
helm install my-app ./my-chart-1.0.0.tgz

# 从 OCI 仓库安装
helm install my-app oci://registry.example.com/charts/my-app

6. 升级与回滚命令#

6.1 升级 Release#

# 基本升级
helm upgrade my-nginx bitnami/nginx

# 升级到指定版本
helm upgrade my-nginx bitnami/nginx --version 13.2.2

# 升级时更新 values
helm upgrade my-nginx bitnami/nginx -f new-values.yaml

# 升级时覆盖参数
helm upgrade my-nginx bitnami/nginx --set replicaCount=5

# 重置 values 到 Chart 默认值
helm upgrade my-nginx bitnami/nginx --reset-values

6.2 查看历史记录#

# 查看发布历史
helm history my-nginx

# 详细输出
helm history my-nginx -o yaml

# 显示最大数量
helm history my-nginx --max 10

6.3 回滚 Release#

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

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

# 等待回滚完成
helm rollback my-nginx 2 --wait

7. 查看与管理 Release#

7.1 列出 Release#

# 列出当前命名空间的 Release
helm list
# 或
helm ls

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

# 指定命名空间
helm list -n my-namespace

# 按时间排序
helm list --date

# JSON 输出
helm list -o json

7.2 查看 Release 状态#

# 查看状态
helm status my-nginx

# 查看资源
helm get manifest my-nginx

# 查看 values
helm get values my-nginx

# 查看所有配置
helm get all my-nginx

# 查看 hooks
helm get hooks my-nginx

# 查看 notes
helm get notes my-nginx

7.3 卸载 Release#

# 卸载 Release
helm uninstall my-nginx

# 卸载时保留历史
helm uninstall my-nginx --keep-history

# 强制卸载（即使失败也继续）
helm uninstall my-nginx --no-hooks

# 指定超时时间
helm uninstall my-nginx --timeout 5m

8. Chart 开发与打包命令#

8.1 创建 Chart#

# 创建新 Chart
helm create my-chart

# 创建时指定 API 版本
helm create my-chart --api-version v2

8.2 验证 Chart#

# 验证 Chart 格式
helm lint ./my-chart

# 严格验证
helm lint ./my-chart --strict

# 验证并输出详细信息
helm lint ./my-chart --debug

8.3 打包与发布#

# 打包 Chart
helm package ./my-chart

# 指定版本号
helm package ./my-chart --version 1.2.3

# 指定应用版本
helm package ./my-chart --app-version 2.0.0

# 指定输出目录
helm package ./my-chart --destination ./packages

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

8.4 依赖管理#

# 更新依赖
helm dependency update ./my-chart

# 构建依赖
helm dependency build ./my-chart

# 列出依赖
helm dependency list ./my-chart

9. 模板操作命令#

9.1 渲染模板#

# 渲染模板（本地查看）
helm template my-app ./my-chart

# 指定 values 文件
helm template my-app ./my-chart -f values.yaml

# 覆盖参数
helm template my-app ./my-chart --set replicaCount=2

# 输出到文件
helm template my-app ./my-chart > manifest.yaml

# 渲染特定命名空间
helm template my-app ./my-chart -n my-namespace

9.2 调试模板#

# 显示渲染的模板
helm install --dry-run --debug my-app ./my-chart

# 使用模板函数调试
helm template my-app ./my-chart --debug

10. 插件管理命令#

10.1 插件操作#

# 安装插件
helm plugin install https://github.com/databus23/helm-diff

# 列出已安装插件
helm plugin list

# 更新插件
helm plugin update diff

# 卸载插件
helm plugin uninstall diff

10.2 常用插件#

# helm-diff：查看变更
helm diff upgrade my-app ./my-chart

# helm-secrets：管理加密 values
helm secrets install my-app ./my-chart -f secrets.yaml

# helm-git：从 Git 仓库安装
helm git install https://github.com/example/charts.git

11. 环境与配置命令#

11.1 环境变量#

# 查看环境配置
helm env

# 设置环境变量
export HELM_NAMESPACE=production
export HELM_KUBECONTEXT=prod-cluster

11.2 配置管理#

# 查看当前配置
helm get values my-app

# 查看指定修订版的配置
helm get values my-app --revision 3

# 输出为 yaml
helm get values my-app -o yaml

12. 实用命令示例#

12.1 一键部署 WordPress#

# 添加仓库
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# 部署 WordPress
helm install my-wordpress bitnami/wordpress \
  --namespace wordpress \
  --set wordpressUsername=admin \
  --set wordpressPassword=password \
  --set mariadb.auth.rootPassword=secretpassword \
  --wait \
  --timeout 10m

12.2 升级并验证#

# 检查升级变更
helm diff upgrade my-app ./my-chart

# 执行升级
helm upgrade my-app ./my-chart \
  --values values.yaml \
  --set image.tag=v2.0.0 \
  --wait \
  --timeout 5m

# 验证升级
helm status my-app
kubectl get pods -l app=my-app

12.3 清理旧 Release#

# 查看失败的 Release
helm list --failed

# 删除所有失败状态的 Release
helm list --failed --short | xargs -L1 helm uninstall

# 删除指定天数之前的 Release
helm list --date | grep "days ago" | awk '{print $1}' | xargs -L1 helm uninstall

13. 常用命令速查表#

功能命令
安装helm install <name> <chart>
升级helm upgrade <release> <chart>
回滚helm rollback <release> <revision>
卸载helm uninstall <release>
列表helm list 或 helm ls
查看状态helm status <release>
查看历史helm history <release>
搜索helm search repo <keyword>
添加仓库helm repo add <name> <url>
更新仓库helm repo update
创建 Charthelm create <name>
打包 Charthelm package <path>
验证 Charthelm lint <path>
渲染模板helm template <name> <chart>

14. 注意事项#

  1. 命名空间：默认使用 default 命名空间，可通过 -n 或 --namespace 指定
  2. 版本管理：每次升级都会创建一个新的修订版
  3. 资源清理：卸载时默认删除所有相关资源
  4. 配置管理：建议使用 values 文件管理配置，而非命令行参数
  5. 生产环境：推荐使用 --wait 和 --timeout 参数确保部署成功

15. 故障排除#

# 查看详细错误信息
helm install --debug --dry-run

# 检查 Kubernetes 配置
kubectl config view

# 检查集群连接
kubectl cluster-info

# 查看 Helm 事件
kubectl get events --sort-by='.lastTimestamp'

本文档覆盖了 Helm 的常用命令，实际使用中可结合具体场景选择合适的命令和参数。

本文共 1955 字，创建于 Dec 16, 2025

相关标签： Kubernetes, Linux, ByAI

Backward Kubernetes 集群版本升级方案梳理 Helm 核心概念详解 Forward