praqma/helmsman

Helmsman 技术文档

注意：Helmsman v3.0.0 仅兼容 Helm 版本 >=3.0.0。对于旧版 Helm，请使用 Helmsman v1.x。

镜像概述和主要用途

Helmsman 是一个 Helm Charts（Kubernetes 应用）即代码工具，它允许您从版本控制的代码中自动化部署和管理 Helm 图表。通过声明式文件描述 Kubernetes 应用的期望状态，Helmsman 能够验证、比较当前状态并自动执行必要操作，以实现期望状态，适用于持续部署（CD）流程和 Kubernetes 应用的生命周期管理。

核心功能和特性

• 面向 CD 设计：可作为 Docker 镜像或二进制文件使用，无缝集成到 CI/CD 流程。
• 应用即代码：通过单个版本控制的声明式文件描述期望的应用状态并进行管理。
• 多租户集群支持：支持在不同命名空间部署 Tiller（v1.x 版本），并配置服务账户和 TLS。
• 易于使用：无需深入了解 Helm CLI 和 Kubectl 即可使用。
• 计划-查看-应用：可生成执行计划并查看，支持选择性执行。
• 可移植性：可用于管理任何 Kubernetes 集群上的图表部署。
• 命名空间/发布保护：可定义受保护的命名空间或发布，防止意外操作。
• 部署顺序控制：通过优先级定义发布的管理顺序（适用于依赖关系场景）。
• 并行执行：相同优先级的发布可并行执行。
• 幂等性：只要期望状态文件不变，多次执行 Helmsman 会得到相同结果。
• 故障恢复：部分部署失败后，修复问题后可直接重新执行，无需回滚成功部分。

使用场景和适用范围

• 持续部署流程：作为 CI/CD 管道的一部分，自动化 Helm 图表部署。
• 多租户 Kubernetes 集群：在共享集群中安全管理不同团队的应用部署。
• 版本控制的应用管理：通过 Git 等版本控制系统追踪和审计应用部署状态。
• 复杂依赖应用部署：通过优先级定义处理具有依赖关系的多应用部署。
• 本地开发与生产环境一致性：使用相同的声明式文件在不同环境中部署应用。

详细使用方法和配置说明

工作原理

Helmsman 使用简单的声明式 https://github.com/toml-lang/toml 或 YAML 文件描述应用的期望状态（https://github.com/Praqma/helmsman/blob/master/examples/example.toml%E3%80%81https://github.com/Praqma/helmsman/blob/master/examples/example.yaml%EF%BC%89%E3%80%82%E8%AF%A5%E6%9C%9F%E6%9C%9B%E7%8A%B6%E6%80%81%E6%96%87%E4%BB%B6%EF%BC%88DSF%EF%BC%89%E9%81%B5%E5%BE%AA https://github.com/Praqma/helmsman/blob/master/docs/desired_state_specification.md%E3%80%82

Helmsman 的工作流程包括：验证期望状态（如检查图表是否在定义的仓库中可用）、与 Helm 当前状态比较、生成执行计划并（可选）执行。

常用命令示例

• 生成执行计划（不执行）：

  sh
  helmsman -f example.toml
  

• 生成并执行计划：

  sh
  helmsman --apply -f example.toml
  

• 显示调试信息：

  sh
  helmsman --debug --apply -f example.toml
  

• 模拟执行（Dry-run）：

  sh
  helmsman --debug --dry-run -f example.toml
  

• 指定目标应用执行：

  sh
  helmsman --debug --dry-run --target artifactory -f example.toml
  

安装与部署

作为 Docker 镜像使用

Helmsman 官方镜像托管在 https://hub.docker.com/r/praqma/helmsman/tags/%EF%BC%8C%E5%BB%BA%E8%AE%AE%E4%BD%BF%E7%94%A8%E7%89%B9%E5%AE%9A%E7%89%88%E6%9C%AC%E6%A0%87%E7%AD%BE%EF%BC%88%E5%A6%82 v3.18.0）而非 latest 以确保稳定性。

Docker 运行示例：

sh
# 挂载当前目录（包含期望状态文件）到容器，生成执行计划
docker run --rm -v $(pwd):/apps \
  -v $HOME/.kube/config:/root/.kube/config \  # 挂载 Kubernetes 配置
  praqma/helmsman:v3.18.0 \
  -f /apps/example.toml

# 执行部署（--apply）
docker run --rm -v $(pwd):/apps \
  -v $HOME/.kube/config:/root/.kube/config \
  praqma/helmsman:v3.18.0 \
  --apply -f /apps/example.toml

其他安装方式

二进制安装

前置依赖：

• https://github.com/kubernetes/kubectl
• https://github.com/helm/helm%EF%BC%88Helmsman >=1.6.0 需 Helm >=2.10.0；Helmsman >=v3.0.0 需 Helm >=v3.0.0）
• https://github.com/databus23/helm-diff%EF%BC%88Helmsman >=1.6.0 required）

安装命令：

sh
# Linux
curl -L https://github.com/Praqma/helmsman/releases/download/v3.18.0/helmsman_3.18.0_linux_amd64.tar.gz | tar zx
# MacOS
curl -L https://github.com/Praqma/helmsman/releases/download/v3.18.0/helmsman_3.18.0_darwin_amd64.tar.gz | tar zx

mv helmsman /usr/local/bin/helmsman

包管理器安装

• Arch Linux：helmsman-bin（最新二进制版本）或 helmsman-git（开发版）
• Homebrew：

  sh
  brew install helmsman
  

asdf-vm 插件

sh
asdf plugin-add helmsman
asdf install helmsman latest

文档与更多资源

• 完整文档：
  • https://github.com/Praqma/helmsman/blob/master/docs/how_to/
  • https://github.com/Praqma/helmsman/blob/master/docs/desired_state_specification.md
  • https://github.com/Praqma/helmsman/blob/master/docs/cmd_reference.md
• 使用场景：
  • https://github.com/Praqma/helmsman/blob/master/docs/how_to/settings
  • https://github.com/Praqma/helmsman/blob/master/docs/how_to/deployments/ci.md
  • https://github.com/Praqma/helmsman/blob/master/docs/how_to/deployments/inside_k8s.md

注意：Helmsman v1.x 文档请参考 https://github.com/Praqma/helmsman/tree/1.x/docs%E3%80%82