How to use docker stack ps command to list stack tasks

Introduction

In this lab, you will learn how to effectively use the docker stack ps command to list and manage tasks within a Docker stack. You will begin by deploying a sample stack using Docker Compose, a powerful tool for defining and running multi-container applications.

Following the stack deployment, you will explore the various capabilities of docker stack ps. This includes listing all tasks in the stack, filtering tasks based on their names, formatting the output to display specific fields of interest, and finally, displaying only the task IDs for a concise view. This hands-on experience will equip you with the skills to monitor and understand the state of your Docker stack tasks.

Skills Graph

Deploy a sample stack

In this step, you will learn how to deploy a sample stack using Docker Compose. Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.

Since Docker Compose is not pre-installed in the LabEx environment, you need to install it first. We will install Docker Compose version 1.29.2, which is compatible with the installed Docker version.

First, download the Docker Compose binary:

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

This command downloads the Docker Compose binary from the official GitHub repository and saves it to /usr/local/bin/docker-compose. The $(uname -s) and $(uname -m) parts automatically detect your operating system and architecture.

Next, apply executable permissions to the binary:

sudo chmod +x /usr/local/bin/docker-compose

This command makes the downloaded file executable.

Now, verify the installation by checking the Docker Compose version:

docker-compose --version

You should see output similar to docker-compose version 1.29.2, build 5becea4c.

Now that Docker Compose is installed, let's create a simple Docker Compose file to define our stack. We will create a file named docker-compose.yml in the ~/project directory.

Use the nano editor to create and edit the file:

nano ~/project/docker-compose.yml

Paste the following content into the docker-compose.yml file:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  app:
    image: alpine:latest
    command: echo "Hello from Alpine"

This docker-compose.yml file defines two services:

• web: Uses the nginx:latest image and maps port 80 on the host to port 80 in the container.
• app: Uses the alpine:latest image and runs a simple echo command.

Save the file by pressing Ctrl + S and exit the editor by pressing Ctrl + X.

Before deploying the stack, let's pull the necessary images. While Docker Compose can pull images automatically during deployment, explicitly pulling them beforehand can sometimes be helpful.

Pull the nginx:latest image:

docker pull nginx:latest

Pull the alpine:latest image:

docker pull alpine:latest

Now, deploy the stack using the docker-compose up command. The -d flag runs the containers in detached mode (in the background).

Navigate to the ~/project directory where you created the docker-compose.yml file:

cd ~/project

Then, run the command:

docker-compose up -d

This command reads the docker-compose.yml file and creates and starts the defined services. You should see output indicating the creation and starting of the web and app services.

To verify that the services are running, you can list the running containers:

docker ps

You should see two containers running, one for the web service (based on nginx) and one for the app service (based on alpine).

List all tasks in the stack

In this step, you will learn how to list all the tasks (containers) associated with the stack you deployed in the previous step. In Docker Swarm or Kubernetes, the term "task" is often used to refer to a running instance of a service. While we are using Docker Compose here, which doesn't technically use the "task" concept in the same way as Swarm, we can still list the containers that make up our deployed stack.

The docker-compose ps command is used to list the containers managed by Docker Compose for the current project (the directory containing the docker-compose.yml file).

Make sure you are still in the ~/project directory where your docker-compose.yml file is located:

cd ~/project

Now, run the docker-compose ps command:

docker-compose ps

This command will display a list of containers defined in your docker-compose.yml file, along with their current state, command, and ports.

You should see output similar to this (container names and IDs will vary):

      Name                     Command               State          Ports
--------------------------------------------------------------------------------
project_app_1       /bin/sh -c echo "Hello fr ...   Exit 0
project_web_1       /docker-entrypoint.sh ngin ...   Up      0.0.0.0:80->80/tcp

This output shows the two services defined in your docker-compose.yml: app and web. The State column indicates whether the container is running (Up) or has exited (Exit 0). The Ports column shows the port mapping for the web service.

The app container exited because its command echo "Hello from Alpine" finished execution. The web container is still running because the Nginx server is designed to run continuously.

This command is useful for quickly seeing which services in your stack are running and their basic status.

Filter tasks by name

In this step, you will learn how to filter the list of containers managed by Docker Compose based on their service name. This is useful when you have a large stack with many services and only want to see the status of a specific service.

The docker-compose ps command allows you to specify the service name as an argument to filter the output.

Make sure you are in the ~/project directory:

cd ~/project

To list only the container for the web service, run the following command:

docker-compose ps web

This command will only show the information for the container associated with the web service defined in your docker-compose.yml.

You should see output similar to this:

      Name                     Command               State          Ports
--------------------------------------------------------------------------------
project_web_1       /docker-entrypoint.sh ngin ...   Up      0.0.0.0:80->80/tcp

Similarly, to list only the container for the app service, run:

docker-compose ps app

This will show the information for the app container:

      Name                     Command               State          Ports
--------------------------------------------------------------------------------
project_app_1       /bin/sh -c echo "Hello fr ...   Exit 0

Filtering by service name is a simple yet effective way to manage and monitor individual components within your Docker Compose stack.

Format the output to show specific fields

In this step, you will learn how to format the output of the docker-compose ps command to display only specific fields. This is useful when you need to extract particular information about your services, such as their names or status, for scripting or further processing.

The docker-compose ps command supports the --format flag, which allows you to specify the output format using Go templates.

Make sure you are in the ~/project directory:

cd ~/project

To display only the service name and the container state, you can use the following command:

docker-compose ps --format "table {{.Service}}\t{{.State}}"

Let's break down the --format flag:

• "table": This specifies that the output should be in a table format with headers.
• {{.Service}}: This is a Go template placeholder that represents the service name.
• \t: This is a tab character, used here to separate the columns.
• {{.State}}: This is a Go template placeholder that represents the container state.

The output will look like this:

SERVICE         STATE
app             Exit 0
web             Up

You can include other fields in the format string as well. For example, to display the service name, image, and state:

docker-compose ps --format "table {{.Service}}\t{{.Image}}\t{{.State}}"

The output will be:

SERVICE         IMAGE           STATE
app             alpine:latest   Exit 0
web             nginx:latest    Up

Using the --format flag provides flexibility in how you view and process the information about your Docker Compose services.

Display only task IDs

In this step, you will learn how to display only the container IDs for the services in your Docker Compose stack. This is particularly useful when you need to pass container IDs to other commands for automation or scripting purposes.

We will again use the --format flag with the docker-compose ps command, but this time we will specify only the container ID field.

Make sure you are in the ~/project directory:

cd ~/project

To display only the container IDs, use the following command:

docker-compose ps -q

The -q flag is a shorthand for --quiet, which prints only the container IDs.

Alternatively, you can achieve the same result using the --format flag:

docker-compose ps --format "{{.ID}}"

This command uses the Go template {{.ID}} to extract only the container ID for each service.

The output of either command will be a list of container IDs, one per line:

<container_id_for_app>
<container_id_for_web>

(The actual IDs will be different in your environment).

Displaying only the IDs is a common requirement when you need to programmatically interact with your containers, for example, to stop or remove them.

Finally, let's clean up the deployed stack by bringing it down. This will stop and remove the containers and networks created by docker-compose up.

Make sure you are in the ~/project directory:

cd ~/project

Run the following command:

docker-compose down

This command will stop and remove the containers for the web and app services. You should see output indicating that the containers and network are being removed.

After running docker-compose down, you can verify that the containers are no longer running by using docker ps:

docker ps

This command should now show no running containers.

Summary

In this lab, you learned how to deploy a sample stack using Docker Compose. This involved installing Docker Compose, creating a docker-compose.yml file to define services, and then deploying the stack.

Following the deployment, you will learn how to use the docker stack ps command to list all tasks within the deployed stack. You will also explore how to filter these tasks by name, format the output to display specific fields, and display only the task IDs, demonstrating the flexibility of the docker stack ps command for monitoring and managing stack tasks.