Docker Swarm has served many teams well: it is simple, quick to set up and good enough for a lot of platforms. But as the number of applications grows, as several teams share the same platform and as security requirements tighten, Kubernetes often becomes the logical choice. The migration itself, however, is anything but automatic. Here are the five mistakes we see most often in the field.
1. Translating Compose files line by line
Tools such as kompose convert a docker-compose.yml file into Kubernetes manifests. That is a good starting point, never the finish line. A Swarm service does not map exactly onto a Deployment: for each application you need to decide whether it is a Deployment, a StatefulSet (database, message queue) or a DaemonSet (an agent running on every node).
Swarm configs and secrets become ConfigMaps and Secrets, and each healthcheck becomes a probe. Use the migration to adopt a packaging tool such as Helm or Kustomize: you will then manage your environments (staging, production) without duplicating files.
2. Forgetting persistent storage
On Swarm, many platforms rely on local volumes or an NFS share mounted on every node. On Kubernetes, a container can be rescheduled onto any node at any time, and a local volume will rarely follow it. You need a real storage solution, exposed through a StorageClass (Longhorn, LINSTOR or your SAN storage array), and PersistentVolumeClaims for every application that writes data.
Before the cutover, test the restore of your data, not just the copy. A backup that has never been restored is only a hypothesis.
3. Neglecting networking and service exposure
The Swarm routing mesh publishes a port on every node without any particular configuration. Kubernetes separates the roles: a Service gives the application a stable address inside the cluster, and an Ingress controller (or the Gateway API) exposes it to the outside world, with TLS certificates ideally renewed automatically by cert-manager.
Watch the names, too: applications that called each other by their Swarm service name must use the DNS name of the Kubernetes Service, which depends on the namespace (api.production.svc.cluster.local). Finally, apply NetworkPolicies: by default, every pod can talk to every other pod.
4. Declaring neither resources nor probes
Without requests, the Kubernetes scheduler does not know where to place your pods and may overload a node. Without memory limits, a leaking application can hurt its neighbours; with limits set too low, it will be killed in a loop (OOMKilled). Start from the consumption you observed on Swarm, then adjust using Prometheus metrics.
Probes matter just as much. The readiness probe says when a pod can receive traffic, the liveness probe when it needs restarting. Badly tuned, they cause restarts while slow applications are still starting up: use a startup probe for those.
5. Switching everything over at once
It is tempting to migrate every application on a Friday evening. Prefer a migration in waves: first a low-criticality application, then the others, running both platforms in parallel during the transition.
- Lower the time to live (TTL) of your DNS records a few days beforehand, so you can switch over and back quickly.
- Write the rollback plan before the cutover, not during the incident.
- Set up observability (metrics, logs, alerts) before migrating, so you can compare behaviour.
Above all: prepare the team
A well-built Kubernetes platform that nobody knows how to operate remains fragile. The commands change (kubectl instead of docker service), and so does the way you troubleshoot. Plan the operations team's upskilling alongside the migration, not after it.
This is the approach we apply in our projects: design, deploy, secure, then transfer the skills to the teams who run the platform day to day.