Upgrade & Secure Your Future with DevOps, SRE, DevSecOps, MLOps!

We spend hours scrolling social media and waste money on things we forget, but won’t spend 30 minutes a day earning certifications that can change our lives.
Master in DevOps, SRE, DevSecOps & MLOps by DevOpsSchool!

Learn from Guru Rajesh Kumar and double your salary in just one year.


Get Started Now!

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

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

  1. Create a DSF file (helmsman.yaml): apps: my-nginx: namespace: default chart: stable/nginx version: 13.2.17 enabled: true valuesFile: values/nginx.yaml
  2. Apply your desired state: helmsman -f helmsman.yaml --apply
  3. Upgrade a release:
    Update your values or chart version and re-apply.
  4. 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:
databaseapifrontend (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

FeatureHelmsmanHelmfileHelmwave
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


Subscribe
Notify of
guest
0 Comments
Newest
Oldest Most Voted
Inline Feedbacks
View all comments

Certification Courses

DevOpsSchool has introduced a series of professional certification courses designed to enhance your skills and expertise in cutting-edge technologies and methodologies. Whether you are aiming to excel in development, security, or operations, these certifications provide a comprehensive learning experience. Explore the following programs:

DevOps Certification, SRE Certification, and DevSecOps Certification by DevOpsSchool

Explore our DevOps Certification, SRE Certification, and DevSecOps Certification programs at DevOpsSchool. Gain the expertise needed to excel in your career with hands-on training and globally recognized certifications.

0
Would love your thoughts, please comment.x
()
x