How to use docker stack ls command to list stacks

Introduction

In this lab, you will learn how to use the docker stack ls command to list Docker stacks. We will begin by installing Docker Compose, which is essential for defining and deploying multi-container applications as stacks. You will then deploy a simple web service stack using a docker-compose.yml file to have a stack to list.

Following the deployment, you will explore different ways to list stacks using docker stack ls. This includes listing all running stacks, listing stacks with a custom output format to display specific information, and listing stacks in JSON format for programmatic processing.

Skills Graph

List all stacks

In this step, you will learn how to list all Docker stacks running on your system. A Docker stack is a collection of services that are deployed together. Before we can list stacks, we need to install Docker Compose, which is used to define and run multi-container Docker applications.

First, let's install Docker Compose. We will download the Docker Compose 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

The first command downloads the Docker Compose binary from the official GitHub repository. $(uname -s) and $(uname -m) are used to get the operating system and architecture of your machine, ensuring you download the correct binary. The second command makes the downloaded file executable.

Now that Docker Compose is installed, let's verify the installation by checking the version.

docker-compose --version

You should see the installed Docker Compose version in the output.

To demonstrate listing stacks, we need to deploy a simple stack. We will create a docker-compose.yml file that defines a simple web service.

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"

This docker-compose.yml file defines a single service named web that uses the nginx:latest image and maps port 80 on the host to port 80 in the container.

Now, let's deploy this stack using the docker stack deploy command. We will name our stack mywebstack.

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

The -c flag specifies the Compose file to use, and mywebstack is the name we are giving to our stack. You will see output indicating the services are being created and deployed.

After deploying the stack, you can list all running stacks using the docker stack ls command.

docker stack ls

This command will display a list of all deployed stacks, including the name of the stack, the number of services, and the desired and current number of replicas for each service. You should see mywebstack listed in the output.

List stacks with custom format

In the previous step, you learned how to list all deployed Docker stacks using the default output format. In this step, you will learn how to customize the output format of the docker stack ls command to display only the information you need.

The docker stack ls command supports the --format flag, which allows you to specify a Go template to format the output. This is useful when you want to extract specific information or integrate the output with other tools.

Let's start by listing the stack names and the number of services in each stack. We can use the {{.Name}} and {{.Services}} template fields for this.

docker stack ls --format "{{.Name}}: {{.Services}}"

In this command, --format "{{.Name}}: {{.Services}}" tells Docker to output each stack's name followed by a colon and then the number of services. The {{.Name}} and {{.Services}} are placeholders that will be replaced with the actual values for each stack.

You should see output similar to mywebstack: 1, indicating the name of the stack and the number of services it contains.

You can also include other fields in the format string. For example, let's list the stack name and the desired number of replicas.

docker stack ls --format "Stack Name: {{.Name}}, Desired Replicas: {{.Desired}}"

Here, we are using the {{.Desired}} field to display the desired number of replicas for the services in the stack.

The --format flag is very flexible and allows you to combine different fields and add custom text. You can find a list of available fields in the Docker documentation for the docker stack ls command.

Let's try one more example, listing the stack name and the current number of replicas.

docker stack ls --format "Stack: {{.Name}}, Current Replicas: {{.Current}}"

This command uses the {{.Current}} field to show the current number of running replicas for the services in the stack.

Using the --format flag allows you to tailor the output of docker stack ls to your specific needs, making it easier to process and analyze the information about your deployed stacks.

List stacks in JSON format

In the previous steps, you learned how to list Docker stacks using the default and custom formats. In this step, you will learn how to list Docker stacks in JSON format. This is particularly useful when you need to parse the output programmatically or integrate it with other systems.

The docker stack ls command, like many other Docker commands, supports the --format json option to output the results as a JSON array.

Let's list the deployed stacks in JSON format.

docker stack ls --format json

This command will output a JSON array, where each element in the array represents a Docker stack and contains information about the stack, such as its name, services, desired replicas, and current replicas.

The output will look something like this (the exact content will depend on the stacks you have deployed):

[
  {
    "Name": "mywebstack",
    "Services": "1",
    "Desired": "1",
    "Current": "1"
  }
]

This JSON output is structured and easy to parse using scripting languages or other tools. For example, you could use a tool like jq to extract specific fields from the JSON output.

Let's install jq, a lightweight and flexible command-line JSON processor.

sudo apt-get update
sudo apt-get install -y jq

Now that jq is installed, let's use it to extract just the names of the deployed stacks from the JSON output.

docker stack ls --format json | jq '.[].Name'

In this command, we pipe the JSON output of docker stack ls --format json to jq. The '.[].Name' is a jq filter that selects the Name field from each object in the JSON array.

You should see the name of your deployed stack, mywebstack, as the output.

Listing stacks in JSON format provides a structured way to access stack information, which is essential for automation and integration purposes.

Summary

In this lab, you learned how to use the docker stack ls command to list Docker stacks. The lab began by guiding you through the installation of Docker Compose, a prerequisite for working with Docker stacks, and verifying its installation. You then created a simple docker-compose.yml file defining a basic web service and deployed it as a stack named mywebstack using docker stack deploy.

The subsequent steps, though not fully detailed in the provided content, would have covered listing all deployed stacks using docker stack ls, customizing the output format to display specific information, and listing stacks in JSON format for programmatic processing. This hands-on experience provided practical knowledge of managing and inspecting Docker stacks using the docker stack ls command and its various options.