helmfile2compose

The full distribution. Patient zero, fully armed.

This is where it started — a single Python script, born from the unholy request to make Kubernetes run without Kubernetes. It worked. That was the worst possible outcome. From this aberration, an entire ecosystem grew: a package manager, CRD extensions, documentation — a temple built for the sole purpose of dismantling a greater and more beautiful one.

Core of the problem: feed it Kubernetes manifests (from helmfile template, helm template, kustomize build, whatever produced them) and it will spit out a compose.yml + whatever configfile your proxy server will use. Not Kubernetes-in-Docker — no cluster, no kubelet, no shim. Plain docker compose up.

Quick start

Download helmfile2compose.py from the latest release.

# Convert from helmfile
python3 helmfile2compose.py --helmfile-dir ~/my-platform -e compose --output-dir .

# Or from any K8s manifests
python3 helmfile2compose.py --from-dir /tmp/rendered --output-dir .

docker compose up -d

If your stack uses CRDs (Keycloak, cert-manager, trust-manager), grab the extension .py files from their repos, drop them in a directory, and pass --extensions-dir to the script. For managing extensions and automating downloads, see dekube-manager.

Requirements

• Python 3.10+
• pyyaml
• helmfile + helm (only if rendering from helmfile directly)

What it converts

K8s kind	Compose equivalent
Deployment / StatefulSet / DaemonSet	services: (image, env, command, volumes, ports)
Job	services: with restart: on-failure
ConfigMap / Secret	Inline environment: + generated files for volume mounts
Service	Hostname/alias/port rewriting
Ingress	Caddy reverse_proxy (auto-TLS, path routing, backend SSL)
PVC / volumeClaimTemplates	Host-path bind mounts

Init containers, sidecars, fix-permissions services, and hostname truncation are handled automatically.

CRDs (Keycloak, cert-manager, trust-manager) are handled by external extensions via --extensions-dir.

Output files

• compose.yml — services, volumes
• Caddyfile — reverse proxy config from Ingress manifests
• dekube.yaml — persistent config (volumes, excludes, overrides)
• configmaps/ / secrets/ — generated files from volume mounts

Development

This repo contains built-in extensions under extensions/. The core engine lives in dekube-engine (src/dekube/). The single-file helmfile2compose.py is a build artifact — dekube-engine + extensions concatenated by build-distribution.py.

# Build locally (reads core sources from sibling checkout)
python ../dekube-engine/build-distribution.py helmfile2compose \
  --extensions-dir extensions --core-dir ../dekube-engine
# → helmfile2compose.py

# Test it
python helmfile2compose.py --from-dir /tmp/rendered --output-dir .

See the distributions docs and core architecture for the full picture.

Documentation

Full docs at docs.dekube.io.

Related repos

Repo	Description
dekube-engine	Bare conversion engine (dekube.py)
dekube-manager	Package manager + extension registry
dekube-docs	Documentation site

License

Public domain.