Effective orchestration requires visibility into the state of your infrastructure and applications. The docker node ls and docker service ls commands provide essential status information, enabling you to monitor health, troubleshoot issues, and make informed operational decisions.
Understanding Status Commands
Status commands give you snapshots of your cluster's current state. They answer fundamental questions: What hosts are available? What services are running? How many tasks are active? Are there any problems?
These commands are your first line of observation, the starting point for both routine monitoring and incident response. Mastering them is essential for effective cluster management.
The docker node ls Command
The docker node ls command lists all hosts in your cluster, showing their status, availability, and roles. This command provides a high-level view of your infrastructure.
Basic Usage
The simplest invocation lists all hosts:
docker node ls
This produces output showing host IDs, hostnames, status, availability, and manager status. For example:
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS abc123xyz789 * manager1 Ready Active Leader def456uvw012 manager2 Ready Active Reachable ghi789rst345 worker1 Ready Active jkl012mno678 worker2 Ready Active
Output Columns
ID
Each host has a unique identifier. This ID is used in commands that target specific hosts. The asterisk (*) marks the host you're currently connected to.
Hostname
The hostname is the human-readable name assigned to the host. This is typically the system hostname and makes it easier to identify hosts than using IDs alone.
Status
The status column indicates whether the orchestrator can communicate with the host. Common values include:
- Ready: The host is operational and communicating normally
- Down: The host is not responding to cluster communications
- Unknown: The host's status cannot be determined
A Ready status doesn't guarantee the host is functioning perfectly, only that it's responsive to cluster control plane communications.
Availability
Availability indicates whether the host can receive task assignments:
- Active: The host is accepting new task assignments
- Pause: The host retains existing tasks but receives no new assignments
- Drain: The host is being emptied of tasks and receives no new assignments
Administrators change availability to control workload placement, particularly during maintenance or troubleshooting.
Manager Status
This column shows manager-specific status information:
- Leader: This manager is the current cluster leader, making consensus decisions
- Reachable: This manager is participating in consensus but is not the leader
- Unreachable: This manager has lost connection to other managers
- (blank): The host is not a manager
Filtering Node Lists
The --filter option narrows the node list to hosts matching specific criteria:
docker node ls --filter role=manager docker node ls --filter "node.label=environment=production"
Filters help you focus on relevant hosts when managing large clusters. Multiple filters can be combined, and hosts must match all specified filters to appear in results.
Formatting Output
The --format option customizes output using Go templates:
docker node ls --format "{{.Hostname}}: {{.Status}}"
docker node ls --format "table {{.Hostname}}\t{{.ManagerStatus}}\t{{.Status}}"
Custom formatting is useful for scripting or when you need specific information without extraneous details.
Quiet Mode
The -q or --quiet flag outputs only host IDs, one per line:
docker node ls -q
This format is perfect for scripting, allowing you to pipe host IDs to other commands.
The docker service ls Command
The docker service ls command lists all services, showing their current state and configuration. This provides visibility into your applications running on the cluster.
Basic Usage
List all services with:
docker service ls
Typical output shows:
ID NAME MODE REPLICAS IMAGE PORTS a1b2c3d4e5f6 web replicated 3/3 nginx:latest *:80->80/tcp g7h8i9j0k1l2 api replicated 5/5 api:v2.1 *:8080->8080/tcp m3n4o5p6q7r8 worker replicated 2/3 worker:latest s9t0u1v2w3x4 monitor global 4 monitor:1.0
Output Columns
ID
The service ID uniquely identifies each service. Like host IDs, these are used when you need to reference a specific service in commands.
Name
The service name is the human-readable identifier you assigned when creating the service. Names within a cluster must be unique.
Mode
The mode indicates the service type:
- replicated: The service runs a specific number of task replicas
- global: The service runs one task on every qualifying host
Mode fundamentally affects how the service behaves and is managed.
Replicas
For replicated services, this shows actual versus desired task counts in the format "RUNNING/DESIRED". For example, "3/5" means 3 tasks are currently running, but 5 are desired.
For global services, this shows the total number of running tasks.
Discrepancies between running and desired counts indicate problems or ongoing changes. A service showing "2/5" may have tasks pending, failing to start, or being created.
Image
The image column shows which container image the service uses. This is crucial for identifying what version of an application is deployed.
Ports
Published ports appear in this column. The format shows the published port, protocol, and target port (e.g., "*:80->80/tcp").
An asterisk (*) indicates the port is published on all hosts via the ingress routing mesh. If no ports are published, this column is empty.
Filtering Service Lists
Like host lists, service lists can be filtered:
docker service ls --filter name=web docker service ls --filter mode=global docker service ls --filter label=environment=production
Filters help manage large numbers of services by showing only those matching your criteria.
Formatting Service Output
Custom formatting provides precise control over displayed information:
docker service ls --format "{{.Name}}: {{.Replicas}}"
docker service ls --format "table {{.Name}}\t{{.Image}}\t{{.Replicas}}"
Quiet Mode
Output only service IDs with -q:
docker service ls -q
Combining Status Commands
These commands are often used together to build a complete picture of cluster state. You might check hosts to verify infrastructure health, then check services to understand application status.
Typical Inspection Workflow
A common workflow starts with checking host status to ensure infrastructure is healthy. If hosts show problems, investigate those before checking services—service issues often stem from host problems.
Once hosts are verified healthy, check service status. Identify services with mismatched replica counts or other anomalies, then drill deeper into specific services.
Cross-Referencing Information
Information from host and service listings helps you understand relationships. If a host is Down, you can anticipate that services may show fewer running replicas. If services show pending tasks, checking host availability and resource utilization helps identify the cause.
Interpreting Replica Counts
The replica count format "X/Y" requires careful interpretation. The numbers represent current state versus desired state, but what "current state" means is nuanced.
Running vs Desired
If all tasks are running and healthy, current equals desired: "5/5". This indicates the service is in the desired state.
Scaling in Progress
When scaling up, you might see "3/5" as new tasks are being created and started. This is temporary and should resolve to "5/5" once new tasks are running.
When scaling down, you might briefly see "7/5" as excess tasks are being stopped and removed.
Failed or Pending Tasks
If tasks fail to start or cannot be scheduled, the current count may remain below desired: "3/5" persistently. This indicates a problem requiring investigation.
Task State Complexity
The current count includes tasks in various states: starting, running, and shutting down. The number doesn't distinguish between these states, which is why additional inspection commands are often needed.
Status Command Frequency
How often you check status depends on your operational needs and automation:
Manual Monitoring
For manual monitoring, checking status periodically (every few minutes to hours) depending on stability and criticality is common. After changes or during incidents, you might check continuously.
Automated Monitoring
Automated systems can check status very frequently, potentially multiple times per second. This enables rapid detection of problems and quick response.
However, excessive status checking can burden the cluster. Design monitoring systems to balance responsiveness with cluster load.
Status Changes Over Time
Status is a snapshot, not a history. Commands show current state but don't reveal how you got there. Understanding typical state transitions helps interpret what you see:
Host State Transitions
Hosts normally remain Ready and Active. Transitions to Down indicate connectivity or host failures. Transitions to Pause or Drain are deliberate administrative actions.
A host flapping between Ready and Down indicates instability—network issues, resource exhaustion, or host-level problems.
Service State Transitions
Services typically maintain stable replica counts. Changes occur during scaling, updates, or when tasks fail and are recreated.
A service with constantly fluctuating replica counts suggests tasks are failing and being restarted repeatedly—a sign of application or configuration problems.
Using Status for Troubleshooting
Status commands are often the first step in troubleshooting. They quickly reveal whether problems are infrastructure-related (host issues) or application-related (service issues).
Identifying Host Problems
If hosts show Down status or have changed availability, investigate those hosts directly. Check logs, resource utilization, and network connectivity.
Identifying Service Problems
If services show mismatched replica counts or other anomalies, drill into specific service details to understand why. Task-level inspection reveals specific failure reasons.
Correlating Issues
Look for correlations between host and service problems. Multiple services showing issues simultaneously might indicate a common cause—perhaps a host failure affecting multiple services.
Advanced Filtering Techniques
Label-Based Filtering
Labels enable sophisticated filtering. If you've labeled hosts and services consistently, you can quickly find all resources related to specific applications, environments, or teams:
docker node ls --filter "node.label=datacenter=east" docker service ls --filter "label=team=backend"
Combining Multiple Filters
Multiple filters create AND conditions—resources must match all filters:
docker service ls --filter mode=replicated --filter "label=env=prod"
This shows only replicated services in production.
Filter by Name Pattern
The name filter supports patterns, allowing you to find services with names matching a prefix or pattern:
docker service ls --filter "name=web"
This shows all services with "web" in their name.
Output Formatting Use Cases
Human-Readable Tables
Default output is designed for human readability, providing aligned columns and clear headers. This format works well for interactive use and quick manual inspection.
Machine-Readable Output
For scripting and automation, custom formats or quiet mode provide predictable, parseable output. JSON format is particularly useful for complex automation:
docker service ls --format '{{json .}}'
This outputs each service as a JSON object, easily parsed by scripts.
Custom Reports
Format strings let you create custom reports showing exactly the information you need:
docker service ls --format "Service: {{.Name}}\nReplicas: {{.Replicas}}\nImage: {{.Image}}\n"
Limitations of Status Commands
These commands show current state but have limitations:
No Historical Data
Commands don't show when state changed or what the previous state was. For historical analysis, you need logging or monitoring systems that collect and retain status over time.
No Detailed Task Information
Service listings show aggregate replica counts but not individual task details. For task-level information, additional commands are required.
No Performance Metrics
Status commands show operational state (running, stopped, ready) but not performance metrics (CPU usage, memory consumption, response times). Performance monitoring requires separate tools.
Snapshot Nature
By the time you see output, state may have changed. In rapidly changing environments, status commands provide approximate information that's immediately slightly stale.
Best Practices for Status Monitoring
Regular Health Checks
Establish a routine for checking cluster health. Periodic status checks help you understand normal patterns and quickly identify anomalies.
Automate Monitoring
While manual status checks are valuable, automated monitoring provides continuous visibility and alerts. Combine status commands with monitoring platforms for comprehensive observability.
Investigate Anomalies Quickly
When status commands reveal issues—hosts down, mismatched replica counts—investigate immediately. Problems often escalate if left unaddressed.
Document Baseline State
Understand what normal looks like for your cluster. Document expected host counts, typical service replica distributions, and common operational patterns. This baseline helps you recognize when something is wrong.
Use Filtering Effectively
In large clusters with many hosts and services, unfiltered output is overwhelming. Use filters to focus on relevant subsets, making information more actionable.
Scripting with Status Commands
Status commands integrate well into scripts for automation and monitoring:
Checking for Healthy Hosts
#!/bin/bash
down_nodes=$(docker node ls --filter "status=down" -q | wc -l)
if [ $down_nodes -gt 0 ]; then
echo "Warning: $down_nodes nodes are down"
exit 1
fi
Verifying Service Health
#!/bin/bash
for service in $(docker service ls -q); do
replicas=$(docker service ls --filter "id=$service" --format "{{.Replicas}}")
if [[ $replicas != *"/"* ]] || [[ ${replicas%/*} -ne ${replicas#*/} ]]; then
name=$(docker service ls --filter "id=$service" --format "{{.Name}}")
echo "Service $name has mismatched replicas: $replicas"
fi
done
Monitoring Specific Services
#!/bin/bash
critical_services=("web" "api" "database")
for service in "${critical_services[@]}"; do
if ! docker service ls --filter "name=$service" --format "{{.Name}}" | grep -q "$service"; then
echo "Critical service $service not found!"
exit 1
fi
done
Integration with Monitoring Tools
Status commands provide data that can feed into monitoring dashboards and alerting systems:
Metrics Collection
Monitoring agents can periodically execute status commands and parse output to extract metrics. These metrics feed dashboards showing cluster health over time.
Alert Generation
Automated systems can execute status commands, evaluate results against thresholds, and generate alerts when problems are detected.
Health Dashboards
Parse status command output to populate real-time health dashboards showing host status, service health, and replica distributions.
Common Status Patterns
Healthy Cluster
In a healthy cluster, docker node ls shows all hosts Ready and Active. docker service ls shows all services with current replica counts matching desired counts.
Degraded State
During degraded operation, some hosts might be Down or some services might show mismatched replica counts. The cluster continues functioning but at reduced capacity.
Maintenance Mode
During maintenance, you might see hosts with Drain availability as you empty them of tasks before performing maintenance activities.
Update in Progress
During service updates, replica counts might fluctuate as old tasks are stopped and new ones started. This is temporary and normal during updates.
Reading Between the Lines
Status commands show explicit state, but experienced operators learn to read implicit information:
Absence of Expected Services
If you expect certain services to exist but they don't appear in listings, they may have been removed or never created. This could indicate deployment failures or configuration errors.
Unexpected Global Service Task Counts
If a global service shows fewer tasks than there are qualifying hosts, some hosts might be Down or Drain, or placement constraints might be excluding hosts.
Consistent Patterns Across Services
If multiple unrelated services all show the same pattern (e.g., all running 1 fewer replica than desired), this suggests a common cause—perhaps a host failure affecting multiple services.
Operational Workflows
Daily Health Check
Start each day by checking cluster health. Run docker node ls to verify all hosts are up and active. Run docker service ls to verify all services are running desired replica counts.
Pre-Deployment Verification
Before deploying changes, check cluster status to ensure a stable starting point. Verify all hosts are healthy and existing services are running normally.
Post-Deployment Verification
After deployments, check status to verify changes took effect correctly. Ensure services scaled as expected and new services started successfully.
Incident Response
During incidents, status commands provide quick assessment of cluster state. Identify which components are affected and begin drilling down into specific problems.
Status Command Alternatives
While docker node ls and docker service ls are primary status commands, related commands provide complementary information:
Detailed Inspection Commands
Commands like docker node inspect and docker service inspect provide complete detail about specific resources, going far beyond the summary information in list commands.
Task-Level Commands
Commands like docker service ps show individual tasks for a service, revealing details about specific task states and placements.
Log Commands
Log commands provide the output from specific tasks, essential for understanding why tasks fail or behave unexpectedly.
Conclusion
The docker node ls and docker service ls commands are fundamental tools for cluster visibility. They provide quick, actionable information about infrastructure and application state, forming the foundation of effective cluster management.
Mastering these commands—understanding their output, using filters effectively, and knowing when additional investigation is needed—is essential for anyone managing orchestrated applications. They're the starting point for monitoring, troubleshooting, and ensuring your cluster operates reliably.