How to use docker service ls command to list services

Introduction

In this lab, you will learn how to effectively use the docker service ls command to manage and inspect services running in a Docker Swarm. You will begin by listing all services in your swarm, ensuring you have a basic understanding of the command's output and the information it provides.

Building upon the basic listing, you will then explore powerful filtering options. This includes filtering services by their name, allowing you to quickly locate specific services. You will also learn how to filter by service mode (e.g., replicated or global) and by labels, which are key-value pairs used for organizing and identifying services. Finally, you will discover how to format the output of the docker service ls command to display the information in a way that best suits your needs, making it easier to parse and analyze service details.

Skills Graph

List all services in the swarm

In this step, you will learn how to list all services running in a Docker Swarm. Before listing services, you need to have a Docker Swarm initialized and at least one service running.

First, let's initialize a Docker Swarm if it's not already initialized. You can check the swarm status using the docker info command. If the output includes "Swarm: active", the swarm is already initialized. Otherwise, you need to initialize it.

docker info

If the swarm is not active, initialize it:

docker swarm init

Now, let's create a simple service to list. We will create a service named my-web-service using the nginx image. Since we are using a fresh environment, we need to pull the nginx image first.

docker pull nginx

Now, create the service:

docker service create --name my-web-service -p 80:80 nginx

This command creates a service named my-web-service from the nginx image and publishes port 80 of the container to port 80 on the host.

To list all services in the swarm, you use the docker service ls command. This command shows information about the services, including their ID, name, mode, replicas, and the image they are using.

docker service ls

The output will show the my-web-service you just created. You should see its ID, name, mode (replicated), the number of replicas (usually 1 by default), and the image (nginx).

Filter services by name

In this step, you will learn how to filter the list of services by their name using the docker service ls command with the --filter flag. This is useful when you have many services running and you only want to see information about a specific service or a group of services with similar names.

The basic syntax for filtering by name is docker service ls --filter name=<service_name>. You can provide the full name of the service or a part of the name.

In the previous step, we created a service named my-web-service. Let's use the filter to display only this service.

docker service ls --filter name=my-web-service

The output should only show the line corresponding to the my-web-service.

You can also use partial names to filter. For example, if you had services named my-web-service-1 and my-web-service-2, filtering by name=my-web would show both. In our current setup, filtering by name=my-web will still show my-web-service.

docker service ls --filter name=my-web

This command demonstrates how to use a partial name for filtering. The output should still list my-web-service.

Filtering by name is a quick way to narrow down the list of services and find the information you need about a specific service without having to scan through the entire list.

Filter services by mode

In this step, you will learn how to filter the list of services based on their mode using the docker service ls command with the --filter flag. Docker Swarm services can run in two modes: replicated and global.

• Replicated: This is the default mode. The swarm manager schedules a specified number of replicas of the service task on available nodes.
• Global: The swarm runs one task for the service on every available node.

The basic syntax for filtering by mode is docker service ls --filter mode=<mode>. You can use either replicated or global as the mode.

In the previous steps, we created a service named my-web-service which runs in replicated mode by default. Let's filter the services to show only those running in replicated mode.

docker service ls --filter mode=replicated

The output should show my-web-service because it is a replicated service.

Now, let's try filtering for services in global mode. Since we haven't created any global services, this command should not show any services.

docker service ls --filter mode=global

The output of this command should only show the header row and no service entries, as there are no global services running.

Filtering by mode is helpful when you want to see only services of a specific type, for example, to check the status of all your global services that are meant to run on every node.

Filter services by label

In this step, you will learn how to filter the list of services based on labels using the docker service ls command with the --filter flag. Labels are key-value pairs that you can attach to Docker objects, including services, to help organize and identify them.

The basic syntax for filtering by label is docker service ls --filter label=<key>=<value>. You can filter by a specific label key and value, or just by the presence of a label key.

First, let's update our existing my-web-service to add a label. We will add a label environment=development to the service.

docker service update --label-add environment=development my-web-service

This command updates the my-web-service and adds the specified label.

Now, let's filter the services to show only those with the label environment=development.

docker service ls --filter label=environment=development

The output should show my-web-service because we just added this label to it.

You can also filter by just the presence of a label key, regardless of its value. For example, to list all services that have the environment label:

docker service ls --filter label=environment

This command will list all services that have the environment label, regardless of its value. In our case, it will still show my-web-service.

Filtering by labels is a powerful way to manage and query services, especially in larger swarms where you might use labels to categorize services by environment, team, or application.

Format the output of service listing

In this step, you will learn how to format the output of the docker service ls command using the --format flag. This allows you to customize the information displayed and the format in which it is presented, which is particularly useful for scripting or generating reports.

The --format flag uses Go's text/template package. You can specify the fields you want to display and how they should be formatted. Common fields for services include .ID, .Name, .Mode, .Replicas, and .Image.

Let's start by displaying only the service ID and name, separated by a tab.

docker service ls --format "{{.ID}}\t{{.Name}}"

The output will show the ID and name of my-web-service, separated by a tab character.

Now, let's display the service name, image, and mode in a more readable format, perhaps like a table without the default header.

docker service ls --format "table {{.Name}}\t{{.Image}}\t{{.Mode}}"

Using table at the beginning of the format string tells Docker to format the output as a table. The fields are separated by tabs (\t).

You can also use JSON format, which is very useful for programmatic processing.

docker service ls --format json

This command will output the service information in JSON format.

Formatting the output gives you flexibility in how you view and use the service information. You can select specific fields, change the separators, and output in different formats like table or JSON.

Summary

In this lab, you learned how to use the docker service ls command to list services running in a Docker Swarm. You started by ensuring a Docker Swarm was initialized and creating a sample service. You then used docker service ls to view all running services, understanding the basic output including service ID, name, mode, replicas, and image.

Furthermore, you explored how to filter the service list using the --filter flag. You learned to filter services specifically by their name, which is essential for managing a large number of services and focusing on relevant information.