Skip to content

Getting started with kubernetes2simple

kubernetes2simple (k2s) turns a directory of Kubernetes YAML, a Helm chart, or a helmfile into a working compose.yml — plus a Caddyfile for reverse proxying and a dekube.yaml for customization. One command, no cluster.

For the record: if you can run Kubernetes, it's probably simpler to. On Linux, k3s is one script. On macOS or Windows, Docker Desktop has an "Enable Kubernetes" checkbox. Your manifests work as-is.

But you're here, so one of these is true:

  • You don't want to learn Kubernetes. You want to add an app to your NAS or VPS the same way you added Plex or Immich — paste a compose file, done. I'm not saying I agree, but this is the reason this project exists.
  • You can't be root. Corporate policy says Podman rootless, no sudo, no systemd. k3s needs root. Compose is what you've got.
  • Your platform only speaks Compose. Your Synology, your TrueNAS, your hosting panel — it has a Compose field and nothing else.

Either way — read on.

Two commands

kubernetes2simple is a shell script. Point it at a directory containing Kubernetes YAML files, a Helm chart, or a helmfile, and it handles everything — detecting the project type, downloading any missing tools (helm, helmfile), and converting:

curl -fsSL k2s.dekube.io/get | bash
docker compose up -d

All downloaded tools go into .kubernetes2simple/. Your system stays clean. You get a compose.yml, a Caddyfile, and a dekube.yaml.

If your helmfile uses environments, pass one. On the first run, forward it through the installer — arguments after -- are passed straight to the script:

curl -fsSL k2s.dekube.io/get | bash -s -- --env dev

Once ./k2s.sh is on disk, re-run it directly:

./k2s.sh --env dev

Things to check after conversion

Hostnames — Your app's domain names end up in the Caddy reverse proxy config. Make sure they resolve locally (*.localhost works on most systems, or add /etc/hosts entries).

Secrets — If a secret value wasn't found during conversion, env vars that reference it are skipped (with a warning). Add missing values in dekube.yaml under overrides:, not in compose.yml.

Volume paths — Persistent storage becomes bind mounts under ./data/. Customize in dekube.yaml — the script reads it but never overwrites it.

Re-running

The script is safe to re-run. compose.yml and Caddyfile are regenerated. dekube.yaml is preserved — your volume paths, excludes, and overrides survive.

# After chart or manifest changes, just re-run
./k2s.sh --env dev
docker compose up -d

What the script fetches, and when

Everything lands in .kubernetes2simple/ next to your project. ./k2s.sh --clean wipes it and starts over.

  • The converter (kubernetes2simple.py) is cached. The script checks GitHub for a newer release at most once a day and downloads it only when the tag changed. If GitHub can't be reached (offline, rate-limited), it keeps the cached copy and says so. Only a first run, with nothing cached yet, has to reach GitHub for it.
  • helm and helmfile come from your PATH when they're installed. Otherwise the latest release is downloaded into .kubernetes2simple/bin/, and its SHA-256 is checked against the upstream checksum before it's unpacked. A mismatch aborts the run. Raw manifests need neither, a chart needs only helm.
  • Python dependencies (PyYAML, cryptography) come from the system Python when it has them, otherwise from a venv in .kubernetes2simple/venv/.

The project type is read from the directory: helmfile.yaml or helmfile.yml (with or without .gotmpl) means a helmfile, Chart.yaml a Helm chart, and a *.yaml file with a top-level kind: raw manifests. The converter only reads .yaml files. If your manifests are all .yml, the script warns you before converting, because the output will probably be empty. Rename them to .yaml.

Pick your guide

Want more control?

Want to understand what the script did with each part of your input? How the conversion works breaks it down step by step.

kubernetes2simple decides everything for you. If you need to pick which extensions to load, exclude services, or embed the conversion in CI, helmfile2compose is the distribution for people who want full control. For how providers, rewriters, and extensions fit together, see the full dekube documentation.