Limitations¶
You replaced the perfectly sane orchestra conductor with a horribly mutated chimpanzee and you wonder why the audience needs earplugs.
This page covers what you lost when you chose compose over Kubernetes, scoped to what matters when running the tool day-to-day. For the exhaustive technical breakdown — including what's ignored, what's silently dropped, and the full existential crisis — see Limitations on docs.dekube.io.
Key limitations¶
Network aliases (nerdctl)¶
nerdctl compose silently ignores network aliases. Without the flatten-internal-urls transform, services will fail to reach each other by K8s FQDN. Install the transform or switch to Docker Compose / Podman Compose.
Startup ordering¶
Init containers become separate services with restart: on-failure, and the main service uses depends_on with condition: service_completed_successfully — so Docker Compose starts the main container only after its init containers complete. nerdctl ignores depends_on, so on nerdctl everything starts concurrently and converges via retries. Expect noisy logs on first boot with nerdctl.
Native sidecars (initContainers with restartPolicy: Always, K8s ≥ 1.28) are the exception — they run alongside the main container instead of blocking it, so they become their own service with depends_on pointing the other way. Known limit: a one-shot init container can't reach a native sidecar, since the sidecar joins the main container's network namespace only once the main container starts.
Secrets¶
Kubernetes Secrets are dumped as plain-text environment variables into compose.yml. The security model you carefully built is now a flat file on your laptop. Do not commit it to version control.
CRDs¶
Operator-managed resources are skipped unless a loaded extension handles them. "Skipped" means the resources they would have produced are missing — your cert-manager Certificate becomes a warning line, not a PEM file. See the extension catalogue for available converters (cert-manager, Keycloak, trust-manager, ServiceMonitor).
CronJobs¶
Not converted. No compose equivalent. People use host crontab entries, sleep-loop containers, or quiet denial. None of these are endorsed.
Long service names¶
Linux hostnames are limited to 63 characters. Compose uses the service name as the container hostname, and Helm-generated names can easily exceed that limit. dekube automatically sets a truncated hostname: on affected services to avoid sethostname: invalid argument failures. The compose service name itself is unchanged — only the container hostname is shortened. Sidecars, which share the main container's network namespace and hostname, get no hostname: — Docker refuses one there.
Bind mount permissions¶
Linux file permissions — the last thing you expect to fight after converting an entire orchestrator. Handled automatically by the bundled fix-permissions transform — non-root containers (runAsUser) and pods with an fsGroup get a chown/chgrp init service that runs before them, for bind mounts and named volumes alike. No manual intervention needed in most cases.
Volume types¶
PVC, ConfigMap, Secret and emptyDir volumes convert. hostPath, projected, downwardAPI, csi and the rest are dropped with a warning — add the mount yourself in overrides:.
For the full list, rationale, and workarounds: docs.dekube.io/limitations.