Demote a Docker Swarm Manager Without Losing Quorum

You will demote one or more Docker Swarm managers to workers, verify the new roles, and know how to restore a manager role if the change was premature. The examples use the installed Docker Community CLI package version 5:29.8.1-1~ubuntu.24.04~noble and the syntax documented by docker-node-demote(1).

Allow about ten minutes for a planned change, plus time to check your services. You need access to a healthy Swarm manager and permission to use its Docker daemon socket. The demotion changes cluster membership state, so treat it as an administrative operation. Use sudo only when your Docker setup requires it; the command itself does not need a shell root prompt if your account already has Docker access.

1. Confirm that you are on a manager

Run the read-only node listing from the machine whose Docker context points at the target swarm:

$ docker node ls

The output has a MANAGER STATUS column. A healthy manager normally shows a status such as Leader or Reachable. The asterisk marks the node used by the current Docker daemon. If the command says that it must be run on a manager, switch to another manager or select the correct Docker context before continuing.

Checkpoint: write down the exact node name or ID you intend to demote. Do not use a hostname copied from an unrelated inventory when two swarm nodes have similar names.

2. Check the manager count and quorum

Count the managers in the MANAGER STATUS column and identify which one is the leader. Swarm managers use Raft, so a majority must remain available for management operations. The useful rule is that three managers tolerate one manager loss, while five tolerate two. An odd number of managers is preferred.

Do not demote a manager if doing so would remove the majority. In a three-manager swarm, demoting one is normally the maximum planned reduction. In a two-manager swarm, demoting either one leaves no majority. Docker also protects the last manager from being demoted, but relying on that refusal is a poor change plan.

If the target is still running application tasks, demotion makes it a worker, not an empty machine. If your real aim is to stop scheduling new tasks there, drain it first and wait for tasks to move:

$ docker node update --availability drain NODE_NAME
$ docker node inspect NODE_NAME --format '{{ .Spec.Availability }}'
drain

Replace NODE_NAME with the exact node name or ID. Draining can disrupt workloads while tasks are rescheduled. If you only need to remove manager duties and are content for the node to keep running worker tasks, omit this optional change.

3. Demote the selected manager

Review the target and quorum one last time. This is the state-changing step:

$ docker node demote NODE_NAME

The installed command accepts one or more nodes, using the form docker node demote NODE [NODE...]. For a first change, demote one node at a time so that a failed request or unexpected quorum result has a small scope. You do not need to run the command on the machine being demoted; run it against a manager in the same swarm.

Do not use a manager demotion as a substitute for removing a failed node. For a failed manager that must leave the swarm, Docker's administrative procedure is to demote it first and then remove it. A separate docker node rm operation has additional safety checks and can have a larger operational effect.

4. Verify both the role and the swarm health

List the nodes again:

$ docker node ls

The target should remain in the list, but its MANAGER STATUS field should no longer contain a manager state. It should still have an ordinary node status such as Ready if the engine is healthy. Exact columns and values are host-specific, so verify the role rather than matching a complete line of output.

For a focused check, inspect the node's manager reachability:

$ docker node inspect NODE_NAME --format '{{ .ManagerStatus.Reachability }}'

A demoted node has no manager status to report. An empty result is therefore expected for this particular field; it is not evidence that the node disappeared. Use docker node ls to check that the node remains a worker, and inspect service placement if you drained it.

Checkpoint: confirm that the remaining managers still show a healthy leader and reachable peers. If the listing fails with a quorum or timeout error, stop making membership changes and restore manager availability before attempting another operation.

5. Undo an accidental demotion

Demotion is reversible while the node remains in the swarm. From a healthy manager, promote the worker again:

$ docker node promote NODE_NAME
$ docker node ls

Promotion restores the manager role but does not recreate a node that has been removed, nor does it repair a broken swarm. If you drained the node in step 2, restore scheduling separately only after checking its workload and capacity:

$ docker node update --availability active NODE_NAME

Changing availability back to active permits new task placement. It does not guarantee that tasks immediately return to that node. If the node was intentionally drained for maintenance, leave it drained until the maintenance window is finished.

Common traps

• Using a worker as the control point: node management commands must be sent through a manager. Check the Docker context as well as the machine name.
• Counting machines instead of managers: workers do not contribute to Raft quorum. Count manager entries, not every row in docker node ls.
• Demoting the leader during a tight maintenance window: the swarm may elect another manager, but plan for a short control-plane interruption and verify the new leader afterwards.
• Expecting demotion to stop containers: it changes the node role. Use drain when the scheduling behaviour must change, and check service tasks after rescheduling.
• Removing the node immediately: demotion and removal are separate operations. Keep the node in the swarm until you have verified the new role and no longer need its worker capacity.