Docker Swarm: Container Orchestration for Beginners

Docker Docker 8 min read 1637 words Beginner ExcellentWiki Editorial Team

Docker Swarm turns a group of Docker hosts into a single virtual Docker host. It is Docker’s native clustering and orchestration solution — built directly into the Docker engine with no additional installation required. While Kubernetes has become the dominant orchestrator, Swarm remains popular for smaller deployments because of its simplicity.

Why Docker Swarm?

Swarm is dramatically simpler than Kubernetes. A single-node Swarm cluster takes seconds to initialize. The API is the same Docker API you already know — docker service create replaces docker run, but the flags and concepts are nearly identical.

Key advantages:

Built into Docker — no extra installation
Docker-native CLI — learn once, run anywhere
Declarative service model — define desired state, Swarm maintains it
Built-in load balancing — ingress routing mesh included
Secure by default — TLS for all node communication

Swarm Architecture

┌─────────────────────────────────────────┐
│               Swarm Cluster             │
│                                         │
│  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Manager  │  │ Manager  │  │ Worker │ │
│  │  Node 1  │  │  Node 2  │  │ Node 3 │ │
│  └────┬─────┘  └────┬─────┘  └───┬────┘ │
│       │              │            │       │
│       └──────────────┴────────────┘       │
│                  Consensus (Raft)          │
└──────────────────────────────────────────┘

Manager nodes handle cluster management — maintaining state, scheduling services, and responding to API requests. Worker nodes run the actual containers. Manager nodes also act as workers by default.

Raft Consensus

Swarm uses the Raft consensus algorithm to maintain a consistent cluster state across managers. For fault tolerance, deploy an odd number of managers:

1 manager: tolerates 0 failures
3 managers: tolerates 1 failure
5 managers: tolerates 2 failures

Setting Up a Swarm

Initialize the Swarm

# On the first manager node
docker swarm init --advertise-addr 192.168.1.10

# Output includes join tokens
# To add a worker: docker swarm join --token WORKER_TOKEN ...
# To add a manager: docker swarm join --token MANAGER_TOKEN ...

The --advertise-addr should be the IP address other nodes use to reach this node. On cloud VMs, this is typically the private IP.

Add Worker Nodes

# On each worker node
docker swarm join --token SWMTKN-1-xxxx 192.168.1.10:2377

# View nodes in the cluster
docker node ls

Add Manager Nodes

# Get the manager join token
docker swarm join-token manager

# On the new manager node
docker swarm join --token MANAGER-TOKEN 192.168.1.10:2377

Deploying Services

Services are the Swarm equivalent of containers. You define a desired state, and Swarm ensures it is maintained.

# Create a service with 3 replicas
docker service create \
  --name web \
  --replicas 3 \
  --publish 80:80 \
  nginx:alpine

# List services
docker service ls

# List service tasks (containers)
docker service ps web

# View service logs
docker service logs web

Scaling Services

# Scale to 5 replicas
docker service scale web=5

# Scale multiple services at once
docker service scale web=5 api=3 worker=10

# Scale down
docker service scale web=2

Swarm distributes replicas across available nodes. It spreads containers evenly by default but supports constraints for node-specific placement.

Rolling Updates

Swarm supports zero-downtime rolling updates with configurable parallelism and delay:

# Update image with rolling update
docker service update \
  --image nginx:1.25 \
  --update-parallelism 2 \
  --update-delay 10s \
  web

This updates 2 replicas at a time, waiting 10 seconds between batches. If the update fails, Swarm automatically rolls back:

# Roll back to previous state
docker service rollback web

Update Configuration Options

Flag	Default	Purpose
`--update-parallelism`	1	Number of replicas updated at once
`--update-delay`	0s	Pause between updates
`--update-failure-action`	`pause`	What happens on failure (`pause` or `continue`)
`--rollback-parallelism`	Same as update	Rollback batch size
`--rollback-monitor`	5s	Time to monitor after rollback

Service Discovery and Networking

Swarm provides built-in DNS-based service discovery:

# Create an overlay network
docker network create --driver overlay app-net

# Deploy services on the overlay network
docker service create \
  --name api \
  --network app-net \
  --replicas 3 \
  my-api:latest

docker service create \
  --name web \
  --network app-net \
  --publish 80:80 \
  my-web:latest

Services communicate using service names as hostnames — the web service can reach http://api:3000 directly. The overlay network spans all nodes, so containers on different hosts communicate seamlessly.

Ingress Routing Mesh

Swarm’s routing mesh allows every node to accept connections on published ports and route them to any container in the cluster, regardless of which node is actually running that container. This means you can point a load balancer at any node and the traffic will be routed correctly.

Production Best Practices

Resource Limits

Always set resource limits to prevent noisy neighbors:

docker service create \
  --name api \
  --reserve-cpu 0.5 \
  --reserve-memory 256M \
  --limit-cpu 1 \
  --limit-memory 512M \
  my-api:latest

Placement Constraints

Pin services to specific node types:

# Run database only on nodes with SSD label
docker node update --label-add ssd=true node-3

docker service create \
  --name postgres \
  --constraint 'node.labels.ssd == true' \
  --mount type=volume,source=pgdata,target=/var/lib/postgresql/data \
  postgres:16

Secrets Management

# Create a secret
echo "my-db-password" | docker secret create db_password -

# Use in a service
docker service create \
  --name api \
  --secret db_password \
  --secret api_key \
  my-api:latest

Health Checks

docker service create \
  --name web \
  --health-cmd "curl -f http://localhost/ || exit 1" \
  --health-interval 10s \
  --health-retries 3 \
  --health-start-period 30s \
  nginx:alpine

Monitoring a Swarm

# Node status
docker node ls

# Service status
docker service ls

# Task (container) details
docker service ps <service-name>

# Real-time stats
docker stats $(docker ps -q)

# Inspect node
docker node inspect <node-id> --pretty

FAQ

How does Docker Swarm compare to Kubernetes?

Swarm is simpler to set up and use but has fewer features. Kubernetes offers auto-scaling, self-healing, service meshes, and a vast ecosystem — but requires significant operational expertise. Swarm is ideal for small to medium deployments where simplicity matters more than feature breadth.

Can I run Swarm on a single node?

Yes. A single-node Swarm is useful for testing and small-scale production. Initialize with docker swarm init and all workloads run on the same machine.

How do I update a service without downtime?

Use rolling updates with docker service update --image new:tag --update-parallelism 2 --update-delay 10s. Swarm replaces replicas gradually, keeping the service available throughout.

What happens if a Swarm manager fails?

Swarm uses Raft consensus. With 3 managers, the cluster tolerates 1 failure. The remaining managers continue to operate, and the failed node can be replaced or re-added later.

How do I leave a Swarm cluster?

On each worker node, run docker swarm leave. On a manager node, run docker swarm leave --force. The node stops participating but the Docker engine continues running normally.

Related: Learn Docker Compose and Docker networking.

Docker Swarm Architecture

Docker Swarm clusters consist of manager nodes (control plane) and worker nodes (execution). Managers run the Raft consensus algorithm to maintain cluster state — use 3 or 5 managers for fault tolerance. Services are the declarative unit of deployment: docker service create --name web --replicas 3 --publish 80:80 nginx. Swarm services support rolling updates with --update-parallelism 2 --update-delay 10s. Secrets management: docker secret create db_password ./password.txt. Swarm mode ingress routing mesh exposes services across all nodes. Stacks (docker stack deploy -c compose.yaml mystack) deploy multi-service applications from Compose files. Node labels constrain services to specific nodes. Swarm supports secrets, configs, networks, and volumes as first-class objects.

Docker Stack Deployments

Docker Compose files become stack definitions in Swarm mode. The docker stack deploy command accepts a Compose file and converts it into Swarm services with automatic networking, secrets, and configs. Unlike docker-compose up, stacks support rolling updates, replicated services, and declarative state management. Use deploy section in your Compose file to configure Swarm-specific settings: resources, restart_policy, placement, and update_config. The mode: replicated setting runs a specified number of replicas, while mode: global runs one task per node. Logging drivers like json-file, gelf, and splunk forward container logs from all Swarm nodes to a centralized system. For zero-downtime deployments, use --update-order start-first to start new tasks before stopping old ones.

Swarm vs Kubernetes

Swarm excels at simplicity — easier to set up and operate than Kubernetes for small-to-medium deployments. It integrates natively with Docker Compose. However, Swarm lacks Kubernetes’ auto-scaling, self-healing, service mesh integration, and ecosystem breadth. Choose Swarm for simpler operations, Kubernetes for complex deployments. Many teams start with Swarm for its low operational overhead and migrate to Kubernetes when they need advanced scheduling, auto-scaling, or ecosystem integrations. Consider Docker Swarm for teams with limited DevOps headcount or small-to-medium microservice deployments running fewer than 20 services.