From Docker Compose to Kubernetes: What Actually Changes

If you're comfortable with docker compose up, you already understand more of Kubernetes than you think. Compose taught you to describe an application declaratively — services, their images, their config, how they talk to each other — instead of running containers by hand. Kubernetes is the same instinct, scaled out across a cluster, with more moving parts because it's solving a harder problem: keeping that application running when machines fail.

The good news is the mental model transfers. The honest news is that the operational surface grows, and it's worth knowing exactly what changes before you commit. Let me map the concepts you already know onto their Kubernetes equivalents, show the YAML side by side, and be straight about the parts that get harder.

First, the thing that doesn't change: your images

This trips people up, so let's clear it early. The Docker images you already build run on Kubernetes unmodified. Kubernetes doesn't use the Docker daemon to run them — most clusters use containerd or CRI-O — but every one of those runtimes runs standard OCI images. That's the whole point of the OCI standard: the image you built with docker build is the same artifact the cluster pulls and runs.

docker build -t registry.example.com/myapp:1.4.2 .

docker push registry.example.com/myapp:1.4.2

That image works identically whether docker run starts it or a Kubernetes node's containerd does. So the packaging is settled. What changes is everything around the container.

The concept map

Here's the translation table I'd keep next to you while you learn:

Let's walk the important rows.

service becomes a Deployment and a Service

In Compose, one service block means both "run this" and "let others reach it." Kubernetes splits that in two, on purpose:

• A Deployment manages your pods — how many replicas, which image, how to roll out a new version.


• A Service gives those pods a stable name and IP, because individual pods are disposable and their addresses change.

That split feels like extra ceremony at first. It pays off because it lets Kubernetes replace a dead pod without anything that talks to it needing to care — the Service name stays constant.

depends_on becomes probes and init containers

This is the conceptual jump that matters most. Compose's depends_on controls start order on one host. Kubernetes deliberately doesn't guarantee ordering across a cluster, because in a distributed system "started" and "ready" are different things, and any pod can restart at any time.

Instead of ordering, you declare readiness:

• A readiness probe tells the Service "don't send traffic to this pod until this check passes."


• A liveness probe tells the kubelet "if this check fails, restart the pod."


• An initContainer runs to completion before your app container starts — the right place for a migration or a wait-for-dependency loop.

So "start the DB before the API" becomes "the API's readiness probe fails until the DB answers." It's a healthier model — it survives restarts and reschedules — but it's a genuine shift in thinking.

.env becomes ConfigMap and Secret

Compose leans on .env files and inline environment:. Kubernetes separates config from the workload into two objects: ConfigMaps for non-sensitive values and Secrets for sensitive ones. You then inject them as env vars or mounted files.

One caveat I'll say plainly: a Kubernetes Secret is base64-encoded, not encrypted, by default. If someone can read the object, they can read the value. For anything that actually matters, enable encryption at rest and lock down RBAC, or use an external secrets manager. Treat "Secret" as "the place secrets go," not "the thing that protects them."

volumes become PVCs

A Compose volume mounts a path on the local host. In a cluster the workload can land on any node, so "the local disk" isn't a stable idea. Kubernetes splits storage into a PersistentVolume (the actual storage) and a PersistentVolumeClaim (your request for some). Your pod references the claim, and the cluster binds it to real storage — usually a cloud disk. For stateful things like databases you'll also meet StatefulSets, but that's a next step.

Side by side: a tiny app

Here's a minimal Compose file — a web app with a couple of settings.

services:

  web:

    image: registry.example.com/myapp:1.4.2

    ports:

      - "8080:8080"

    environment:

      LOG_LEVEL: info

    deploy:

      replicas: 2

And the equivalent minimal Kubernetes manifests — a Deployment plus a Service:

apiVersion: apps/v1

kind: Deployment

metadata:

  name: myapp

spec:

  replicas: 2

  selector:

    matchLabels:

      app: myapp

  template:

    metadata:

      labels:

        app: myapp

    spec:

      containers:

        - name: myapp

          image: registry.example.com/myapp:1.4.2

          ports:

            - containerPort: 8080

          env:

            - name: LOG_LEVEL

              value: info

          readinessProbe:

            httpGet:

              path: /healthz

              port: 8080

            initialDelaySeconds: 5

            periodSeconds: 10

---

apiVersion: v1

kind: Service

metadata:

  name: myapp

spec:

  selector:

    app: myapp

  ports:

    - port: 80

      targetPort: 8080

Notice what the extra YAML buys you. The selector/labels pairing is how the Service finds the Deployment's pods — that loose coupling is what lets pods come and go. The readiness probe is doing the job depends_on used to, but correctly, on every restart. And to reach this from the outside you'd add an Ingress in front of the Service — the rough equivalent of the reverse proxy you probably already run beside Compose.

One more thing worth adding early, even though I left it out above for clarity: resource requests and limits. Compose lets you ignore how much CPU and memory a container uses until something falls over. Kubernetes wants you to declare it — requests tell the scheduler how much to reserve so it can place the pod, and limits cap what it can consume so one noisy service can't starve its neighbors. Skipping them is the single most common reason a new cluster behaves unpredictably under load. Set modest values from the start and tune them once you've measured real usage; guessing high wastes capacity, guessing low gets your pods evicted or throttled.

The other habit that saves grief: apply with kubectl apply -f, then actually watch the rollout rather than assuming it worked.

kubectl apply -f myapp.yaml

kubectl rollout status deployment/myapp

kubectl get pods -l app=myapp

If a pod is stuck, kubectl describe pod and kubectl logs are your first two stops — the equivalent of reading docker compose logs, just with more places the failure can hide.

Be honest about the added surface

I won't pretend this is free. Moving from Compose to Kubernetes trades one file you fully understand for a set of objects and a platform you now operate. In practice you inherit:

• 
  More YAML, and more places to get it subtly wrong — a mismatched label selector fails silently by matching nothing.


• 
  Cluster networking — Services, DNS, Ingress, and network policies are a real subsystem to learn.


• 
  Storage that behaves differently — dynamic provisioning, access modes, and reclaim policies have sharp edges.


• 
  The control plane itself — even on managed Kubernetes, you own upgrades, RBAC, and resource quotas.

That's not a reason to avoid it. It's a reason to adopt it when your app has genuinely outgrown a single host — when you need self-healing, rolling deploys, and horizontal scaling badly enough to pay for the platform underneath them. If a well-run Compose host still covers your load and your uptime target, staying put is a legitimate engineering decision, not a failure of ambition.

When you do make the move, having reference manifests and setup patterns on hand saves a lot of trial and error — I keep the ones I reach for in the cover getting your images clean and small before they ever hit a cluster, which is where a smooth migration actually starts.

Wrapping up

Compose and Kubernetes are two points on the same line: describe your app declaratively and let the tool run it. Kubernetes just assumes the machine underneath will fail, so it splits your one tidy service into a Deployment, a Service, probes, ConfigMaps, and claims — each solving a real distributed-systems problem. Learn the map, expect the larger operational surface, and move when your reliability needs justify it.

If you're mid-migration, the habit that'll serve you best: translate one Compose service at a time, get its probes and config right, and prove it healthy before you move to the next. Slow and boring beats a big-bang cutover you have to debug at 3 a.m.