Skip to content

Docker Compose vs Kubernetes YAML: key differences

Compose describes processes on a Docker host. Kubernetes YAML describes API objects. A converter can copy an image name and a port. It cannot turn a bind mount into a well-designed PersistentVolumeClaim without you.

Two models, one word: service

In Compose, a service is a long-running container with a name on a project network. In Kubernetes, a Service is a stable address in front of Pods. The Pods themselves usually come from a Deployment (or a StatefulSet, DaemonSet, Job). When people say “convert Docker Compose to Kubernetes YAML,” they usually want each Compose service to become a Deployment plus, if ports are published, a Service. That is what the Docker Compose to Kubernetes YAML page writes.

services:
  web:
    image: nginx:1.25
    ports:
      - "8080:80"

The Deployment runs nginx:1.25 with containerPort: 80. The Service listens on 8080 and selects those Pods. The Compose project name, the default network, and the Docker-internal DNS name web are not Kubernetes objects. Other Pods reach this one through the Service name you apply, which this converter keeps as the Compose service name when that name is a valid DNS-1123 label.

Images versus build

Compose is happy with build: ./web and no image. Kubernetes is not a builder. The cluster pulls an image. ConfigKit requires image and lists build as unsupported. A CI job should build and push, then the manifest should name the tag. Inventing a Dockerfile-to-image step inside a YAML converter would be fiction.

Restart, replicas, and command

Compose restart: unless-stopped means “stay up unless I docker stop you.” A Deployment’s restartPolicy is Always. Other values belong on Jobs. The converter maps unless-stopped and always to Always, and says so. deploy.replicas becomes spec.replicas. Compose command and entrypoint become container args and command. If you set only command, the image ENTRYPOINT still applies in Docker; Kubernetes args without command does the same with the image’s entrypoint. The converter does not inspect the image, so it cannot warn about a mismatch it cannot see.

Ports, volumes, and networks

Compose "8080:80" publishes host port 8080. Kubernetes Services do not bind a host IP in that way unless you choose NodePort or hostPort, which this mapping does not. You get a ClusterIP Service. That is the usual in-cluster shape. Host-mode publishes and host IPs are listed and omitted.

Named volumes, bind mounts, networks, depends_on, env_file, healthcheck, secrets, and configs are not turned into PVCs, NetworkPolicies, or init containers. Those objects need sizes, storage classes, and probes you have not written in Compose. A tool that emitted an empty PVC would be guessing. ConfigKit lists the keys and leaves them out. Invalid YAML, a missing image, or a service name that is not a Kubernetes name is an error and the output stays empty.

Environment and labels

Compose environment becomes container env. Values are strings. Host passthrough without a value is rejected: the cluster will not read your laptop’s environment. Labels that are valid Kubernetes labels can be copied onto the Deployment; Compose labels that break the Kubernetes label syntax are not rewritten into something that applies.

compose.yaml and the version key

Compose V2 reads compose.yaml, compose.yml, docker-compose.yaml, and docker-compose.yml. The old top-level version: "3.8" is ignored by current Compose. Kubernetes has no equivalent of that key. ConfigKit looks at services. A Compose file that is only version and networks will fail because there is nothing to map. Adocker run command is not a Compose file either.

What to do with the output

Read the notices. Add probes, resources, and a real Service type if you need to reach the process from outside the cluster. Run the Kubernetes YAML syntax check on the result: it parses each document and does not validate apiVersion or required fields. Apply in a namespace you control. This mapping is a start for web and worker services with an image, not a replacement for Helm charts or for reading the Kubernetes API docs.

FAQ

Can I convert Docker Compose to Kubernetes YAML without Kompose?
Yes. ConfigKit maps services with an image onto Deployments and Services in the browser. It is not Kompose, and it does not call a cluster.
Why is there no Service for my worker?
A Service is written when the Compose service publishes ports. A worker with only an image and a command becomes a Deployment.
Does Compose restart: unless-stopped become Always?
On a Deployment, yes. Kubernetes Deployments only allow Always as restartPolicy. The converter records that change instead of pretending unless-stopped exists.

Related: Docker Compose to Kubernetes YAML, Kubernetes Secret base64 decode online, error converting YAML to JSON.