Migrating Docker Compose to Kubernetes: Complete Architectural Guide

Docker Compose is the gold standard for developer ergonomics. With a single command (`docker compose up`), engineers can spin up a complete application stack—including frontend web apps, API microservices, background workers, and relational databases. However, taking that local stack to production Kubernetes (such as AWS EKS, Google GKE, Azure AKS, or lightweight K3s) introduces a fundamental paradigm shift: - **Host-Bound vs Node-Agnostic:** Compose operates under the assumption of a single Docker daemon running on a single physical host or virtual machine. Kubernetes operates across an elastic pool of worker nodes where pods can be rescheduled, terminated, or scaled at any moment. - **Declarative Reconciliation:** While Compose acts as a CLI orchestrator, Kubernetes continuously enforces a desired state loop. If a pod crashes or a worker node suffers hardware failure, Kubernetes controllers automatically reschedule replacements. - **Decoupled Architecture:** In Compose, configurations, container commands, and storage directories are tightly coupled in one YAML file. In Kubernetes, best practices require decoupling configurations into `ConfigMap`, credentials into `Secret`, stateful data into `PersistentVolumeClaim`, and ingress routing into `Ingress` or Gateway API objects.

Understanding how Compose keywords translate into native Kubernetes manifests is essential for building clean, maintainable deployment pipelines: | Docker Compose Primitive | Kubernetes Manifest Equivalent | Key Consideration | | :--- | :--- | :--- | | `services.<name>` (Stateless) | `apps/v1` Deployment | Sets desired replica counts and rolling update strategies. | | `services.<name>` (Stateful/DB) | `apps/v1` StatefulSet | Guarantees ordered pod startup and persistent network identifiers. | | `ports: ["8080:80"]` | `v1` Service (`ClusterIP` / `LoadBalancer`) | Maps internal cluster ports or cloud load balancers to container ports. | | `environment: [KEY=val]` | `v1` ConfigMap | Stores non-sensitive application environment variables. | | Passwords, Tokens, API Keys | `v1` Secret (`type: Opaque`) | Uses `stringData` or base64 to isolate confidential credentials. | | `volumes: [db-data:/var/lib]` | `v1` PersistentVolumeClaim (PVC) | Requests persistent cloud block storage (e.g. AWS gp3, GCE-PD). | | `healthcheck` | `livenessProbe` & `readinessProbe` | Periodically inspects HTTP endpoints or commands to detect deadlocks. | | `deploy.resources.limits` | `resources.limits` & `requests` | Enforces CPU/Memory boundaries to prevent node out-of-memory crashes. |

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-api
  namespace: production
  labels:
    app: web-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-api
  template:
    metadata:
      labels:
        app: web-api
    spec:
      containers:
        - name: web-api
          image: ghcr.io/myorg/api:v1.4.2
          ports:
            - containerPort: 8080
              name: http-8080
          envFrom:
            - configMapRef:
                name: web-api-config
            - secretRef:
                name: web-api-secret
          resources:
            limits:
              cpu: "1.0"
              memory: 1024Mi
            requests:
              cpu: "250m"
              memory: 256Mi

Two of the most common pitfalls during migration involve credentials and file paths: 1. **Automated Secret Separation:** Committing database passwords or API keys directly to Git in plain YAML is a severe security vulnerability. When converting Compose stacks, extract all sensitive environment variables into discrete Kubernetes Secret resources that can be managed via SealedSecrets, HashiCorp Vault, or AWS Secrets Manager. 2. **Eliminating Host Bind Mounts:** In local development, developers routinely mount source code or configs via `./config:/app/config`. In a multi-node Kubernetes cluster, worker nodes cannot access your local workstation directory. Configuration files should instead be populated into a ConfigMap and mounted as read-only volumes, while scratch files should utilize `emptyDir` volumes.