Migrating from Docker Compose to Kubernetes: Complete Translation Guide

Docker Compose is the gold standard for defining and running multi-container applications in local development. However, as applications scale to production environments demanding auto-scaling, high availability, zero-downtime rolling deployments, and self-healing resilience, migrating workloads to Kubernetes (K8s) becomes essential.

Moving from a single-node daemon like Docker to a distributed container orchestrator involves translating imperative host assumptions into declarative Kubernetes primitives.

This guide provides a comprehensive mapping model, explains how to avoid common architectural gotchas, and walks through automated migration workflows.

---

1. Architectural Concept Mapping

Docker Compose bundles compute, networking, and storage into single service blocks. Kubernetes decouples these concerns into specialized API objects.

Docker Compose Concept	Kubernetes Equivalent	Responsibility / Purpose
services.<name>	Deployment + Pod	Manages replica lifecycle, container specifications, and rolling update strategies.
ports: ["8080:80"]	Service (ClusterIP / NodePort / LoadBalancer)	Provides stable internal DNS resolution and load balancing across dynamic pods.
environment / env_file	ConfigMap and Secret	Injects configuration key-values and encrypted credentials into container runtimes.
volumes: ["./data:/var/lib/db"]	PersistentVolumeClaim (PVC) + StorageClass	Decouples physical disk storage from pod lifecycles across cluster nodes.
networks	NetworkPolicy + Cluster CNI (Calico/Cilium)	Controls inter-pod communication and ingress/egress network security.
restart: always	restartPolicy: Always (Pod Spec)	Dictates container recovery behavior on crash or process termination.

---

2. Step-by-Step Translation Example

Consider a typical web application stack composed of a Node.js API and a Redis cache:

Original docker-compose.yml

version: '3.8'
services:
  api:
    image: myorg/api-service:v1.4.0
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - REDIS_HOST=cache
      - API_SECRET=supersecret123
    depends_on:
      - cache
    restart: always

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

---

Translated Kubernetes Manifests

1. ConfigMap & Secret (api-config.yaml)

apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
data:
  NODE_ENV: "production"
  REDIS_HOST: "cache-service"
---
apiVersion: v1
kind: Secret
metadata:
  name: api-secret
type: Opaque
stringData:
  API_SECRET: "supersecret123"

2. API Deployment & Service (api-deployment.yaml)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
  labels:
    app: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: myorg/api-service:v1.4.0
          ports:
            - containerPort: 3000
          envFrom:
            - configMapRef:
                name: api-config
            - secretRef:
                name: api-secret
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "1000m"
              memory: "512Mi"
          readinessProbe:
            httpGet:
              path: /healthz
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: api-service
spec:
  type: ClusterIP
  selector:
    app: api
  ports:
    - port: 3000
      targetPort: 3000

3. Redis Storage & Deployment (cache-deployment.yaml)

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: redis-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cache-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cache
  template:
    metadata:
      labels:
        app: cache
    spec:
      containers:
        - name: redis
          image: redis:7-alpine
          ports:
            - containerPort: 6379
          volumeMounts:
            - name: redis-storage
              mountPath: /data
      volumes:
        - name: redis-storage
          persistentVolumeClaim:
            claimName: redis-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: cache-service
spec:
  type: ClusterIP
  selector:
    app: cache
  ports:
    - port: 6379
      targetPort: 6379

Convert your multi-container Compose setups directly into Kubernetes YAML manifests with the DevFlow Docker Compose to K8s Converter.

---

3. Critical Migration Traps & Production Checklist

1. Host Mounts vs Persistent Volume Claims (PVC)

• In Docker Compose, bind mounts like ./src:/app or /var/data:/data map directly to the host filesystem.
• In Kubernetes, pods can be scheduled across any node in the cluster. Binding to local node paths (hostPath) breaks workload portability. Always declare a PersistentVolumeClaim backed by a managed storage driver (AWS EBS CSI, GCP Persistent Disk, or Ceph).

2. Service Discovery and Hostnames

• In Docker Compose, services communicate using service names directly (e.g., http://cache:6379).
• In Kubernetes CoreDNS, services resolve across namespaces via <service-name>.<namespace>.svc.cluster.local. Update internal configuration strings to point to the created Service names.

3. Missing Resource Requests & Limits

• Compose setups often run without CPU/memory constraints on developer laptops.
• In Kubernetes, omitting resources.requests and resources.limits leads to node memory exhaustion and unpredictable OOM-kills. Always define explicit constraints.

Validate your generated manifests against schema best practices using our companion Kubernetes YAML Validator and Kubernetes Common Mistakes Guide.

---

Frequently Asked Questions

What tool automates Docker Compose to Kubernetes conversion?

You can use the browser-based DevFlow Docker Compose to K8s Tool for instant conversion or the open-source CLI kompose (kompose convert -f docker-compose.yml).

How do I handle ingress routing for external traffic?

In Docker Compose, exposing 80:80 maps ports directly to your host IP. In Kubernetes, you deploy an Ingress Controller (like NGINX Ingress or Traefik) and define an Ingress or HTTPRoute resource to route external hostnames and TLS certificates to your backend Service.

Can I run Docker Compose in production instead of Kubernetes?

For small, single-server applications, Docker Compose or Docker Swarm is simple and effective. However, if you require automated horizontal pod autoscaling (HPA), rolling zero-downtime updates across multi-zone infrastructure, and managed cloud resilience, Kubernetes is the industry standard.