Leave a Docker Swarm Node Without Losing Manager Quorum

docker swarm leave pulls one node out of its cluster, and run on the wrong manager it can strand the rest below quorum. A worker leaves in about fifteen minutes. A manager needs a maintenance window and a second, healthy manager standing by. Examples use Docker CE CLI 29.8.1, package version 5:29.8.1-1~ubuntu.24.04~noble, installed on this machine.

1. Check the command and the local swarm state

First confirm the installed syntax. This is an ordinary, read-only check and normally needs no elevated privilege:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker swarm leave --help
Usage:  docker swarm leave [OPTIONS]

Leave the swarm

Options:
  -f, --force   Force this node to leave the swarm, ignoring warnings

Then ask the local Docker Engine whether this host belongs to a swarm:

$ docker info --format 'Swarm={{.Swarm.LocalNodeState}} Control={{.Swarm.ControlAvailable}}'
Swarm=active Control=false

• Active means joined. LocalNodeState=active means this Engine is in a swarm; inactive means there is nothing local to leave.
• False means worker. Control=false identifies a worker here; a manager normally reports Control=true.
• Skip sudo. Add it only if your Docker socket permissions actually require it, and fix ordinary group or service-account access through your normal administration process rather than reaching for it by habit.

$ docker context show
default

2. Leave a worker from that worker

A worker can leave by running the command locally. Run it on the node being retired, not on a different manager:

$ docker swarm leave
Node left the default swarm.

The swarm name in the message can differ from default. What matters is a clean exit and that message. Verify the local state:

$ docker info --format 'Swarm={{.Swarm.LocalNodeState}} Control={{.Swarm.ControlAvailable}}'
Swarm=inactive Control=false

Leaving does not scrub every record of the node from a manager's memory. From a manager, docker node ls may keep showing it as down: that stale entry is not proof the worker is still participating. If it is just clutter, an administrator can remove it with docker node rm NODE_ID from a manager, after checking the exact node ID. That is a separate cluster operation.

There is no undo command for a completed leave. To put the machine back, get a fresh worker join command from a manager and run it there, for example:

$ docker swarm join --token <WORKER_JOIN_TOKEN> <MANAGER_HOST>:2377
This node joined a swarm as a worker.

Keep the token private. If it has been exposed, rotate the worker join token from a manager before reusing it.

3. Inspect a manager before touching it

Managers store and replicate swarm state, so a manager should normally be demoted before it leaves. Run these checks from a manager, where docker node ls is available:

$ docker node ls
ID                         HOSTNAME    STATUS  AVAILABILITY  MANAGER STATUS
<THIS_NODE_ID>             manager-a   Ready   Active         Leader
<OTHER_NODE_ID>            manager-b   Ready   Active         Reachable
<WORKER_NODE_ID>           worker-a    Ready   Active
$ docker node inspect <THIS_NODE_ID> --format '{{.ManagerStatus.Reachability}}'
reachable

Replace the placeholders with the real values, and do not guess manager health from the hostname alone. Count the manager rows and confirm another reachable manager can perform the next command: Raft needs a majority. A three-manager swarm needs two available, so losing one is normally fine, but losing a second before the first change settles is not.

If the node you want gone is the only manager, do not use --force just to make the warning go away. A single-node swarm has no manager redundancy. Decide first whether the whole swarm is being retired or another node will be promoted, and keep any required service and swarm backups current.

4. Demote the manager, then leave it

From another healthy manager, demote the target to a worker:

$ docker node demote <TARGET_MANAGER_ID_OR_NAME>
Manager <TARGET_MANAGER_ID_OR_NAME> demoted in the swarm.

Verify the target has lost its manager status before you connect to it:

$ docker node ls
ID                         HOSTNAME    STATUS  AVAILABILITY  MANAGER STATUS
<TARGET_NODE_ID>           manager-a   Ready   Active
<OTHER_NODE_ID>            manager-b   Ready   Active         Leader

Now connect to the target machine and run the ordinary worker leave from step 2. Demotion changes its role in the swarm; leaving removes its local membership. If the target is also running service tasks, plan for those to be rescheduled and check placement afterwards.

5. Diagnose a failed leave without repeating the damage

• Says it is not part of a swarm. Inspect docker info and the active context. An inactive local state means the leave already happened, or you are on the wrong Engine. Do not retry with --force.
• Warns that a manager must be demoted. Go back to step 3 and use another reachable manager. If there is no reachable majority, stop making membership changes: workers can keep running, but the swarm cannot reliably process management requests until quorum is back. Treat a timeout as an incident, not permission to fire off several force commands.
• Fails to reach the daemon or socket. Check the service and permissions without changing swarm state:

$ docker info --format '{{.ServerVersion}}'
29.8.1
$ systemctl is-active docker
active

Use sudo systemctl is-active docker only when your account cannot query the service. Restarting Docker is not part of a normal leave and can disrupt workloads, so schedule that separately if diagnostics point to a daemon problem.