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
- Deploy to the cluster alongside the existing Compose setup.
- Point a test subdomain at the cluster and run your test suite against it.
- Lower the DNS TTL, then switch the main domain.
- 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
latesttag, 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.