Docker Swarm Cheat Sheet
Commands and concepts for initializing a Docker Swarm cluster, deploying stacks, and managing services and nodes.
2 PagesIntermediateFeb 20, 2026
Cluster Setup
Initialize and join a Swarm cluster.
bash
docker swarm init --advertise-addr <MANAGER_IP> # Init on first managerdocker swarm join-token worker # Get worker join commanddocker swarm join-token manager # Get manager join commanddocker node ls # List cluster nodesdocker node promote <NODE> # Promote worker to managerdocker node update --availability drain <NODE> # Drain a node for maintenance
Service Management
Create and control services on the Swarm.
bash
docker service create --name web --replicas 3 -p 80:80 nginxdocker service ls # List servicesdocker service ps web # List tasks/replicas for a servicedocker service scale web=5 # Scale replicasdocker service update --image nginx:1.25 web # Rolling updatedocker service logs web # View service logsdocker service rm web # Remove a service
Stack Deploy File
Deploy a multi-service application as a stack.
yaml
version: "3.8"services: web: image: myorg/web:1.4 deploy: replicas: 3 update_config: parallelism: 1 delay: 10s restart_policy: condition: on-failure ports: - "80:80" networks: - overlay-netnetworks: overlay-net: driver: overlay
Key Concepts
How Swarm organizes work across the cluster.
- Manager node- Maintains cluster state via Raft consensus and schedules tasks (odd number recommended, e.g. 3 or 5)
- Worker node- Executes tasks assigned by managers; does not participate in Raft by default
- Task- A single running container instance that is part of a service
- Overlay network- A multi-host virtual network letting containers on different nodes communicate
- Secrets- Encrypted data (docker secret create) mounted into containers at /run/secrets
- Rolling update- Deploy updates gradually per update_config parallelism/delay to avoid downtime
Stack Commands
Deploying and inspecting stacks.
bash
docker stack deploy -c docker-stack.yml myapp # Deploy a stackdocker stack services myapp # List stack servicesdocker stack ps myapp # List stack tasksdocker stack rm myapp # Remove a stack
Secrets, Configs & Rotation
Create versioned secrets/configs and roll them into a running service without downtime.
bash
# Create a secret from a fileprintf 's3cr3t' | docker secret create db_password_v2 -# Roll it into a running service, removing the old referencedocker service update \ --secret-rm db_password_v1 \ --secret-add source=db_password_v2,target=db_password \ api# Configs follow the same create/rotate patterndocker config create nginx_conf_v2 ./nginx.confdocker service update \ --config-rm nginx_conf_v1 \ --config-add source=nginx_conf_v2,target=/etc/nginx/nginx.conf \ web
Placement Constraints & Preferences
Pin tasks to specific nodes by label and spread replicas evenly across failure domains.
bash
docker node update --label-add zone=us-east-1a node-1docker node update --label-add zone=us-east-1b node-2docker service create --name api \ --replicas 6 \ --constraint 'node.labels.zone!=us-east-1c' \ --placement-pref 'spread=node.labels.zone' \ --constraint 'node.role==worker' \ myorg/api:1.0
Raft Quorum & Disaster Recovery
Inspect manager quorum health and recover a cluster that has lost the majority of managers.
bash
# Check quorum status per managerdocker node ls --filter role=managerdocker info --format '{{.Swarm.ControlAvailable}} {{.Swarm.Error}}'# Back up swarm state regularly (stop docker or use --detach snapshot on newer engines)tar -czf swarm-state-backup.tgz /var/lib/docker/swarm# Force a new cluster from a single surviving manager after quorum lossdocker swarm init --force-new-cluster --advertise-addr <THIS_NODE_IP>
Rollback & Health-Gated Rolling Updates
Configure automatic rollback when a rolling update fails its healthcheck, and trigger a manual rollback.
yaml
version: "3.8"services: api: image: myorg/api:2.1 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"] interval: 10s retries: 3 deploy: replicas: 4 update_config: parallelism: 1 delay: 15s failure_action: rollback monitor: 30s max_failure_ratio: 0.2 rollback_config: parallelism: 2 delay: 5s order: stop-first
Overlay Networking Internals
How traffic actually moves between tasks and nodes in a Swarm cluster.
- VXLAN encapsulation- Overlay networks tunnel container traffic between hosts over UDP 4789; must be open between all nodes
- ingress network- Built-in overlay network used by the routing mesh; published ports are reachable on every node, not just the one running the task
- --endpoint-mode dnsrr- Switches a service from VIP (virtual IP + internal load balancing) to DNS round-robin, useful for client-side LB or non-TCP protocols
- docker network create --attachable- Allows standalone (non-service) containers to join an overlay network for debugging or bridging with legacy containers
- gossip protocol (control plane)- Managers propagate network/service state via a gossip protocol on UDP/TCP 7946, separate from the Raft log on 2377
- encrypted overlay- Pass --opt encrypted when creating an overlay network to enable IPSec encryption of inter-node traffic
Pro Tip
Run managers on an odd number of nodes (3 or 5) so Raft consensus can tolerate failures without a split-brain; never run just 2 managers.
Was this cheat sheet helpful?
Explore Topics
#DockerSwarm#DockerSwarmCheatSheet#DevOps#Intermediate#ClusterSetup#ServiceManagement#StackDeployFile#KeyConcepts#DataStructures#Docker#CheatSheet#SkillVeris
