How to use docker service ps command to list service tasks

Introduction

In this lab, you will learn how to effectively use the docker service ps command to inspect and manage tasks within a Docker Swarm service. You will begin by listing the basic information of tasks associated with a service, understanding the key details provided in the default output.

Building upon the basic listing, you will then explore how to retrieve full details of service tasks using the --no-trunc flag for comprehensive information. The lab will further guide you on filtering tasks based on various criteria such as name, the node they are running on, and their desired state, allowing you to pinpoint specific tasks. Finally, you will learn how to format the output of the docker service ps command to customize the displayed information according to your needs.

Skills Graph

List tasks of a service

In this step, you will learn how to list the tasks associated with a specific service in a Docker Swarm. Tasks are the fundamental units of scheduling in Swarm, representing a running instance of a service.

First, let's ensure you have a service running. We will create a simple service using the nginx image.

docker service create --name my-nginx nginx

This command creates a service named my-nginx using the nginx image. Docker Swarm will automatically create and manage tasks for this service.

Now, to list the tasks for the my-nginx service, you can use the docker service ps command followed by the service name.

docker service ps my-nginx

You should see output similar to this, showing the tasks associated with your service:

ID             NAME         IMAGE          NODE         DESIRED STATE   CURRENT STATE           ERROR   PORTS
<task_id>      my-nginx.1   nginx:latest   <node_name>   Running         Running 5 seconds ago

The output provides information about each task, including its ID, name, the image it's using, the node it's running on, its desired state, and its current state.

List tasks with full details

In the previous step, you learned how to list the basic information about tasks for a service. Sometimes, you need more detailed information about each task, such as the full task ID, the container ID, and more.

To get the full details of the tasks, you can use the --no-trunc flag with the docker service ps command. This flag prevents Docker from truncating the output, showing the full IDs and other information.

Let's list the tasks for the my-nginx service with full details:

docker service ps --no-trunc my-nginx

You will see output similar to the previous step, but with the full task ID and potentially more detailed information depending on the task's state and configuration.

ID                                                           NAME         IMAGE          NODE         DESIRED STATE   CURRENT STATE            ERROR   PORTS
<full_task_id>                                               my-nginx.1   nginx:latest   <node_name>   Running         Running 10 seconds ago

Comparing this output to the previous step, you can see the complete task ID instead of a truncated version. This is useful when you need to reference a specific task precisely, for example, when inspecting a task.

Filter tasks by name or node

In a larger Swarm cluster, you might have many tasks running across multiple nodes. To find specific tasks, you can filter the output of docker service ps based on various criteria, such as the task name or the node it's running on.

The --filter flag is used for filtering. The basic syntax is --filter "key=value".

To filter tasks by name, you can use the name key. For example, to find tasks with a name starting with my-nginx, you can use:

docker service ps --filter "name=my-nginx.1" my-nginx

This command will show only the task named my-nginx.1 for the my-nginx service. Note that task names are typically in the format service_name.task_number.

To filter tasks by the node they are running on, you can use the node key. First, you need to know the name of the node your task is running on. You can get this from the output of docker service ps. Let's assume your node name is labex-node.

docker service ps --filter "node=labex-node" my-nginx

This command will display tasks for the my-nginx service that are running on the node named labex-node. Replace labex-node with the actual name of your node if it's different.

You can combine filters by using multiple --filter flags.

Filter tasks by desired state

In addition to filtering by name or node, you can also filter tasks based on their desired state. The desired state indicates what state the Swarm manager wants the task to be in (e.g., Running, Shutdown, Rejected).

To filter tasks by desired state, you use the --filter flag with the desired-state key.

For example, to list only the tasks that are currently desired to be Running for the my-nginx service, you can use:

docker service ps --filter "desired-state=running" my-nginx

Since our my-nginx service is running, this command will show the active tasks.

If you wanted to see tasks that have been shut down, you could use:

docker service ps --filter "desired-state=shutdown" my-nginx

Currently, this command might not show any output unless you have scaled down or removed tasks.

You can also filter for tasks that have been Rejected. This state indicates that the Swarm manager was unable to start the task.

docker service ps --filter "desired-state=rejected" my-nginx

Understanding desired states is crucial for monitoring the health and status of your services in a Swarm.

Format the output of service tasks

In this final step, you will learn how to customize the output format of the docker service ps command. This is useful when you want to extract specific information or integrate the output with other tools.

The --format flag allows you to specify a Go template to format the output. You can use placeholders like .ID, .Name, .Image, .Node, .DesiredState, .CurrentState, .Error, and .Ports to display the corresponding task attributes.

For example, to display only the task ID, name, and image in a table format, you can use:

docker service ps --format "table {{.ID}}\t{{.Name}}\t{{.Image}}" my-nginx

This command will produce output similar to this:

ID             NAME         IMAGE
<task_id>      my-nginx.1   nginx:latest

You can also format the output as a list of values, which is useful for scripting. For example, to get just the task IDs:

docker service ps --format "{{.ID}}" my-nginx

This will output only the task ID(s).

Let's try another format, displaying the task name and the node it's running on:

docker service ps --format "Task: {{.Name}} is running on node: {{.Node}}" my-nginx

The output will look like this:

Task: my-nginx.1 is running on node: <node_name>

Experiment with different placeholders and formatting options to get the output you need.

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

docker service rm my-nginx

This command removes the my-nginx service and its associated tasks.

Summary

In this lab, you learned how to use the docker service ps command to list tasks associated with a Docker Swarm service. You started by creating a simple nginx service and then used docker service ps <service_name> to view its tasks, understanding the basic output columns like ID, Name, Image, Node, Desired State, and Current State.

Furthermore, you explored how to obtain more detailed task information by using the --no-trunc flag to prevent output truncation, allowing you to see full IDs and other comprehensive details about each task.