Migrate Applications from Docker Swarm to Kubernetes

Docker Swarm to Kubernetes migration concerns a growing number of organizations seeking to standardize their container orchestration. According to The Decipherist, 96% of organizations use or evaluate Kubernetes, while Docker Swarm represents only 24% of deployments. This trend is accelerating with AI adoption: 66% of organizations hosting generative AI models use Kubernetes for their inference workloads (CNCF Annual Survey 2025).

TL;DR: This guide details the key steps to migrate your Docker Swarm applications to Kubernetes: concept mapping, configuration conversion, progressive migration strategy, and validation.

To master these skills, discover the LFD459 Kubernetes for Application Developers training.

Why Consider Docker Swarm to Kubernetes Migration Now?

Docker Swarm offers appreciable simplicity: a single command docker swarm init is enough to initialize a cluster (Portainer Blog). However, several factors push teams toward Kubernetes.

Migration triggers:

Key takeaway: Migration to Kubernetes is not a question of "if" but "when". Plan it proactively rather than under constraint.

An enterprise CTO testifies in the Spectro Cloud State of Kubernetes 2025 report: "Just given the capabilities that exist with Kubernetes, and the company's desire to consume more AI tools, we will use Kubernetes more in future."

How to Map Docker Swarm Concepts to Kubernetes?

The first step of a successful Kubernetes container migration strategy is understanding the equivalences between the two systems.

Resource Correspondence Table

To deepen Kubernetes manifests, consult Kubernetes YAML Manifests: Quick Reference.

Fundamental Architectural Differences

Docker Swarm uses a simplified declarative model where the manager directly orchestrates workers. Kubernetes introduces several components: etcd for state storage, kube-scheduler for placement, kube-controller-manager for reconciliation.

# Docker Compose / Swarm
services:
web:
image: nginx:1.25
deploy:
replicas: 3
ports:
- "80:80"

# Kubernetes equivalent
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 3
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: web
spec:
selector:
app: web
ports:
- port: 80
targetPort: 80

Key takeaway: Kubernetes requires more initial configuration but offers granular control. Each Swarm concept often translates to multiple Kubernetes resources.

What Kubernetes Container Migration Strategy to Adopt?

Three main approaches exist for migrating from Docker Swarm to Kubernetes. The choice depends on application criticality and time constraints.

Progressive Migration (Recommended)

This approach minimizes risks by migrating application by application:

1. Inventory: List all Swarm stacks and their dependencies
2. Classification: Prioritize by criticality and complexity
3. Pilot: Migrate a non-critical application to validate the process
4. Iteration: Apply lessons learned to subsequent applications
5. Cutover: Progressively switch traffic

# Export Swarm configuration
docker stack services my-stack --format "{{.Name}}: {{.Image}}"
docker service inspect my-service --pretty

Parallel Migration

Running both environments simultaneously during a transition period:

• Advantage: Immediate rollback possible
• Disadvantage: Infrastructure cost temporarily doubled

Big Bang Migration

Migrate everything in a single planned operation:

• Advantage: Quick transition, no double maintenance
• Disadvantage: High risk, requires exhaustive preparation

The Kubernetes Cluster Administration hub details operational aspects of cluster management.

How to Convert Your docker-compose.yml Files?

Several tools partially automate the conversion of Docker Compose files to Kubernetes manifests.

Using Kompose

# Installation
curl -L https://github.com/kubernetes/kompose/releases/latest/download/kompose-linux-amd64 -o kompose
chmod +x kompose
sudo mv kompose /usr/local/bin/

# Conversion
kompose convert -f docker-compose.yml

# Conversion with resource creation
kompose convert -f docker-compose.yml | kubectl apply -f -

Kompose generates separate files for each resource. Expect manual adjustments, particularly for:

• Persistent volumes (PVC)
• Advanced network configurations
• Health checks (probes)
• Resource constraints (requests/limits)

Manual Secret Conversion

# Docker Swarm
docker secret create my-key ./my-key.pem

# Kubernetes
kubectl create secret generic my-key --from-file=./my-key.pem

For secure secret management, consult Kubernetes ConfigMaps and Secrets: Best Practices.

How Does a Kubernetes Infrastructure Engineer Validate the Migration?

Post-migration validation requires a methodical approach covering several dimensions.

Functional Tests

# Check deployment
kubectl get deployments
kubectl rollout status deployment/my-app

# Test endpoints
kubectl port-forward service/my-app 8080:80
curl localhost:8080/health

Load Tests

# Use k6 or hey for load tests
hey -n 10000 -c 100 http://my-app.cluster.local/api

# Monitor metrics
kubectl top pods -l app=my-app

Network Validation

# Test internal DNS resolution
kubectl run test --rm -it --image=busybox -- nslookup my-service

# Check endpoints
kubectl get endpoints my-service

Key takeaway: Automate your validation tests in a CI/CD pipeline. A reproducible test suite guarantees the quality of each migration.

The CI/CD Pipeline for Kubernetes Applications guide details deployment automation.

What Pitfalls to Avoid During Docker Swarm to Kubernetes Migration?

Migration experience reveals recurring errors to anticipate.

Underestimating Volume Management

Docker Swarm simplifies volume sharing between nodes. Kubernetes requires a distributed storage solution (NFS, Ceph, cloud provider).

# Kubernetes PersistentVolumeClaim
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-storage
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
storageClassName: standard

Ignoring Network Differences

The Swarm overlay network works differently from Kubernetes CNIs. Explicitly test inter-service communication.

Neglecting Health Checks

Kubernetes uses three types of probes (liveness, readiness, startup) versus a single healthcheck mechanism in Swarm.

livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: 8080
initialDelaySeconds: 5
periodSeconds: 5

To resolve deployment issues, refer to Resolve Common Kubernetes Deployment Errors.

Forgetting Resource Constraints

Swarm allows deploying without specifying limits. Kubernetes allows it too, but it's bad practice in production.

resources:
requests:
memory: "128Mi"
cpu: "100m"
limits:
memory: "256Mi"
cpu: "500m"

How to Optimize Your Images for Kubernetes?

Migration represents an opportunity to optimize your container images. According to Cloud Native Now, multi-stage builds reduce image size from 800 MB to 15-30 MB.

Use Lightweight Base Images

# Instead of
FROM ubuntu:22.04

# Prefer
FROM alpine:3.19
# or
FROM gcr.io/distroless/static-debian12

An Alpine image weighs about 3 MB versus 70 MB for Ubuntu (Medium Docker Optimization).

Multi-Stage Builds

# Build stage
FROM golang:1.22 AS builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o main .

# Production stage
FROM alpine:3.19
COPY --from=builder /app/main /main
CMD ["/main"]

The system administrator Kubernetes Fundamentals training guide covers these best practices.

Plan Your Skill Development

Key takeaway: A successful migration relies as much on human skills as on technical tools. Train your teams before migrating.

The Kubernetes Application Development hub centralizes resources for developers.

For post-migration observation, consult Observability and Monitoring of Kubernetes Applications.

Take Action: Kubernetes Migration Training

Docker Swarm to Kubernetes migration requires a deep understanding of both ecosystems. Official Linux Foundation trainings effectively prepare your teams.

Recommended trainings for Cloud operations engineers:

• LFD459 Kubernetes for Application Developers: 3 days to master containerized application deployment, ideal for developers migrating from Docker Swarm
• LFS458 Kubernetes Administration: 4 days for Kubernetes infrastructure engineers responsible for production clusters
• Kubernetes Fundamentals: 1 day of discovery to initiate teams to basic concepts

As Chris Aniszczyk of the CNCF states: "Kubernetes is no longer experimental but foundational. Soon, it will be essential to AI as well." Position your teams now.