Programster's Blog

Tutorials focusing on Linux, programming, and open-source

Docker Swarm Cheatsheet

Cluster Status

Use the following command to get the status of a cluster. This can only be run from a manager node.

docker node ls

  1. This node is the "primary" manager that actually manages the cluster. The other managers are replicas there for redundancy.
  2. This node is "drained" meaning that it is not running any services, nor will any services be deployed to it in future. This is can be good for managers as it means they are dedicated to managing.
  3. This node is unreachable, meaning it has likely gone offline.
  4. This star indicates the node that you ran the query on.

You may notice that one of the nodes has a blank under the manager status. This means that it is a worker node and not a manager.

Node Management

Add A Node

When you created the cluster, you should have been given the command that you need to give to other nodes in order to join the cluster. If you don't have this command anymore, you can retrieve it by executing:

docker swarm join-token worker

If you want to get the command to join nodes as managers, you can execute:

docker swarm join-token manager

The output of both of these commands will be similar to below:

To add a manager to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-154zu01lysyz6qbqxhm5i27b591gg8ffhce2jq438damwelgz6-2qve6pcf9y6j5t3d9dmqnl5kg \

Scale the service in the swarm Now that you have the relevant command, simply execute it from the node that you wish to have join the swarm. Make sure not to have more than 7 managers, but you can have as many workers as you like.

Remove A Node

To gracefully remove a node from a cluster, use the following command on the node itself:

docker swarm leave

If the node is currently a manager, you will need to demote it before trying to leave the swarm.

The node will still show in the list of nodes in the cluster, but its status will be Down and its availability will be Active.

To now remove the node from the cluster, run the following command on the manager.

docker node rm $NODE_ID

Inspect Node

docker node inspect --pretty $NODE_ID

Drain Node

If you want to gracefully remove any containers from a node, and prevent services from running on that node in future then you want to drain it. This could be a useful step to run before updating and rebooting nodes.

docker node update \
--availability drain \

Draining your manager nodes may be a good idea to keep them dedicated to managing the cluster. You may wish to maintain a few tiny, dedicated management nodes for redundancy/reliability and have larger worker nodes for hosting the services.

To undo this change, execute:

docker node update --availability active $NODE_ID

Refer here for more info on draining nodes.

Demote Node

To demote a node from a manager to a "follower" node, use the command below:

docker node demote $NODE_ID

Promote Node

To promote a node from a worker to a manager, execute:

docker node promote $NODE_ID

Make sure to have an odd number of managers, and no more than 7. All managers should have minimal downtime and have static IPs.


To deploy your application to a swarm cluster, you deploy it as a service. By being a service, it has the ability to:

  • be deployed to any of the nodes.
  • be automatically re-deployed if it dies.
  • can be scaled to be run any number of times simultaneously across the cluster.
  • have requests be load-balanced across running containers of the service.

Create Service

To deploy your application as a service run:

docker service create $IMAGE

Chances are that you probably want to give your service a name to reference it by, and you may want to specify the number of instances/replicas:

docker service create --name my_web --replicas 3 $IMAGE

Please refer here for the full list of optional parameters.

Remove Service

When you want to remove a service from your cluster, use the following command:

docker service rm $SERVICE_ID

List Services

To see which services are running on your cluster:

docker service ls

Scale Service

If you want to scale up/down after a service has already been deployed...

docker service scale $SERVICE_ID=$NUM_INSTANCES

For example

docker service scale whoami=3

List Service Processes

When there are multiple instances of a single service running, you can see them with:

docker service ps $SERVICE_ID

This will indicate which nodes the service's containers are running on.

ID                         NAME          SERVICE     IMAGE   LAST STATE          DESIRED STATE  NODE
8p1vev3fq5zm0mi8g0as41w35  helloworld.1  helloworld  alpine  Running 7 minutes   Running        worker2
c7a7tcdq5s0uk3qr88mf8xco6  helloworld.2  helloworld  alpine  Running 24 seconds  Running        worker1
6crl09vdcalvtfehfh69ogfb1  helloworld.3  helloworld  alpine  Running 24 seconds  Running        worker1
auky6trawmdlcne8ad8phb0f1  helloworld.4  helloworld  alpine  Running 24 seconds  Accepted       manager1
ba19kca06l18zujfwxyc5lkyn  helloworld.5  helloworld  alpine  Running 24 seconds  Running        worker2

Overlay Networks

Containers deployed on the same overlay network can communicate with each other, even when they are on different nodes. For more information pleas refer here.

Create Overlay Network

The command below will create an overlay network called my-network.

docker network create \
  --driver overlay \
  --subnet \
  --opt encrypted \

Remove Overlay Network

docker network rm $NETWORK_ID

Deploy Service To Specific Network

Use the --network [overlay network ID] option when creating a service if you wish to specify which network to join.

List Networks

docker network ls

Example output:

NETWORK ID          NAME                DRIVER              SCOPE
a924a6335935        bridge              bridge              local               
0eb588929cb3        docker_gwbridge     bridge              local               
6520f47d6e19        host                host                local               
8puto62h939d        ingress             overlay             swarm               
064db85ed9e3        none                null                local               
0fv9x8scsntd        traefik-net         overlay             swarm

Inspect Network

docker network inspect $NETWORK_ID


Last updated: 8th August 2020
First published: 16th August 2018