Moving from Docker Compose to Kubernetes involves translating familiar Compose concepts into Kubernetes-native resources — this guide covers the mapping and migration approach.
Why Consider This Migration
See K3s vs kubeadm vs Full Kubernetes: Which Should You Choose for a VPS? and What Is Kubernetes and When Do You Need It on a VPS? for whether migration genuinely makes sense for your situation — this guide assumes you've already decided Kubernetes is the right direction.
Conceptual Mapping: Compose to Kubernetes
| Docker Compose | Kubernetes Equivalent |
|---|---|
| service | Deployment + Service |
| volumes | PersistentVolumeClaim |
| environment | ConfigMap / Secret |
| networks | Handled natively by Kubernetes cluster networking |
| depends_on | No direct equivalent — use readiness probes and application-level retry logic |
Using Kompose for Automated Initial Translation
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/kompose convert -f docker-compose.ymlKompose generates initial Kubernetes manifests from your Compose file — a genuinely useful starting point, though the output typically needs review and refinement rather than being production-ready as-is.
Reviewing and Refining Generated Manifests
Kompose's automated conversion often needs manual adjustment for: proper resource requests/limits (see Kubernetes Resource Requests and Limits Explained), appropriate readiness/liveness probes (see How to Set Up Liveness and Readiness Probes in Kubernetes), and genuinely production-appropriate replica counts and update strategies.
Handling depends_on's Absence in Kubernetes
Compose's depends_on ensures startup ordering; Kubernetes has no direct equivalent — instead, design your application to handle dependency unavailability gracefully (retry logic, readiness probes checking actual dependency availability) rather than relying on guaranteed startup order.
Converting Volumes to PersistentVolumeClaims
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: db-data
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 10GiSee How to Manage Persistent Storage in Kubernetes (PersistentVolumes & PVCs) — Compose volumes map to PVCs, but require explicit sizing and storage class considerations that Compose's simpler volume model doesn't need.
Converting Environment Variables
apiVersion: v1
kind: ConfigMap
metadata:
name: myapp-config
data:
API_URL: "https://api.example.com"See Kubernetes ConfigMaps and Secrets: Managing Configuration Safely — distinguish between genuinely sensitive values (use Secrets) and regular configuration (ConfigMaps), a distinction Compose's flat environment variable list doesn't naturally enforce.
Testing Thoroughly Before Cutting Over
Deploy the converted manifests to a staging/test cluster first, verifying genuinely equivalent behavior before migrating production traffic — automated conversion tools are a starting point, not a guarantee of correctness.
Planning the Actual Cutover
Consider a gradual migration approach (see Canary Deployments: Gradually Rolling Out Changes for the underlying pattern, applied at the platform-migration level) rather than an abrupt full cutover, particularly for genuinely critical production workloads.
Common Errors
Application works differently under Kubernetes despite seemingly equivalent configuration — check for implicit assumptions in your application about Compose's networking model (service discovery via container name) that may need adjustment for Kubernetes' DNS-based service discovery instead.
Continue Reading
- What Is Kubernetes and When Do You Need It on a VPS?
- Kubernetes Pods, Deployments & Services Explained
- How to Manage Persistent Storage in Kubernetes (PersistentVolumes & PVCs)
Browse more articles in Kubernetes & Container Orchestration.
