1. Introduction to Helmsman
What is Helmsman?
Helmsman is an open-source tool that lets you declare and manage Helm chart deployments as code, using a simple Desired State File (DSF) written in YAML or JSON.
Helmsman adds governance, RBAC, drift detection, and advanced orchestration—addressing gaps in raw Helm and even other tools like Helmfile and Helmwave.
Key Features & Advantages
- Declarative deployment: Manage all releases, values, RBAC, and policies in a single DSF.
- RBAC & policy management: Built-in Kubernetes RBAC and team governance.
- Drift detection: Identify out-of-sync resources before making changes.
- Plan/apply workflows: Preview actions before executing.
- Release priorities & dependencies: Control install/upgrade order.
- GitOps & CI/CD friendly: Designed for automation pipelines.
- Secrets integration: Manage sensitive values securely.
2. Installation and Setup
Prerequisites
Install Helmsman
Via Homebrew (macOS/Linux):
brew install praqma/tap/helmsman
Via Binary Download:
- Go to Helmsman Releases.
- Download and extract for your OS.
- Move
helmsman
binary to your PATH.
Check Installation:
helmsman --version
3. Understanding the Desired State File (DSF) Structure
The DSF is a YAML or JSON file describing all releases, charts, environments, namespaces, priorities, RBAC, and more.
Minimal YAML Example
namespaces:
default:
installTiller: false
apps:
my-nginx:
namespace: default
enabled: true
chart: stable/nginx
version: 13.2.17
valuesFile: values/nginx.yaml
Code language: JavaScript (javascript)
Key Sections
- namespaces: Namespaces to manage or create.
- apps: List of Helm releases (name, chart, version, namespace, values, etc.).
- charts: (Optional) External chart sources.
- settings: Global options (kubeContext, helmRepos, etc.).
- rbac: (Optional) RBAC roles and bindings.
- environments: (Optional) Multiple cluster/environment support.
Pro Tip:
Helmsman also supports variable substitution and conditional logic for powerful configs.
4. Creating and Managing Simple Helm Releases
Step-by-Step Example
- Create a DSF file (
helmsman.yaml
):apps: my-nginx: namespace: default chart: stable/nginx version: 13.2.17 enabled: true valuesFile: values/nginx.yaml
- Apply your desired state:
helmsman -f helmsman.yaml --apply
- Upgrade a release:
Update your values or chart version and re-apply. - Delete a release:
Remove from DSF and run with--purge
.
5. Organizing Projects with Multiple Releases, Namespaces, and Charts
Helmsman can manage hundreds of releases in multiple namespaces.
namespaces:
frontend:
backend:
apps:
frontend-app:
namespace: frontend
chart: myorg/frontend
valuesFile: values/frontend.yaml
backend-app:
namespace: backend
chart: myorg/backend
valuesFile: values/backend.yaml
Tip:
Helmsman will auto-create namespaces if they don’t exist (unless you disable this in settings).
6. Setting Up Priorities and Controlling Release Ordering
Helmsman supports priorities (lower numbers first) and dependencies.
apps:
database:
namespace: backend
chart: bitnami/postgresql
priority: 1
api:
namespace: backend
chart: myorg/api
priority: 2
dependsOn:
- database
frontend:
namespace: frontend
chart: myorg/frontend
priority: 3
dependsOn:
- api
Code language: PHP (php)
Result:database
→ api
→ frontend
(order guaranteed).
7. Implementing RBAC and Policy Management
Helmsman can create and manage RBAC roles for your Helm releases.
rbac:
myteam:
namespaces: [frontend, backend]
role: admin
users: [alice, bob]
serviceAccounts: [ci-bot]
Code language: CSS (css)
- Supports custom roles and fine-grained permissions.
- Bind users/service accounts to namespaces for access control.
Tip:
You can also set up cluster-wide roles and restrict who can update what.
8. Using Drift Detection, Plan/Apply Workflows, and Dry Runs
Drift Detection
- Before applying changes, Helmsman detects “drift” between your DSF and what’s actually running.
helmsman -f helmsman.yaml --show-diff
Code language: CSS (css)
Plan Before Apply
- Preview actions without making changes:
helmsman -f helmsman.yaml --plan
Dry Run
- Simulate an upgrade or install:
helmsman -f helmsman.yaml --apply --dry-run
9. Integrating Secrets and Managing Configuration Securely
- Helmsman supports Helm secrets and environment variables.
- Reference encrypted files:
apps: secret-app: namespace: backend chart: myorg/secure secretsFile: secrets/app-secrets.yaml
- Use variables:
settings: envVars: DB_PASSWORD: ${DB_PASSWORD}
- Pass env vars from your shell or CI/CD.
10. Managing Environments and Release Conditions
- Helmsman supports environments for multiple clusters or namespaces.
environments: dev: kubeContext: dev-cluster namespace: dev prod: kubeContext: prod-cluster namespace: prod
- Reference with:
helmsman -f helmsman.yaml --environment dev --apply
- Conditional releases:
Deploy certain apps only in specific environments:apps: canary: namespace: frontend enabled: ${ENVIRONMENT == "dev"}
11. Incorporating Helmsman into CI/CD and GitOps Workflows
Example: GitHub Actions Workflow
- name: Install Helmsman
run: brew install praqma/tap/helmsman
- name: Deploy with Helmsman
env:
KUBECONFIG: ${{ secrets.KUBECONFIG }}
DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
run: |
helmsman -f helmsman.yaml --apply
Code language: JavaScript (javascript)
Tips:
- Store secrets in your CI/CD secret manager.
- Use plan/diff in PRs, apply on merge.
12. Troubleshooting, Debugging, and Best Practices
Debugging Tools
- Use verbose mode:
helmsman -f helmsman.yaml --apply --debug
- Check drift:
helmsman -f helmsman.yaml --show-diff
- Helm log inspection:
helm list -A helm status <release>
Best Practices
- Use priorities and dependencies for reliability.
- Separate environments in different DSFs or use
environments
. - Encrypt all secrets and sensitive values.
- Keep your DSF and values in version control.
- Use selectors/labels to operate on subsets of releases.
13. Real-World Examples and Sample Configurations
Microservices Example
namespaces:
user:
order:
payment:
apps:
user-service:
namespace: user
chart: myorg/user
valuesFile: values/user.yaml
priority: 1
order-service:
namespace: order
chart: myorg/order
valuesFile: values/order.yaml
dependsOn: [user-service]
priority: 2
payment-service:
namespace: payment
chart: myorg/payment
valuesFile: values/payment.yaml
dependsOn: [order-service]
priority: 3
14. Comparison with Helmfile, Helmwave, and When to Choose Helmsman
Feature | Helmsman | Helmfile | Helmwave |
---|---|---|---|
RBAC/Policy Mgmt | ✅ (core) | ⚠️ (some) | ⚠️ (some) |
Drift Detection | ✅ | 🚫 | 🚫 |
Declarative Config | ✅ | ✅ | ✅ |
Release Priorities | ✅ | ⚠️ (needs) | ✅ (graph) |
Plan/Apply Workflow | ✅ | ✅ | ✅ |
Environments | ✅ | ✅ | ✅ |
Secrets Mgmt | ✅ | ✅ | ✅ |
Parallelism | 🚫 | 🚫 | ✅ |
CI/CD Friendly | ✅ | ✅ | ✅ |
When to Choose Helmsman
- You need built-in RBAC, governance, and drift detection.
- Large organizations managing hundreds of releases with strong compliance needs.
- You want a clear “plan/apply” workflow with audit trails.
Conclusion
Helmsman is an enterprise-grade tool for Kubernetes release orchestration, governance, and automation.
It’s powerful for both small and large teams, making release management predictable, auditable, and secure—from development to production.
Further Reading & Resources
I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.
Do you want to learn Quantum Computing?
Please find my social handles as below;
Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND