Docker Compose to Kubernetes Migration

Why Migrate from Docker Compose to Kubernetes?

Docker Compose is excellent for local development and small deployments, but as your application grows, you need features that Compose can't provide: auto-scaling, self-healing, rolling updates, and multi-node scheduling. Kubernetes delivers all of these, and the migration path is well-defined.

Kompose: Automated Conversion

Kompose is the official tool for converting Docker Compose files to Kubernetes manifests:

# Install Kompose
curl -L https://github.com/kubernetes/kompose/releases/download/v1.31.2/kompose-linux-amd64 -o kompose
chmod +x kompose && sudo mv kompose /usr/local/bin/

# Convert docker-compose.yml
kompose convert -f docker-compose.yml

This generates Deployment and Service YAML files for each service defined in your Compose file.

What Kompose Handles Well

• Service definitions → Deployments + Services
• Port mappings → Service port configurations
• Environment variables → ConfigMaps or inline env vars
• Named volumes → PersistentVolumeClaims
• Restart policies → Pod restart policies

What Requires Manual Refinement

• Health checks — Compose healthcheck translates to liveness probes, but you should add readiness probes manually
• Resource limits — Compose mem_limit converts, but CPU limits need tuning
• Secrets management — Move from .env files to Kubernetes Secrets
• Networking — Compose networks don't map directly; use Kubernetes Services for inter-service communication
• Init containers — Compose depends_on needs conversion to init containers for startup ordering

Step-by-Step Migration

1. Audit your docker-compose.yml — List all services, volumes, networks, and dependencies
2. Run Kompose convert — Generate initial Kubernetes manifests
3. Add health probes — Define liveness and readiness probes for each service
4. Configure resource requests/limits — Size based on actual usage from Docker stats
5. Externalize configuration — Move environment variables to ConfigMaps and secrets to Kubernetes Secrets
6. Set up persistent storage — Create StorageClasses and PVCs for stateful services
7. Configure Ingress — Replace Docker port mappings with Ingress resources
8. Test in a staging cluster — Validate all services communicate correctly
9. Set up CI/CD — Automate image builds and manifest deployments
10. Migrate production — Use a blue-green strategy for zero-downtime cutover

Example: Before and After

Docker Compose:

services:
  web:
    image: myapp:latest
    ports:
      - "8080:80"
    environment:
      - DB_HOST=postgres
    depends_on:
      - postgres
  postgres:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

Kubernetes equivalent:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: web
        image: myapp:latest
        ports:
        - containerPort: 80
        env:
        - name: DB_HOST
          value: postgres
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 256Mi
        livenessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 80
          initialDelaySeconds: 5

Eazy SaaS Tip: We recommend running your application in both Docker Compose (for development) and Kubernetes (for production) simultaneously. Use Skaffold or Tilt to maintain a smooth developer experience while deploying to K8s in CI/CD.