Change a Docker Swarm Node with docker node update

docker node update is how you drain a Swarm node for maintenance, tag it with a placement label, or promote a worker to manager. It changes a node's scheduling state, metadata or manager role, and lets you check the change actually took. The examples use Docker Community Edition CLI 29.8.1, installed here as package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Allow about 10 minutes if you already have a Swarm and a change window.

Before you start

This is a Swarm cluster administration command. Run it from a Swarm manager, against the Docker context that holds the cluster. A normal user can run it only if that user can reach the Docker daemon; use sudo when your local socket requires it. Because it changes cluster state, identify the node and record its current state before you touch anything.

1. Find and inspect the node

1. Check the CLI and list the nodes.

   docker version --format '{{.Client.Version}}'
   docker node ls

   Expected version output on the reference machine is:

   29.8.1

   The node list gives you the node ID or hostname to pass as NODE. A manager node shows a manager status; do not guess a name when several clusters or contexts are in play.

2. Inspect the target before changing it.

   docker node inspect --pretty NODE_NAME

   Swap in a real node name or ID for NODE_NAME. Save the relevant availability, role and labels somewhere in your change record: this is also your recovery reference, since docker node update has no general undo option.

2. Change whether a node receives tasks

The --availability option takes three values:

• active permits normal scheduling.
• pause stops new tasks being assigned but leaves existing tasks running.
• drain moves running service tasks away and blocks new assignments.

docker node update --availability drain NODE_NAME

A successful update normally returns the node ID, though the exact display can vary by CLI release. Verify the state rather than trusting the exit status alone:

docker node inspect --format '{{.Description.Hostname}} availability={{.Spec.Availability}}' NODE_NAME

When maintenance is done, restore scheduling with:

docker node update --availability active NODE_NAME

Restoring active does not automatically put tasks back on that node. The Swarm scheduler decides where tasks run from the current service specification and whatever capacity is available.

3. Add or remove node labels

Node labels are Swarm metadata used by placement constraints. They are not Docker daemon labels and do not alter containers already running. Add a key with a value when the value matters:

docker node update --label-add region=eu-west NODE_NAME

You can also add a key without a value, as shown in the Docker documentation:

docker node update --label-add storage-ssd NODE_NAME

Use one --label-add per label in a single command. Adding a label with an existing key overwrites that key, so check the spelling carefully. A service can then use a constraint such as node.labels.region == eu-west, though setting the label does not by itself prove a service has moved.

Remove a label only after checking which services depend on it:

docker node update --label-rm region NODE_NAME

This removes the label if it exists. If a service can no longer satisfy a placement constraint, its tasks may sit pending. Recovery is the inverse: add the key and its previous value back, then inspect the affected service.

4. Change a node's manager role

The --role option accepts worker or manager. Promoting a worker adds to the manager count. Demoting a manager strips its manager role, a control-plane change rather than a scheduling preference.

docker node ls

Promote a suitable worker with:

docker node update --role manager NODE_NAME

Demote a manager only during an approved change:

docker node update --role worker NODE_NAME

Verify both the node and the wider quorum after either change:

docker node inspect --format '{{.Description.Hostname}} role={{.Spec.Role}}' NODE_NAME
docker node ls

5. Combine changes with care

The options can be supplied together, but separate commands are easier to review and undo. If you do combine them, put the complete intended state in one change record:

docker node update   --availability pause   --label-add maintenance-window=2026-09   NODE_NAME

Never leave a shell placeholder such as NODE_NAME in a production command. Replace it before pressing Enter, and quote values if your shell would otherwise mangle them.

Common traps

• Not a manager. The command only works from a Swarm manager. Check docker info and the current context before you start debugging option syntax.
• Wrong cluster. Docker contexts change the daemon endpoint. Run docker context show and docker context ls before any state-changing command.
• Unexpected scheduling. Labels affect placement decisions; availability affects whether a node can receive tasks at all. Neither one edits a service's constraints.
• Insufficient capacity after a drain. Check service tasks and node capacity before draining. If tasks cannot land elsewhere, restore active and investigate the service instead of retrying the drain.

For the exact options on your installed CLI, run:

docker node update --help