Skip to content

helmfile2compose

For when you just wanted to maintain a nice helmfile but people kept asking for a docker-compose — then it got REALLY out of hand

Convert Kubernetes manifests to compose.yml + Caddyfile. Not Kubernetes-in-Docker (kind, k3d, minikube...) — no cluster, no kubelet, no shim. A devolution of the power of Kubernetes into the simplicity of compose: real docker compose up, real Caddy, plain stupid containers.

Here because this upmost abomination is causing issues? Here's the path to (partial) redemption: Troubleshooting.

But why?

There are dozens of tools that go from Compose to Kubernetes (Kompose, Compose Bridge, Move2Kube, etc.) — that's the "normal" direction. Almost nothing goes the other way, because who would design their deployment in K8s first and then downgrade?

Using Kubernetes manifests as an intermediate representation to generate a docker-compose is absolutely using an ICBM to kill flies — which is exactly why I find it satisfying.

The name is helmfile2compose because both helmfile and docker-compose share the same purpose: deploying an entire self-contained platform at once. If you're using this to convert something that isn't self-contained, you are further into the abyss than I ever ventured, and I am certain it will end terribly. Yog Sa'rath, stay away from me.

The disciples beseeched the architect: render thy celestial works in common clay, that we may raise them without knowledge of the heavens. It was heresy. The architect obliged. The temples stood.

— Necronomicon, Prayers That Should Never Have Been Answered (probably)

Documentation

For users

"I received a compose setup and want plug & play."

  • Operations — day-to-day: updating, data management, troubleshooting
  • Advanced — cohabiting with existing infrastructure, multiple projects, disabling Caddy

For maintainers

"I have a helmfile and need to provide a compose deployment."

  • Your project — installation, first run, adapting h2c for your own helmfile
  • Configuration — helmfile2compose.yaml deep dive: volumes, overrides, secrets, replacements
  • Known workarounds — sushi recipes for the tentacles that don't fit
  • h2c-manager — installing h2c and extensions via the package manager

For developers

  • Concepts — design philosophy, emulation boundary, K8s vs Compose differences
  • Architecture — converter pipeline, what gets converted, dispatch loop
  • Code quality — linter scores, complexity metrics, existential dread
  • Testing — regression suite, torture generator, performance tracking
  • Writing extensions — converters, providers, transforms, rewriters

Extension catalogue

Available providers, converters, transforms, rewriters

Troubleshooting

When the cursed lands fight back

Reference

How it works

The same Helm charts used for Kubernetes are rendered into standard K8s manifests, then converted to compose:

Helm charts (helmfile / helm / kustomize)
    ↓  helmfile template / helm template / kustomize build
K8s manifests (Deployments, Services, ConfigMaps, Secrets, Ingress...)
    ↓  helmfile2compose.py
compose.yml + Caddyfile + configmaps/ + secrets/

Despite the name, helmfile is not required — the core accepts any directory of K8s YAML files. Helmfile is just one way to produce them.

The ecosystem

What started as a single script became an ecosystem of three components:

  • h2c-core — the mad scribe. A single Python script (~1860 lines) that reads K8s manifests and writes compose. Handles Deployments, StatefulSets, DaemonSets, Jobs, Services, Ingress, ConfigMaps, Secrets, PVCs, init containers, sidecars, and more things than anyone asked for.
  • Extensions — the damned. External modules that teach h2c new tricks. Four types: providers (CRD converters that produce compose services), converters (CRD converters that produce synthetic resources), transforms (post-processing hooks that reshape the final output), and ingress rewriters (translate controller-specific annotations to Caddy rules). Each extension is a single .py file. For the glory of Yog Sa'rath.
  • h2c-manager — the dark priest. Downloads h2c-core and extensions from GitHub releases, resolves dependencies, and provides a run shortcut. Reads helmfile2compose.yaml for declarative dependency management. Stdlib only, no dependencies.

Repositories

Repo Description
h2c-core Core converter script (helmfile2compose.py)
h2c-manager Package manager + extension registry
helmfile2compose.github.io This documentation site
h2c-testsuite Regression & performance test suite

Extensions (providers, converters, transforms, rewriters) are listed in the extension catalogue.

Compatible projects

  • stoatchat-platform — 15 services. Chat platform (Revolt rebranded).
  • lasuite-platform — 22 services + 11 init jobs. Collaborative suite (La Suite Num.).
  • mijn-bureau-infra — ~30 services. Dutch government digital workplace. Not tested extensively, but it starts and the apps respond. Requires nginx and bitnami extensions.
  • A proprietary, real production-grade helmfile — Why do you think there are CRDs extension that aren't used in any public repo?

License

Public domain.

Looking for the full record of what was done, and in what order? The cursed journal remembers.

Looking for why this exists, and why the documentation is complete? The about page has opinions.