Playing with Manager and Node Statuses in Docker Swarm

Introduction – Why Managing Node Statuses in Swarm Matters

In Docker Swarm, nodes are the building blocks of your orchestration cluster. Each node plays a distinct role—either as a manager or a worker—and knowing how to monitor and control their statuses is key to ensuring service reliability, cluster health, and zero-downtime maintenance.

In this guide, you’ll learn:

• The roles and responsibilities of manager vs worker nodes
• How to inspect, promote, demote, and drain nodes
• Best practices for maintaining node availability and cluster stability

Node Roles in Docker Swarm

Docker Swarm nodes operate in one of two roles:

👑 Manager Nodes

• Coordinate the entire swarm
• Schedule services and manage state
• Participate in the Raft consensus to elect a Leader
• Can also run containers (but not recommended in prod)

🔩 Worker Nodes

• Receive tasks from managers and execute them
• Do not participate in scheduling or cluster decisions

Tip: Use odd numbers of manager nodes (3, 5, 7) to maintain quorum and fault tolerance.

Inspecting Nodes with docker node ls

Run this command from a manager node to list all nodes in the swarm:

docker node ls

Key Columns in the Output:

Sample Output:

ID                            HOSTNAME   STATUS  AVAILABILITY  MANAGER STATUS
ehkv3bcimagdese79dn78otj5 *   node-1     Ready   Active        Leader
46aqrk4e473hjbt745z53cr3t     node-2     Ready   Active        Reachable
a5b2m3oghd48m8eu391pefq5u     node-3     Ready   Active        

Managing Node Availability States

You can manually change how a node accepts or rejects tasks:

Availability Modes:

• Active – Accepts new tasks (default)
• ⏸️ Pause – Keeps running tasks but prevents scheduling new ones
• Drain – Migrates running tasks elsewhere; blocks new tasks

Update Node Availability:

docker node update --availability drain <NODE-ID>
docker node update --availability pause <NODE-ID>
docker node update --availability active <NODE-ID>

Use Case: Drain a node before performing maintenance or decommissioning it.

🩺 Checking Manager Health and Leadership

Identify the Leader:

docker node ls

Look for Leader in the MANAGER STATUS column.

Inspect Manager Reachability:

docker node inspect <NODE-ID> --format "{{ .ManagerStatus.Reachability }}"

Reachability values:

• reachable
• unreachable
• unknown

Handling Manager Node Failures

If a manager becomes unresponsive:

Recommended Actions:

• Restart Docker: systemctl restart docker
• Reboot the machine if necessary
• Promote another node if quorum is lost
• Remove the failed manager: docker node demote <NODE-ID> docker node rm <NODE-ID>

Keep at least 3 managers (odd number) to preserve Raft quorum and resilience.

Promoting and Demoting Nodes

Promote Worker to Manager:

docker node promote <NODE-ID>

Demote Manager to Worker:

docker node demote <NODE-ID>

Joining New Nodes to the Swarm

Get Join Token (from manager):

docker swarm join-token manager
docker swarm join-token worker

Use Join Command (on new node):

docker swarm join --token <TOKEN> <MANAGER-IP>:2377

Monitoring and Maintaining Swarm Nodes

Swarm Health Checklist:

• Run docker node ls regularly
• Use docker node inspect <NODE-ID> for in-depth info
• Maintain quorum by keeping a majority of managers online
• Distribute managers across zones for redundancy
• Drain managers not meant to run services

Summary – Recap & Takeaways

Mastering node and manager operations in Docker Swarm helps you create fault-tolerant, maintainable, and production-ready clusters. Whether you’re scaling out or debugging failures, controlling node states is essential.

Key Takeaways:

• Use docker node ls to track health and roles
• Actively manage node availability using drain/pause/active modes
• Promote/demote nodes as needed to maintain quorum
• Always ensure an odd number of managers for fault tolerance
• Use drain before performing node maintenance

Real-World Relevance: Effective node status management ensures cluster uptime, smooth updates, and safe failover handling in real deployments.

FAQ: Manager and Node Statuses in Docker Swarm

How do I find the current leader manager?

Use docker node ls and check for Leader under the MANAGER STATUS column.

What does Drain mode do?

Prevents the node from receiving new tasks and migrates existing ones to other active nodes.

How many manager nodes should I run?

Always use an odd number (3, 5, or 7) to maintain quorum and support failover scenarios.

What should I do if a manager becomes unreachable?

Try restarting Docker or the node. If it remains unreachable, demote and remove it to maintain cluster stability.

Can manager nodes run containers?

Yes, but in critical environments, it’s a best practice to drain managers so they only handle orchestration.

Call to Action – Practice Makes Perfect!

Ready to get hands-on?

Try these in your own swarm setup:

• Run docker node ls to inspect nodes
• Change availability with docker node update
• Promote and demote roles using docker node promote/demote
• Add/remove nodes using docker swarm join and docker node rm

Start by draining a manager node, observe behavior, and restore it. Practice failover handling before it’s needed in production!