Promote a Docker Swarm Worker Safely with docker node promote

You will promote one or more Docker Swarm workers to managers, confirm that the role changed, and keep an undo command ready. Allow about ten minutes for a planned change, plus time to check the swarm's manager quorum. The command changes swarm control-plane membership, so do not run it as a casual test against a production cluster.

1. Confirm the local Docker version and swarm role

The installed package here is Docker CE CLI 29.8.1, provided by docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. The local manual describes the command as docker node promote NODE [NODE...]. Docker's current reference says the command works with the Swarm orchestrator and must be run on a manager.

Check both the client and the daemon before you touch the cluster:

$ docker version --format '{{.Client.Version}} client, {{.Server.Version}} server'
29.8.1 client, 29.8.1 server
$ docker info --format 'state={{.Swarm.LocalNodeState}} manager={{.Swarm.ControlAvailable}}'
state=active manager=true

The exact version strings depend on your installation. If the state is not active, the current engine is not in a swarm. If manager=false, switch your Docker context or shell to a swarm manager. Do not initialise a new swarm merely to make this command available: docker swarm init would create a new cluster on the current engine.

2. List nodes and check the proposed target

Run the read-only node listing from a manager. Use the node ID or an unambiguous node name from this output:

$ docker node ls
ID                            HOSTNAME       STATUS    AVAILABILITY   MANAGER STATUS
u1...                         swarm-manager  Ready     Active          Leader
v2...                         app-worker-1   Ready     Active
w3...                         app-worker-2   Ready     Active

Before promotion, the target should be a worker, shown by an empty MANAGER STATUS column. Check its details when a name is similar to another node:

$ docker node inspect app-worker-1 --pretty
ID:                     v2...
Hostname:               app-worker-1
Status:
 State:                 Ready
 Availability:          Active
Manager Status:
 Address:               192.0.2.21:2377
 Raft Status:           
 Leader:                No

Output formatting varies by Docker release. The useful distinction is whether the node already has a manager role. Promoting a node that is already a manager is unnecessary; inspect the result before changing anything further.

3. Check quorum before adding a manager

Managers participate in the swarm's Raft consensus. Keep an odd number of managers where practical. A three-manager swarm can tolerate one manager failure, while a five-manager swarm can tolerate two. More managers do not automatically improve workload performance, and an overloaded manager can make control-plane operations less reliable.

Record the current manager count and decide where the new manager belongs before running the command:

$ docker node ls --format '{{.Hostname}}\t{{.ManagerStatus}}\t{{.Status}}'
swarm-manager  Leader     Ready
app-worker-1              Ready
app-worker-2              Ready

Do not promote a node just because a manager is unavailable. First establish whether the remaining managers still have quorum and whether the candidate is suitable for the control plane. Distribute managers across failure domains where your infrastructure supports that. A manager is also a worker by default, so it may receive service tasks unless you deliberately drain it.

4. Promote one or more workers

This is the state-changing step. It requires a swarm manager, but normally does not require sudo: Docker client access is governed by the daemon socket and your user permissions. Use the exact node names or IDs selected in the previous step:

$ docker node promote app-worker-1 app-worker-2
Node app-worker-1 promoted to a manager in the swarm.
Node app-worker-2 promoted to a manager in the swarm.

The command accepts one or more nodes. It changes their swarm role; it does not deploy a service, copy application data, or move running containers to another machine. The command is a convenience form of docker node update --role manager.

5. Verify the new manager roles

Run the listing again and look for Reachable or another manager status on each promoted node:

$ docker node ls
ID                            HOSTNAME       STATUS    AVAILABILITY   MANAGER STATUS
u1...                         swarm-manager  Ready     Active          Leader
v2...                         app-worker-1   Ready     Active          Reachable
w3...                         app-worker-2   Ready     Active          Reachable

A manager with Reachable is participating in Raft and can become leader if the current leader fails. Confirm a particular node independently when needed:

$ docker node inspect app-worker-1 --pretty
Manager Status:
 Address:               192.0.2.21:2377
 Raft Status:           Reachable
 Leader:                No

The node's availability is still separate from its role. Active permits task scheduling; Drain prevents new tasks and causes existing tasks to be rescheduled. If this machine should run management traffic only, draining it is a separate, service-affecting decision:

$ docker node update --availability drain app-worker-1
app-worker-1

6. Undo an unwanted promotion

If you promoted the wrong node, or the manager count is no longer appropriate, demote it from a manager. This is another cluster change, so check quorum before doing it. The demotion command is the reverse convenience operation:

$ docker node demote app-worker-1
Manager app-worker-1 demoted in the swarm.
$ docker node ls --format '{{.Hostname}}\t{{.ManagerStatus}}'
swarm-manager  Leader
app-worker-1

Demotion returns the node to worker status. It does not remove the node from the swarm and it does not delete its containers. If you also drained the node and want it eligible for tasks again, restore availability separately:

$ docker node update --availability active app-worker-1
app-worker-1

Common errors

• "This node is not a swarm manager": use a Docker context connected to a manager. docker node management commands are not worker commands.
• "This node is not part of a swarm": check docker info and the selected context. Do not run docker swarm init unless creating a new swarm is genuinely intended.
• The target is already a manager: confirm with docker node ls; no promotion is needed.
• The new manager is unavailable: inspect it with docker node inspect NODE --pretty and check network reachability between manager addresses. Do not repeatedly promote and demote while quorum is unstable.
• Services are unexpectedly scheduled on a manager: managers are workers by default. Use docker node update --availability drain NODE only after checking that other nodes can carry the tasks.