Helmsman Tutorial: From Beginner to Advanced

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

Helm 3.x
kubectl
Access to a Kubernetes cluster

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.