Docker Swarm Cheat Sheet: 20 Essential Commands Every Engineer Must Know

Introduction

Looking for a quick reference to manage a Docker Swarm cluster? This cheat sheet gives you the 20 most used Docker Swarm commands, from initializing a manager node to scaling services, securing secrets, and troubleshooting. Keep it handy for fast, error‑free deployments.

Getting Started with the Swarm Manager

Command	Purpose	Sample Usage
docker swarm init	Creates the first manager node and starts a new swarm.	docker swarm init --advertise-addr 192.168.1.100
docker swarm join	Adds a worker or manager to an existing swarm.	docker swarm join --token SWMTOK-1-abc123 manager-ip:2377
docker swarm leave	Removes the current node from the swarm.	docker swarm leave
docker swarm update	Updates swarm‑wide settings (e.g., heartbeat).	docker swarm update --dispatcher-heartbeat 30s

Tip: After docker swarm init the CLI prints both worker and manager join tokens. Store them securely – you’ll need them for every new node.

Node‑Level Operations

Command	Purpose	Sample Usage
docker node ls	Lists every node, its role, and status.	docker node ls
docker node inspect <node>	Shows detailed JSON metadata.	docker node inspect --pretty worker-1
docker node promote <node>	Turns a worker into a manager.	docker node promote worker-2
docker node demote <node>	Reverts a manager back to a worker.	docker node demote manager-3
docker node update	Adjusts node attributes (e.g., drain).	docker node update --availability drain worker-1
docker node rm <node>	Removes a node from the cluster.	docker node rm worker-2

Best practice: Drain a node (--availability drain) before removal so tasks are rescheduled automatically.

Service Management

Command	Purpose	Sample Usage
docker service create	Creates a new replicated or global service.	docker service create --name web --replicas 3 -p 80:80 nginx:latest
docker service ls	Lists all services.	docker service ls
docker service ps <svc>	Shows every task belonging to a service.	docker service ps web
docker service update	Modifies an existing service (image, env, resources).	docker service update --image nginx:1.21 --replicas 5 web
docker service scale <svc>=<n>	Quickly changes replica count.	docker service scale web=7
docker service rollback <svc>	Reverts a service to the previous version.	docker service rollback web
docker service logs <svc>	Streams logs from all tasks.	docker service logs -f web
docker service rm <svc>	Deletes a service.	docker service rm web
docker service inspect <svc>	Returns the full service spec.	docker service inspect --pretty web

When to use docker service update vs. docker service scale:

• Use update for any change beyond replica count (image version, env vars, resources).
• Use scale for a one‑liner when you only need to adjust replicas.

Stack & Compose Deployments

Command	Purpose	Sample Usage
docker stack deploy -c <compose.yml> <stack>	Deploys a multi‑service application defined in a Compose file.	docker stack deploy -c docker-compose.yml mystack
docker stack ls	Lists all deployed stacks.	docker stack ls
docker stack services <stack>	Shows services belonging to a stack.	docker stack services mystack
docker stack ps <stack>	Shows tasks across the whole stack.	docker stack ps mystack
docker stack rm <stack>	Tears down an entire stack.	docker stack rm mystack
docker compose config	Validates a Compose file locally.	docker compose -f docker-compose.yml config

Tip: Use Compose version 3.8 or higher to get full Swarm features like deploy: constraints, resources, and update‑config.

Networking Essentials

Command	Purpose	Sample Usage
docker network create -d overlay <net>	Creates an overlay network spanning all swarm nodes.	docker network create -d overlay backend
docker network ls	Lists all networks.	docker network ls
docker network inspect <net>	Shows details and attached services.	docker network inspect backend
docker network rm <net>	Deletes an unused network.	docker network rm backend
docker service create --network <net>	Attaches a service to a specific overlay network.	docker service create --name api --network backend myapi:latest

Security note: Overlay networks are encrypted by default when the daemon runs with TLS. For end‑to‑end encryption add --opt encrypted when creating the network.

Secrets & Configs

Command	Purpose	Sample Usage
docker secret create <name> -	Stores a sensitive value in the swarm Raft store.	echo "s3cr3t" | docker secret create db_password -
docker secret ls	Lists all secrets.	docker secret ls
docker secret inspect <name>	Shows metadata (never the secret value).	docker secret inspect db_password
docker secret rm <name>	Deletes a secret.	docker secret rm db_password
docker config create <name> <file>	Stores non‑secret configuration files.	docker config create nginx_conf ./nginx.conf
docker config ls	Lists stored configs.	docker config ls
docker service create --secret <name> --config <name>	Injects secret/config into a service at runtime.	docker service create --name web --secret db_password --config nginx_conf nginx:latest

Best practice: Use secrets for passwords, TLS keys, and API tokens. Use configs for static files that can be version‑controlled (e.g., Nginx config).

Monitoring & Debugging

Command	Purpose	Sample Usage
docker service logs <svc>	Real‑time logs from every replica.	docker service logs -f --tail 20 web
docker node ps <node>	Shows tasks running on a specific node.	docker node ps worker-1
docker system df	Disk usage summary for images, containers, volumes.	docker system df
docker events --filter 'type=service'	Streams low‑level events for scripting alerts.	docker events --filter 'type=service'
docker stats	Live CPU / memory usage for all containers.	docker stats
docker inspect $(docker ps -q)	Bulk‑inspect all containers; pipe through jq for queries.	docker ps -q | xargs docker inspect -f '{{.Name}} {{.State.Status}}'

Pro tip: Pair docker service logs with a log aggregator like EFK or Loki for searchable, persistent logs.

Common Pitfalls & Best‑Practice Tips

Issue	Why it Happens	Fix / Recommendation
Orphaned manager after network split	Managers lose quorum, swarm becomes unavailable.	Keep an odd number of managers (3,5,7). Demote before removal.
Service stuck in Pending	No node satisfies placement constraints or resources are low.	Run docker service ps <svc> to view error, check node resources with docker node inspect.
Secrets not propagating	Service created before the secret existed.	Create the secret first, then update the service: docker service update --secret-add <name> <svc>.
Overlay network not reachable	Firewall blocks required ports (2377, 7946, 4789) or mixed IPv4/IPv6.	Open those ports on every node; verify with iptables -L -n or cloud security groups.
Image pull failures	Private registry requires auth but service lacks credentials.	Create a registry secret and reference it in the service.
Unexpected task restarts	Health‑check failures or low resource limits.	Inspect the task (docker service ps --no-trunc <svc>) and adjust --limit-cpu/--limit-memory.

Quick Real‑World Workflow Example

Deploy a three‑tier web app (frontend → API → PostgreSQL) using Docker Swarm.

# 1️⃣ Initialise the swarm (run on the first manager)
 docker swarm init --advertise-addr 10.0.0.10

# 2️⃣ Grab join tokens (store them securely)
 docker swarm join-token manager
 docker swarm join-token worker

# 3️⃣ Add two worker nodes (run on each worker)
 docker swarm join --token SWMTOK-1-xxxx 10.0.0.10:2377

# 4️⃣ Create an encrypted overlay network
 docker network create -d overlay --opt encrypted backend

# 5️⃣ Store DB credentials as a secret
 echo "myStrongPassword" | docker secret create db_pass -

# 6️⃣ Deploy the stack (docker‑compose.yml defines three services)
 cat > docker-compose.yml <<'EOF'
 version: "3.8"
 services:
   db:
     image: postgres:15
     environment:
       POSTGRES_PASSWORD_FILE: /run/secrets/db_pass
     secrets:
       - db_pass
     networks:
       - backend
     deploy:
       replicas: 1
       placement:
         constraints: [node.role == manager]

   api:
     image: myorg/api:1.2
     depends_on:
       - db
     networks:
       - backend
     deploy:
       replicas: 3
       resources:
         limits:
           memory: 256M

   web:
     image: nginx:stable-alpine
     ports:
       - "80:80"
     networks:
       - backend
     deploy:
       replicas: 2
 networks:
   backend:
     external: true
 secrets:
   db_pass:
     external: true
 EOF

 docker stack deploy -c docker-compose.yml prod

This script creates a manager, adds workers, builds an encrypted overlay, stores a secret, and launches a full stack. Scale any tier with a single command, e.g.:

docker service scale prod_api=5   # add two more API replicas
docker service update --image myorg/api:1.3 prod_api   # rolling upgrade

Full‑Command Reference Table

#	Command	Category	Core Use‑Case
1	docker swarm init	Swarm init	Create first manager
2	docker swarm join	Swarm join	Add node (worker/manager)
3	docker swarm leave	Swarm leave	Remove node
4	docker swarm update	Swarm config	Change heartbeat, auto‑lock
5	docker node ls	Node mgmt	List nodes
6	docker node inspect	Node mgmt	Detailed node info
7	docker node promote	Node mgmt	Worker → manager
8	docker node demote	Node mgmt	Manager → worker
9	docker node update	Node mgmt	Drain, set labels
10	docker node rm	Node mgmt	Delete node
11	docker service create	Service	New replicated/global service
12	docker service ls	Service	List services
13	docker service ps	Service	View tasks
14	docker service update	Service	Rolling update
15	docker service scale	Service	Change replica count
16	docker service rollback	Service	Revert last update
17	docker service logs	Service	Stream logs
18	docker service rm	Service	Delete service
19	docker stack deploy	Stack	Deploy multi‑service app
20	docker stack rm	Stack	Remove entire stack

Suggested Further Reading

• Official Docker Swarm documentation
• Docker Swarm 101 – Getting started guide
• Awesome Docker Compose examples for Swarm
• Monitoring Docker Swarm with Sysdig

Conclusion

Docker Swarm provides a lightweight, native orchestration layer for teams that love the Docker CLI. Knowing these 20 commands lets you spin up a secure cluster, scale services with zero downtime, protect secrets, and debug issues fast. Keep this cheat sheet bookmarked and you’ll spend more time building applications and less time searching docs.

Meta Description: Quick Docker Swarm cheat sheet with 20 essential commands for initializing, scaling, securing, and troubleshooting a Swarm cluster – perfect for developers and engineers.

Focus Keywords: Docker Swarm, Docker Swarm commands, Docker Swarm cheat sheet, Docker service, Docker stack, overlay network, Docker secrets

Related: 🛠️ Master Automation with Curl: 10 Essential Commands for Every Sysadmin 🛠️.

Related: Install node-red via docker.