metahelm

README

Metahelm

[!WARNING] Unmaintained. Archived for reference — not recommended for use.

Metahelm is no longer developed or supported. The last commit was September 2021, and it is pinned to Helm 3.7 / Kubernetes 1.22 / Go 1.16-era libraries. Its health gating also only understands Deployments — there is no StatefulSet, DaemonSet, Job, or custom-resource readiness support, which is a real limitation given that the motivating example below puts databases and caches in the first install phase.

This repository stays public as a portfolio artifact. Two parts may still be worth reading:

• pkg/dag is a general concurrent dependency-level solver with DOT visualization, decoupled from Helm entirely via a three-method GraphObject interface. It imports nothing from Kubernetes or Helm and compiles standalone.
• pkg/metahelm/error.go turns a failed release into the failing pods and their logs, rather than Helm's timed out waiting for the condition.

The original dollarshaveclub/* repositories were deleted; this is the surviving copy.

To install charts in dependency order today, use Helmfile's needs: for DAG ordering with concurrent execution per group, or Argo CD sync waves if you are already running Argo — sync waves additionally gate on per-resource-kind health assessments, including custom Lua health checks for CRDs, which is the kind coverage Metahelm never gained. Flux's dependsOn covers the same ground.

Metahelm is a CLI and library for installing dependency graphs of Helm charts.

Why?

Helm dependency handling doesn't handle complex trees of dependencies well. It creates all Kubernetes objects at once and waits for them to settle into a consistent state.

With complex sets of dependency relationships, this means one or more applications go into CrashLoopBackoff, greatly lengthening the time for the entire tree to come up. Sometimes they will completely fail when one or more applications gives up entirely.

What does Metahelm do?

Metahelm takes a list of charts (as YAML) with dependency relationships specified, and optionally a way for Metahelm to tell when a chart is "up" or successful.

Metahelm will build a dependency graph (DAG) of the charts and install them in order such that all dependencies are satisfied prior to each chart install.

Sample YAML

Say you have a primary application ("YOLO") that depends upon several microservices to be running for the primary app to start. Those microservices are called "Alpha", "Bravo" and "Charlie". "Alpha" depends upon a MySQL database, "Bravo" needs PostgreSQL and all three need Redis.

An example YAML input might look like the following:

- name: YOLO
  path: /home/charts/yolo
  values_path: /home/releases/yolo/values.yml
  primary_deployment: yolo
  dependencies:
    - alpha
    - bravo
    - charlie
- name: alpha
  path: /home/charts/alpha
  values_path: /home/releases/alpha/values.yml
  primary_deployment: alpha
  wait_for_all_pods: true
  dependencies:
    - mysql
    - redis
- name: bravo
  path: /home/charts/bravo
  values_path: /home/releases/bravo/values.yml
  primary_deployment: bravo
  wait_for_all_pods: true
  dependencies:
    - postgres
    - redis
- name: charlie
  path: /home/charts/charlie
  values_path: /home/releases/charlie/values.yml
  primary_deployment: charlie
  wait_for_all_pods: true
  dependencies:
    - redis
- name: mysql
  path: /home/charts/mysql
  values_path: /home/releases/mysql/values.yml
  primary_deployment: mysql
- name: postgres
  path: /home/charts/postgres
  values_path: /home/releases/postgres/values.yml
  primary_deployment: postgres
- name: redis
  path: /home/charts/redis
  values_path: /home/releases/redis/values.yml
  primary_deployment: redis

Using metahelm plan -g produces a graph like this:

...and an execution plan:

Graph Root: YOLO
Phase 1: ["mysql" "postgres" "redis"]
Phase 2: ["charlie" "alpha" "bravo"]
Phase 3: ["YOLO"]

Phase 1 is installed first. The Mysql, postgres and redis charts would be installed in parallel. When they are all determined to be healthy, Phase 2 ("Charlie", "Alpha", "Bravo") would be installed in a similar fashion. Finally, Phase 3 ("YOLO") would be installed.

Building from source

Verified against Go 1.26 (August 2026): the vendored tree still compiles and all tests pass.

go build -mod=vendor ./...
go test -mod=vendor -tags safe ./pkg/...

The safe build tag is required for anything that actually builds a graph. Metahelm pins gonum to v0.9.1, whose graph iterators reach into Go runtime map internals via //go:linkname. Go 1.24 replaced Go's map implementation with Swiss tables, so that unsafe path now aborts with fatal error: concurrent map iteration and map write. The safe tag selects gonum's reflection-based iterator instead. Building without the tag still succeeds — the failure only appears at runtime. Every gonum release through v0.17.0 still contains the same //go:linkname code, so upgrading is not a fix; the build tag is.