How to use docker node ps command to list tasks

Introduction

In this lab, you will learn how to use the docker node ps command to list and filter tasks running on a Docker Swarm node. You will begin by initializing a Docker Swarm and creating a simple service to generate tasks.

You will then explore how to list all tasks on a specific node, filter tasks based on their name and desired state, and finally, format the output of the task list for better readability and information extraction. This hands-on experience will provide you with practical skills for monitoring and managing tasks within your Docker Swarm cluster.

Skills Graph

List all tasks on a node

In this step, you will learn how to list all tasks running on a Docker Swarm node. Docker Swarm is a container orchestration tool that allows you to manage a cluster of Docker nodes. A task is a running instance of a service.

Before listing tasks, we need to have a running Docker Swarm service. For this lab, we will use a simple nginx service.

First, let's initialize a Docker Swarm on this node.

docker swarm init

You should see output indicating that the swarm has been initialized and providing a join token.

Now, let's create a simple service named my-nginx-service using the nginx image. We will pull the nginx image first to ensure it's available.

docker pull nginx:latest
docker service create --name my-nginx-service --replicas 1 nginx

The docker service create command creates a new service with one replica (one task). Docker will automatically pull the nginx image if it's not already present, but we explicitly pulled it beforehand.

After the service is created, Docker will start a task for this service on one of the nodes in the swarm (in this case, the current node).

To list all tasks running on the node, you can use the docker node ps command followed by the node ID or hostname. Since we are on the manager node where the service was created, we can use the node ID of this node.

To find the node ID, you can use the docker node ls command.

docker node ls

This command will list all nodes in the swarm. The output will show the node ID, hostname, status, availability, and manager status. Copy the node ID of the current node (the one with Leader under MANAGER STATUS).

Now, use the docker node ps command with the node ID you copied to list the tasks on that node. Replace <node_id> with the actual node ID.

docker node ps <node_id>

This command will display a list of tasks running on the specified node, including the task ID, service name, image, node, desired state, current state, and error. You should see the my-nginx-service.1 task listed with a state of Running.

Alternatively, you can list all tasks in the swarm using the docker task ls command. This command is useful for seeing tasks across all nodes in the swarm.

docker task ls

This command will show similar information to docker node ps, but it lists tasks from all nodes in the swarm. Since we only have one node and one task, the output will be similar to docker node ps.

In this step, you learned how to list tasks on a specific node using docker node ps and list all tasks in the swarm using docker task ls.

Filter tasks by name

In this step, you will learn how to filter the list of tasks by their name. This is useful when you have many services and tasks running and you only want to see the tasks related to a specific service.

We will continue using the my-nginx-service created in the previous step.

To filter tasks by name, you can use the --filter flag with the name key in the docker task ls command. The syntax is --filter name=<service_name>.

Let's filter the tasks to only show those belonging to the my-nginx-service.

docker task ls --filter name=my-nginx-service

This command will list only the tasks whose service name is my-nginx-service. You should see the my-nginx-service.1 task listed.

You can also filter by the full task name, which includes the service name and the task number (e.g., my-nginx-service.1).

docker task ls --filter name=my-nginx-service.1

This command will specifically list the task with the exact name my-nginx-service.1.

If you had multiple services running, filtering by service name would show all tasks for that service. For example, if you had another service named my-app-service, running docker task ls --filter name=my-app-service would show all tasks for my-app-service.

Filtering by name is a powerful way to narrow down the output of the docker task ls command and focus on the tasks you are interested in.

Filter tasks by desired state

In this step, you will learn how to filter the list of tasks based on their desired state. The desired state of a task is the state that the Docker Swarm manager wants the task to be in (e.g., Running, Shutdown, Accepted).

We will continue using the my-nginx-service created in the previous steps. Currently, the desired state of the task for this service is Running.

To filter tasks by desired state, you can use the --filter flag with the desired-state key in the docker task ls command. The syntax is --filter desired-state=<state>.

Let's filter the tasks to only show those with a desired state of Running.

docker task ls --filter desired-state=Running

This command will list only the tasks whose desired state is Running. You should see the my-nginx-service.1 task listed.

Now, let's scale down the service to 0 replicas. This will change the desired state of the existing task to Shutdown.

docker service scale my-nginx-service=0

After scaling down, the task will eventually transition to a Shutdown state. It might take a few moments for the state to update.

Now, let's filter the tasks to show those with a desired state of Shutdown.

docker task ls --filter desired-state=Shutdown

You should now see the my-nginx-service.1 task listed with a desired state of Shutdown.

Other possible desired states include Accepted (when a task is accepted by a worker node but not yet running) and Failed (if a task failed to start).

Filtering by desired state is useful for monitoring the status of your services and identifying tasks that are not in the expected state.

Format the output of tasks

In this step, you will learn how to format the output of the docker task ls command to display specific information in a custom format. This is useful for scripting or generating reports.

We will continue using the my-nginx-service and its task.

To format the output, you can use the --format flag with a Go template string. The template string allows you to specify which fields to display and how to format them.

Let's display only the task ID, service name, and current state of the tasks.

docker task ls --format "{{.ID}}\t{{.Service}}\t{{.CurrentState}}"

In this command:

• {{.ID}} refers to the task ID.
• {{.Service}} refers to the service name.
• {{.CurrentState}} refers to the current state of the task.
• \t is used to insert a tab character between the fields for better readability.

The output will show the task ID, service name, and current state for each task.

You can also use the table format to display the output in a table with specific columns.

docker task ls --format "table {{.ID}}\t{{.Service}}\t{{.CurrentState}}\t{{.Node}}"

This command will display a table with columns for Task ID, Service, Current State, and Node.

To see all available fields that you can use in the format string, you can inspect a task using the docker task inspect command and look at the JSON output. However, some common fields include:

• .ID: Task ID
• .Service: Service name
• .Image: Image name
• .Node: Node hostname
• .DesiredState: Desired state of the task
• .CurrentState: Current state of the task
• .Error: Error message if the task failed
• .CreatedAt: Timestamp when the task was created
• .UpdatedAt: Timestamp when the task was last updated

Let's display the task ID, image, and the node it's running on.

docker task ls --format "{{.ID}}\t{{.Image}}\t{{.Node}}"

This command will show the task ID, the image used by the task, and the node where the task is running.

Formatting the output allows you to customize the information displayed by docker task ls to suit your needs, whether for quick inspection or for use in scripts.

Finally, let's clean up the service we created.

docker service rm my-nginx-service

This command will remove the service and its associated tasks.

Summary

In this lab, you learned how to use the docker node ps command to list tasks running on a specific Docker Swarm node. You began by initializing a Docker Swarm and creating a simple nginx service with one replica. You then used docker node ls to identify the node ID of the current manager node and subsequently used docker node ps <node_id> to display all tasks running on that node.

The lab also covered how to refine the output of docker node ps by filtering tasks based on their name and desired state, and how to format the output for better readability. These steps demonstrate the flexibility of the docker node ps command for monitoring and managing tasks within a Docker Swarm cluster.