Docker & Kubernetes

Docker to Kubernetes Migration: A Step-by-Step Guide for Small Teams

Home Blog Docker & Kubernetes

Docker & Kubernetes

In an earlier post we covered how to decide whether you need Kubernetes at all. If the answer is yes, this is the migration plan we use with small teams. It's gradual, reversible and doesn't need a dedicated platform team.

Step 0: Get the app "cluster-ready"

Most migration pain comes from the application, not from Kubernetes. Before writing any YAML, check that:

  • Configuration comes from environment variables, not files baked into the image.
  • Containers are stateless. User uploads go to object storage (S3 or compatible) and sessions go to Redis or the database.
  • Logs go to stdout/stderr, not to files inside the container.
  • There is a health endpoint that returns 200 only when the app can actually serve traffic.
  • Database migrations run as a separate step, not automatically on every container start.

Step 1: Choose where the cluster runs

For small teams we almost always recommend a managed Kubernetes service (EKS, GKE, AKS, DigitalOcean, Linode or similar). Running your own control plane is a full-time job. Keep the database outside the cluster on a managed service as well. Stateful workloads are where Kubernetes is hardest.

Step 2: Translate services into manifests

Each Compose service usually becomes a Deployment plus a Service:

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: registry.example.com/app:1.5.0
          ports: [{ containerPort: 8000 }]
          envFrom:
            - configMapRef: { name: web-config }
            - secretRef: { name: web-secrets }
          readinessProbe:
            httpGet: { path: /healthz, port: 8000 }
          resources:
            requests: { cpu: 100m, memory: 256Mi }
            limits: { memory: 512Mi }

Always set readiness probes and resource requests. Without them, rolling updates and scheduling become unpredictable.

Step 3: Move secrets and config out of .env files

Non-sensitive settings go into a ConfigMap, credentials into a Secret. Plain Kubernetes Secrets are only base64-encoded, so for production consider Sealed Secrets, External Secrets Operator or your cloud's secret manager. Never commit raw secrets to Git.

Step 4: Expose the app with an Ingress

An Ingress controller (NGINX Ingress or your cloud's load balancer controller) routes public traffic to your Services. Add cert-manager to issue and renew TLS certificates automatically.

Step 5: Run migrations as a Job

Run python manage.py migrate (or your framework's equivalent) as a Kubernetes Job before rolling out new pods. That way two replicas never try to migrate at the same time.

Step 6: Package it

Once the raw manifests work, package them with Helm or Kustomize so staging and production share the same templates with different values. Keep them in their own Git repository. This is the basis for GitOps later.

Step 7: Cut over gradually

  1. Deploy to the cluster alongside the existing Compose setup.
  2. Point a test subdomain at the cluster and run your test suite against it.
  3. Lower the DNS TTL, then switch the main domain.
  4. Keep the old server running for a few days as an instant rollback option.

Common mistakes

  • Running the database inside the cluster on day one.
  • No resource limits, so one memory leak takes down a node.
  • Using the latest tag, which makes rollbacks impossible to reason about.
  • No monitoring. You need at least basic metrics and alerts before cutover.

Want a second pair of eyes on your migration plan? Our DevOps team has moved apps of all sizes onto Kubernetes.