Introduction

In Docker Swarm, node labels are part of the scheduler contract. They are commonly used for placement rules such as GPU availability, region, storage class, or workload tier. If the labels are wrong or missing, services can remain pending or land on the wrong machines.

The practical task is not only "show me the labels," but "show me the labels in a format I can actually reason about." That usually means listing nodes from a manager, inspecting their label maps, and then checking those values against service constraints.

Start From a Manager Node

Swarm node metadata is managed by manager nodes, so label inspection commands should be run there. The first quick inventory is:

docker node ls

That shows the node IDs and hostnames, but not the labels. To inspect a single node's labels:

docker node inspect node-1 --format '{{json .Spec.Labels}}'

The Go template prints the label map as JSON, which is much easier to read than the full inspect output.

List Labels for Every Node

For cluster-wide inspection, loop over the node IDs and print each hostname with its labels:

docker node ls -q | while read -r id; do
  docker node inspect "$id" --format '{{.Description.Hostname}} {{json .Spec.Labels}}'
done

That gives output shaped like:

manager-1 {"zone":"east","gpu":"true"}
worker-1 {"zone":"west"}
worker-2 {"zone":"east","disk":"ssd"}

This is a good baseline for audits, cluster reviews, and troubleshooting placement failures.

Filter Nodes by a Specific Label

In real operations you often care about one label at a time. For example, show whether each node has gpu=true:

docker node ls -q | while read -r id; do
  docker node inspect "$id" --format '{{.Description.Hostname}} {{index .Spec.Labels "gpu"}}'
done

To keep only matching nodes:

docker node ls -q | while read -r id; do
  docker node inspect "$id" --format '{{.Description.Hostname}} {{index .Spec.Labels "gpu"}}'
done | grep ' true$'

The same pattern works for labels such as zone, tier, disk, or any team-specific placement key.

Validate Labels Against Service Constraints

Listing labels is only half the story. If a service is pinned to node.labels.zone == east, you also need to confirm that such nodes actually exist:

docker service inspect my-service --format '{{json .Spec.TaskTemplate.Placement.Constraints}}'

A typical constraint might look like this:

["node.labels.zone == east"]

If no node carries that label, tasks will stay pending and the service will appear unhealthy even though the image and network are fine.

This is why label inventory and service constraints should be reviewed together, especially before rollouts.

Update Labels Deliberately

Labels can be added or removed with docker node update:

docker node update --label-add zone=east worker-2
docker node update --label-rm gpu worker-2

After changing a label, verify the new state and then check affected services:

docker service ps my-service

For stateful or pinned workloads, label changes can trigger rescheduling behavior, so do not treat them like harmless metadata edits.

Common Pitfalls

The most common mistake is running label inspection from a worker node and expecting manager-level control data to be available. Swarm metadata lives with the managers.

Another common issue is inventing labels ad hoc across environments. If one cluster uses zone=east and another uses region=east, the service constraints stop being portable.

People also update labels without checking existing placement rules. That can strand services or move them unexpectedly.

Finally, do not treat labels as comments. In Swarm they are scheduling input, so they should be versioned, reviewed, and kept consistent like other deployment configuration.

Summary

• Inspect Swarm node labels from a manager node.
• Use docker node inspect with Go templates to print label maps cleanly.
• Filter by specific label keys when debugging placement behavior.
• Check service placement constraints against the actual node label inventory.
• Treat label changes as scheduler-impacting configuration, not as harmless notes.