How to use docker stack services command to list services

Introduction

In this lab, you will learn how to effectively use the docker stack services command to manage and inspect services within a Docker stack. We will begin by setting up a simple Docker stack using Docker Compose, which involves installing Docker Compose and deploying a basic application defined in a docker-compose.yml file.

Once the stack is running, you will explore the core functionality of docker stack services to list all services in a stack. Building upon this, you will learn how to refine your service listings by filtering based on service name and ID. Finally, you will discover how to customize the output format of the service list to display the information you need in a clear and organized manner.

List all services in a stack

In this step, you will learn how to list all services running within a Docker stack. Before we can list services, we need to have a stack running. Since Docker Compose is not pre-installed, we will first install it and then deploy a simple stack.

First, let's install Docker Compose. We will download the binary and make it executable.

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

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

nano ~/project/docker-compose.yml

Add the following content to the file:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  app:
    image: alpine:latest
    command: sleep 3600

This file defines a stack with two services: web using the nginx image and app using the alpine image. The web service maps port 80 on the host to port 80 in the container. The app service simply runs the sleep 3600 command to keep the container running.

Save the file and exit the editor (Ctrl+X, Y, Enter in nano).

Now, let's deploy the stack using docker stack deploy. We will name our stack mystack.

docker stack deploy -c ~/project/docker-compose.yml mystack

This command reads the docker-compose.yml file and creates the services defined within it as a Docker stack named mystack. You should see output indicating that the services are being created.

Once the stack is deployed, you can list all services in the stack using the docker stack services command followed by the stack name.

docker stack services mystack

This command will display a table showing information about the services in the mystack stack, including their ID, name, mode, replicas, image, and ports.

You should see output similar to this:

ID             NAME                 MODE         REPLICAS   IMAGE          PORTS
xxxxxxxxxxxx   mystack_app          replicated   1/1        alpine:latest
xxxxxxxxxxxx   mystack_web          replicated   1/1        nginx:latest   *:80->80/tcp

The output lists the mystack_app and mystack_web services, confirming that they are running as part of the mystack stack.

Filter services by name

In this step, you will learn how to filter the list of services in a Docker stack based on their name. This is useful when you have many services in a stack and only want to see information about specific ones.

The docker stack services command supports the --filter flag, which allows you to specify criteria for filtering the output. To filter by service name, you can use the name filter.

The syntax for filtering by name is --filter name=<service_name>. Remember that the service names in a stack are typically prefixed with the stack name, followed by an underscore and the service name defined in the docker-compose.yml file (e.g., mystack_web).

Let's filter the services in our mystack stack to only show the web service.

docker stack services mystack --filter name=mystack_web

This command will only display the row corresponding to the mystack_web service.

You should see output similar to this:

ID             NAME                 MODE         REPLICAS   IMAGE          PORTS
xxxxxxxxxxxx   mystack_web          replicated   1/1        nginx:latest   *:80->80/tcp

Notice that only the information for the mystack_web service is shown.

Similarly, you can filter to see only the app service:

docker stack services mystack --filter name=mystack_app

This will display the information for the mystack_app service:

ID             NAME                 MODE         REPLICAS   IMAGE
xxxxxxxxxxxx   mystack_app          replicated   1/1        alpine:latest

Using the name filter allows you to quickly find and view details for specific services within a large stack.

Filter services by ID

In this step, you will learn how to filter the list of services in a Docker stack based on their unique ID. While filtering by name is often more intuitive, filtering by ID is useful when you need to be absolutely precise or when dealing with services that might have similar names.

Each service in a Docker stack is assigned a unique ID. You can see these IDs in the first column of the output from docker stack services.

To filter by service ID, you use the --filter flag with the id filter. The syntax is --filter id=<service_id>. You only need to provide a sufficient prefix of the ID to uniquely identify the service.

First, let's list all services again to get their IDs.

docker stack services mystack

Look at the output and identify the IDs for the mystack_web and mystack_app services. The IDs will be a string of hexadecimal characters. For example, the output might look like this (your IDs will be different):

ID             NAME                 MODE         REPLICAS   IMAGE          PORTS
xxxxxxxxxxxx   mystack_app          replicated   1/1        alpine:latest
yyyyyyyyyyyy   mystack_web          replicated   1/1        nginx:latest   *:80->80/tcp

Let's say the ID for mystack_web starts with yyyyyyyyyyyy. You can filter by this ID (or a shorter unique prefix) like this:

docker stack services mystack --filter id=yyyyyyyyyyyy

Replace yyyyyyyyyyyy with the actual beginning of the ID for your mystack_web service.

This command will display only the row for the service with the matching ID.

You should see output similar to this, showing only the mystack_web service:

ID             NAME                 MODE         REPLICAS   IMAGE          PORTS
yyyyyyyyyyyy   mystack_web          replicated   1/1        nginx:latest   *:80->80/tcp

Similarly, you can filter by the ID of the mystack_app service. Find its ID from the docker stack services mystack output and use it in the filter. For example, if the ID starts with xxxxxxxxxxxx:

docker stack services mystack --filter id=xxxxxxxxxxxx

Replace xxxxxxxxxxxx with the actual beginning of the ID for your mystack_app service.

This will display the information for the mystack_app service:

ID             NAME                 MODE         REPLICAS   IMAGE
xxxxxxxxxxxx   mystack_app          replicated   1/1        alpine:latest

Filtering by ID provides a precise way to target specific services, especially in automated scripts or when dealing with services that might have similar names.

Format the output of services list

In this step, you will learn how to format the output of the docker stack services command. By default, the output is displayed in a human-readable table format. However, you can use the --format flag to customize the output, which is particularly useful for scripting or when you need specific information in a different format.

The --format flag accepts a Go template string. This allows you to specify exactly which fields to display and how to format them. Common fields you might want to display include .ID, .Name, .Image, .Mode, .Replicas, and .Ports.

Let's try formatting the output to show only the service ID, name, and image, separated by tabs.

docker stack services mystack --format "{{.ID}}\t{{.Name}}\t{{.Image}}"

In this command:

• {{.ID}}, {{.Name}}, and {{.Image}} are Go template placeholders that will be replaced by the respective values for each service.
• \t represents a tab character, used here as a separator.

The output will now be a list of services, with each line containing the ID, name, and image, separated by tabs:

xxxxxxxxxxxx mystack_app alpine:latest
yyyyyyyyyyyy mystack_web nginx:latest

(Remember that the IDs will be different in your environment).

You can also format the output as a list, which can be easier to parse in some cases. For example, to list the service name and the number of replicas:

docker stack services mystack --format "- {{.Name}} (Replicas: {{.Replicas}})"

This will output:

- mystack_app (Replicas: 1/1)
- mystack_web (Replicas: 1/1)

The --format flag provides a powerful way to tailor the output of docker stack services to your specific needs, making it easier to integrate with other tools or scripts.

Finally, let's clean up the deployed stack by removing it.

docker stack rm mystack

This command will remove all services and networks associated with the mystack stack. You should see output indicating that the stack is being removed.

Summary

In this lab, you learned how to list services within a Docker stack using the docker stack services command. This involved first installing Docker Compose and deploying a simple stack defined in a docker-compose.yml file. You then used docker stack services <stack_name> to display a table of all services in the deployed stack.

The lab also covered filtering services by name and ID, allowing you to narrow down the list to specific services. Finally, you explored how to format the output of the docker stack services command to customize the displayed information.