Safely Change Docker Swarm Node Availability, Labels and Roles

By the end, you will be able to change a Docker Swarm node's scheduling state, metadata or manager role with docker node update, and check that the change took effect. 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 contains the cluster. A normal user can run it only if that user can access the Docker daemon; use sudo when your local daemon socket requires it. The command changes cluster state, so first identify the node and record its current state.

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 available.

2. Inspect the target before changing it.

   docker node inspect --pretty NODE_NAME

   Replace NODE_NAME with a real node name or ID. Save the relevant availability, role and labels somewhere in your change record. This is also your recovery reference. docker node update does not provide a general undo option.

Change whether a node receives tasks

The --availability option accepts active, pause or drain. active permits normal scheduling. pause stops new tasks being assigned but leaves existing tasks in place. drain moves running service tasks away and prevents new assignments. Draining can disrupt workloads, so warn service owners and check capacity first.

docker node update --availability drain NODE_NAME

A successful update normally returns the node ID, although the exact display can vary by CLI release. Verify the state rather than relying on the command's exit status alone:

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

When maintenance is complete, 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 available capacity.

Add or remove node labels

Node labels are Swarm metadata used by placement constraints. They are not labels for the Docker daemon 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 option for each label in a single command. Adding a label with an existing key updates that key, so check the spelling carefully. A service can then use a constraint such as node.labels.region == eu-west, but changing the label does not by itself prove that a service has moved.

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

docker node update --label-rm region NODE_NAME

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

Change a node's manager role

The --role option accepts worker or manager. Promoting a worker increases the number of managers. Demoting a manager removes its manager role, which is 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

Combine changes carefully

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

Do not put a shell placeholder such as NODE_NAME into a production command. Replace it before pressing Enter, and quote values if your shell would interpret their characters.

Common failure points

• Not a manager: the command is intended for a Swarm manager. Check docker info and the current context before debugging the option syntax.
• Wrong cluster: Docker contexts change the daemon endpoint. Run docker context show and docker context ls before a state-changing command.
• Unexpected scheduling: labels affect placement decisions, while availability affects whether the node may receive tasks. Neither option edits a service's constraints.
• Insufficient capacity after drain: inspect service tasks and node capacity before draining. If tasks cannot be placed elsewhere, restore active and investigate the service rather than repeatedly retrying.

For the exact options available on the installed CLI, run:

docker node update --help

Done means

• You changed only the intended node in the intended Docker context.
• The node's availability, labels or role match the approved target state.
• You checked the result with docker node inspect and, for role changes, docker node ls.
• You recorded the previous state so a label, availability or role change can be reversed safely.