How to use docker node ls command to list swarm nodes

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.

Skills Graph

%%%%{init: {'theme':'neutral'}}%%%% flowchart RL docker(("Docker")) -.-> docker/ContainerOperationsGroup(["Container Operations"]) docker/ContainerOperationsGroup -.-> docker/ls("List Containers") docker/ContainerOperationsGroup -.-> docker/ps("List Running Containers") docker/ContainerOperationsGroup -.-> docker/inspect("Inspect Container") subgraph Lab Skills docker/ls -.-> lab-555182{{"How to use docker node ls command to list swarm nodes"}} docker/ps -.-> lab-555182{{"How to use docker node ls command to list swarm nodes"}} docker/inspect -.-> lab-555182{{"How to use docker node ls command to list swarm nodes"}} end

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.