Introduction
In this lab, you will learn how to effectively use the docker node ls command to manage and inspect nodes within a Docker Swarm. We will begin by initializing a Docker Swarm and listing all the nodes.
Subsequently, you will explore various filtering options to narrow down the node list based on criteria such as node ID, role (manager or worker), and custom node labels. Finally, you will learn how to format the output to display only the specific information you need, enhancing your ability to quickly retrieve relevant node details.
List all nodes in the swarm
In this step, we will learn how to list all nodes in a Docker Swarm. Before we can list the nodes, we need to initialize a Docker Swarm.
First, let's initialize the swarm on the current machine. This machine will become the manager node.
docker swarm init
You should see output indicating that the swarm has been initialized and providing a command to join other nodes to the swarm.
Now that the swarm is initialized, we can list the nodes in the swarm using the docker node ls command.
docker node ls
This command will display a table with information about the nodes in the swarm, including their ID, hostname, status, availability, manager status, and engine version. Since we only have one node (the manager node we just initialized), you will see a single entry in the list.
The output will look similar to this:
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
<node_id> * <hostname> Ready Active Leader 20.10.21
The * next to the ID indicates that this is the current node you are running the command on. The MANAGER STATUS column shows that this node is the Leader of the swarm.
Filter nodes by ID
In this step, we will learn how to filter the list of nodes in a Docker Swarm based on their ID. This is useful when you have many nodes and want to view information about a specific one.
First, let's list all nodes again to get the ID of the manager node.
docker node ls
Identify the ID of the node from the output. It will be a long string of characters.
Now, we can use the --filter flag with the id key to filter the output and show only the node with the specified ID. Replace <node_id> with the actual ID you obtained from the previous command.
docker node ls --filter id=<node_id>
This command will display only the row corresponding to the node with the given ID. This is a simple way to quickly find information about a specific node when you know its ID.
For example, if your node ID is 24ifihg345h345h345h345h34, the command would be:
docker node ls --filter id=24ifihg345h345h345h345h34
The output will be the same as the single line for your manager node from the docker node ls command in the previous step.
Filter nodes by role
In this step, we will learn how to filter the list of nodes in a Docker Swarm based on their role. In a Docker Swarm, nodes can have one of two roles: manager or worker. Manager nodes manage the swarm, while worker nodes run the services.
Since we only have one node in our swarm currently, and it's the manager node, let's filter to show only manager nodes. We use the --filter flag with the role key and the value manager.
docker node ls --filter role=manager
This command will display only the nodes that have the manager role. In our current setup, this will show the same single node as before.
If you had worker nodes in your swarm, you could filter to show only worker nodes using:
docker node ls --filter role=worker
Currently, this command will not show any output because there are no worker nodes in the swarm.
Understanding how to filter by role is important for managing larger swarms with multiple manager and worker nodes.
Filter nodes by node label
In this step, we will learn how to filter nodes based on labels assigned to them. Node labels are key-value pairs that you can attach to nodes for organizational purposes or to control service placement.
First, let's add a label to our manager node. We'll add a label location=datacenter1. To do this, we use the docker node update command followed by the node ID and the --label-add flag.
Get the node ID again using docker node ls -q:
NODE_ID=$(docker node ls -q)
echo $NODE_ID
Now, update the node with the label:
docker node update --label-add location=datacenter1 $NODE_ID
You should see output confirming the node update.
To verify the label has been added, you can inspect the node:
docker node inspect $NODE_ID
Look for the Labels section in the output. You should see "location": "datacenter1".
Now, let's filter the nodes based on this label. We use the --filter flag with the label key and the label in the format key=value.
docker node ls --filter label=location=datacenter1
This command will display only the nodes that have the label location with the value datacenter1. In our case, it will show our manager node.
You can also filter for nodes that have a specific label key, regardless of its value, by just providing the key:
docker node ls --filter label=location
This will show all nodes that have the location label defined.
Format the output to display specific information
In this step, we will learn how to format the output of the docker node ls command to display only the information we are interested in. This is useful for scripting or when you only need a quick view of specific details.
We use the --format flag to specify the output format. You can use Go template syntax to define the desired output. Common fields you can access include .ID, .Hostname, .Status, .Availability, .ManagerStatus, and .EngineVersion.
Let's display only the node ID and hostname.
docker node ls --format "{{.ID}}\t{{.Hostname}}"
The {{.ID}} and {{.Hostname}} are placeholders for the node's ID and hostname, respectively. The \t inserts a tab character for separation.
The output will look like this:
<node_id> <hostname>
Now, let's display the hostname and the manager status.
docker node ls --format "Hostname: {{.Hostname}}, Manager Status: {{.ManagerStatus}}"
This will output:
Hostname: <hostname>, Manager Status: Leader
You can combine filtering and formatting. For example, let's filter for manager nodes and display their ID and hostname.
docker node ls --filter role=manager --format "{{.ID}}\t{{.Hostname}}"
This command first filters the nodes to include only managers and then formats the output to show their ID and hostname.
Using the --format flag provides flexibility in how you view and process information about your Docker Swarm nodes.
Summary
In this lab, we learned how to use the docker node ls command to manage and view information about nodes in a Docker Swarm. We started by initializing a Docker Swarm on the current machine, making it the manager node. Then, we used docker node ls to list all nodes in the swarm, observing the default output which includes ID, hostname, status, availability, manager status, and engine version.
We then explored how to filter the node list using the --filter flag. Specifically, we learned how to filter nodes based on their unique ID, allowing us to quickly locate and view information about a specific node within a larger swarm. The lab also covers filtering by role and node label, and formatting the output to display only specific information, although the provided content only details filtering by ID.
