From Docker Compose to Kubernetes: A Simple Migration Pat...
Sealos·2025-09-02·via Sealos Blog
Modern applications seldom stay small. What starts as a handful of containers running happily in Docker Compose often grows into a distributed system that demands better scalability, resilience, and governance. That’s the point where Kubernetes shines—and also where many teams hesitate, worried that the migration will be complex, disruptive, or time-consuming.
Good news: it doesn’t need to be. In this article, you’ll learn a practical, low-friction path from Docker Compose to Kubernetes using Sealos—a cloud operating system built on Kubernetes that makes cluster creation and operations dramatically simpler. We’ll cover what each piece is, why this migration matters, how the conversion works in practice (with real code), and how to deploy and operate your workloads on Sealos.
By the end, you’ll be able to:
Stand up a production-grade Kubernetes cluster quickly with Sealos.
Convert Docker Compose to Kubernetes manifests using familiar tools.
Apply best practices for secrets, storage, networking, and health checks.
Deploy, observe, and scale your migrated workloads with confidence.
Docker Compose in 30 Seconds
Docker Compose is a developer-friendly tool for defining and running multi-container applications with a single YAML file. It’s perfect for local development and simple deployments because it hides a lot of complexity. But as your system grows, Compose becomes harder to scale, secure, and manage across environments.
Kubernetes: The Standard for Orchestrating Containers
Kubernetes is a container orchestration platform that handles scheduling, networking, storage, health checks, rollouts, and autoscaling. It’s more complex than Compose because it solves a larger problem: running containerized apps reliably at scale in production.
Key benefits:
Self-healing deployments and rolling updates
Service discovery and load balancing
Persistent storage orchestration
Resource quotas, security policies, and multi-tenancy
Horizontal autoscaling
Sealos: Kubernetes Made Simple
Sealos is a cloud operating system that simplifies the lifecycle of Kubernetes:
Create a cluster with a single command (or use the Sealos Cloud).
Package cluster components as container images for reproducible installs.
Operate with standard Kubernetes tools like kubectl and Helm.
Sealos does not reinvent Kubernetes. Instead, it makes Kubernetes accessible by streamlining installation and management, so you can focus on your workloads rather than cluster plumbing.
Scalability and Resilience: Kubernetes reschedules failed containers, handles rolling updates, and scales workloads.
Environment Parity: Reuse the same manifests across dev, staging, and production with minimal drift.
Security and Control: Namespaces, network policies, secrets management, admission control, and RBAC.
Day-2 Operations: Metrics, logs, tracing, and autoscaling are first-class citizens.
Simpler Cluster Ops: Sealos removes much of the friction in setting up and maintaining Kubernetes.
In short, Kubernetes future-proofs your deployments, and Sealos reduces the operational load to get you there.
Migrating isn’t just running a converter on your compose file and calling it a day. Plan for these steps to ensure success:
Inventory Your Services
List all services, images, environment variables, volumes, and ports.
Stateful (databases, queues) → StatefulSets with PersistentVolumeClaims (PVCs).
Externalize Secrets
Move passwords, tokens, and keys into Kubernetes Secrets.
Replace Volumes
Map Compose volumes to StorageClasses and PVCs.
Decide on a storage backend (local-path, hostPath for dev, or cloud CSI/OpenEBS/Longhorn for prod).
Networking and Ingress
Replace Compose ports with Services and Ingress.
Plan TLS and DNS.
Health Checks and Resources
Map Compose healthchecks to Kubernetes readiness/liveness/startup probes.
Add resource requests/limits for better scheduling and autoscaling.
Dev-to-Prod Promotion
Use Kustomize or Helm to parameterize environments.
You can use Sealos to spin up a Kubernetes cluster on VMs or bare metal quickly. Once you have the Sealos CLI installed, creating a single-node development cluster is often as simple as:
Notes:
Replace the Kubernetes version tag with the release you need.
For multi-node clusters, Sealos can join masters and workers via flags or inventory files. Consult the Sealos docs for production-ready topologies, HA control planes, and advanced networking.
Sealos works with standard Kubernetes tooling, so all kubectl and Helm workflows apply.
Install an ingress controller (for HTTP/HTTPS routing), and a default storage class (for PVCs) if your environment doesn’t provide them:
With Sealos handling cluster creation and the basic add-ons in place, you’re ready to migrate your applications.
Let’s start with a representative docker-compose.yaml for a simple web API with Redis and PostgreSQL:
Key concerns we’ll address:
Secrets: Move POSTGRES_PASSWORD to a Kubernetes Secret.
Volumes: Use PVCs for postgres data.
Health checks: Convert to readiness/liveness probes.
Networking: Replace host port mappings with Services and Ingress.
Dependencies: Compose’s depends_on is not a startup gate; we’ll use probes and retries.
Kompose is a tool that translates Docker Compose files into Kubernetes manifests. It won’t produce perfect production manifests, but it’s a great starting point.
Install Kompose:
Convert:
You’ll get several YAML files under k8s/, typically including Deployments, Services, and PVCs. Review the output for api, redis, and postgres resources.
To keep things maintainable, we’ll use Kustomize to layer improvements on top of the generated manifests without editing them directly.
Create a structure like this:
Base kustomization.yaml
We’ll patch in secrets, probes, and other improvements in the overlay.
Create a Secret for sensitive values and a ConfigMap for non-sensitive config:
Patch the api Deployment to reference them:
Also add resource requests/limits (helps scheduling, stability, and autoscaling):
Patch postgres Deployment into a StatefulSet with a PVC:
Note: We’re replacing the kompose-generated postgres Deployment and PVC with a StatefulSet and a volumeClaimTemplate for better data consistency. Ensure you remove or override the original postgres Deployment in the overlay so only the StatefulSet is applied.
If you need Ingress to reach the API, add it:
Finally, wire the overlay together:
Apply to your Sealos-managed cluster:
If you’re not using DNS, you can test the API by port-forwarding:
For Redis, the kompose-generated Deployment is adequate for dev/test. For production, consider:
Redis as a StatefulSet with a PVC for persistence.
Using a well-maintained Helm chart (bitnami/redis) for built-in replication, metrics, and password support.
Example Redis resource patch for a simple persistent standalone:
Kompose can generate a Helm chart:
Helm can be a better fit if you want:
Parameterized values for different environments.
A packaging format for distribution.
Built-in rollback and release history.
Sealos plays nicely with Helm—use whichever packaging strategy suits your team.
Kubernetes gives you powerful primitives for operations. With Sealos providing the cluster, you can layer standard tools:
Observability Stack
Logs: Use kubectl logs for ad-hoc, then deploy EFK/ELK or Loki for centralized logging.
Metrics: Install the Prometheus Operator (kube-prometheus-stack) via Helm for cluster and application metrics.
Tracing: Deploy OpenTelemetry Collector to export traces from your services.
Example install:
Horizontal Pod Autoscaling (HPA)
Add resource requests and deploy an HPA for the API:
Apply:
Ensure the metrics server is running (often deployed by default in many clusters; if not, install it):
CSI snapshots: Use VolumeSnapshot resources to take point-in-time snapshots.
Application-level: pg_dump for PostgreSQL, Redis RDB/AOF persistence, and off-site backups.
For production, adopt a tested operator or backup toolchain (e.g., Velero for cluster resources and supported PVs).
Namespaces: Use namespaces for isolation across environments and teams.
Network Policies: Restrict pod-to-pod communication to only what’s necessary.
Secrets Management: Use Kubernetes Secrets, sealed-secrets, or an external KMS (e.g., HashiCorp Vault).
Pod Security: Use Pod Security Admission or Pod Security Policies (where applicable) and ensure containers run as non-root where possible.
Ingress and TLS: Terminate TLS at the ingress controller and manage certificates via cert-manager.
Install cert-manager:
Then create ClusterIssuer and annotate your Ingress for automatic certificates.
Your choice depends on environment:
Development: local-path-provisioner or hostPath volumes (simple, not HA).
Bare Metal Production: OpenEBS (LVM/Mayastor), Longhorn, or Ceph/Rook.
Cloud: Use your provider’s CSI driver (EBS, PD, Azure Disk).
Make sure:
A default StorageClass exists.
Stateful workloads use ReadWriteOnce volumes, unless your setup supports shared access (RWX).
I/O requirements and capacity are sized correctly.
Before declaring success, run through a checklist:
Pods become Ready consistently after a fresh deploy.
Readiness/liveness probes behave correctly under failure scenarios.
Databases persist data across restarts and node reboots.
Services are reachable via ClusterIP and Ingress/TLS is configured.
Resource limits prevent noisy neighbor issues.
HPA scales up under load test and scales down cleanly.
Logs and metrics are visible; alerts are configured for key SLOs.
Backups work and restores are tested.
RBAC roles are least-privilege for CI/CD and ops.
For each environment, automate:
Build and push images to a trusted registry.
Update image tags in Kustomize/Helm (e.g., via GitOps).
Run kubectl apply -k or helm upgrade as a pipeline stage.
Add gates for canary or blue-green releases when appropriate.
GitOps with Argo CD or Flux is a natural next step for reliability and auditability.
Pods Pending due to PVC: Ensure a default StorageClass exists and the provisioner is healthy.
CrashLoopBackOff: Inspect container logs and events (kubectl describe pod). Check secrets and env vars.
Ingress Not Routing: Confirm the ingress controller is running, the Ingress resource uses the correct class, and DNS resolves to the controller’s endpoint.
Image Pull Errors: Verify the registry is reachable and imagePullSecrets are set for private registries.
DNS Failures in Pods: Check CoreDNS status (kubectl -n kube-system get pods) and network policies.
Helpful commands:
Monolith → Microservices: Kubernetes lets you decompose the system incrementally. Start by migrating the whole Compose stack, then split services.
Stateful Workloads: Move dev databases first using StatefulSets, then consider managed databases or operators (e.g., Postgres Operator) for production.
Multi-tenant SaaS: Namespaces per tenant, resource quotas, and network policies keep tenants isolated with predictable performance.
Edge and On-Prem: Sealos simplifies standing up clusters outside cloud providers; use CSI drivers suited to your hardware.
As your usage grows:
Cluster Lifecycle: Create, upgrade, or tear down clusters predictably using Sealos “cluster images.”
Standard Tooling: Keep using kubectl, Helm, Kustomize, and your favorite operators—Sealos embraces the ecosystem.
Portability: Move clusters or workloads across environments with minimal friction.
The aim is to make Kubernetes feel as approachable as Docker Compose without sacrificing the power you need in production.
Moving from Docker Compose to Kubernetes doesn’t have to be a leap into the unknown. With a clear strategy, a conversion tool like Kompose, and a simplified cluster lifecycle via Sealos, you can migrate in a measured, confidence-building way.
Key takeaways:
Use Sealos to stand up a robust Kubernetes cluster quickly.
Convert Compose to Kubernetes manifests with Kompose, then refine with Kustomize or Helm.
Externalize secrets, map volumes to PVCs, add probes, and define resource requests/limits.
Install ingress and a storage class; adopt observability and autoscaling early.
Validate with health checks, backups, and load tests before promoting to production.
Start small: migrate a single Compose stack into your Sealos-managed cluster, iterate on best practices, and scale features as your needs grow. The Kubernetes ecosystem will meet you where you are—and with Sealos, getting there is far simpler than you might think.
