Skip to content

helmfile2compose

For when you maintain a helmfile but people keep asking for a docker-compose. But 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.

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
  • Configuration — helmfile2compose.yaml deep dive: volumes, overrides, secrets, replacements
  • 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
  • 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
  • Writing operators — develop your own CRD converter
  • Code quality — linter scores, complexity metrics, existential dread

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 (~1500 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. Today, all extensions are CRD operators (Keycloak, cert-manager, trust-manager) — but the system is open to anything that fits the interface. 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-operator-keycloak Keycloak and KeycloakRealmImport CRDs
h2c-operator-certmanager Certificate, ClusterIssuer, Issuer CRDs
h2c-operator-trust-manager Bundle CRD (trust-manager)

Compatible projects

License

Public domain.