Inspect a Docker Swarm Stack's Services Safely

You will list the services belonging to a Docker Swarm stack, narrow the result to named services, and produce output suitable for a script. The command is read-only: it does not scale, redeploy or remove anything. These examples use Docker CLI 29.8.1 from docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes. You need the Docker CLI, access to a running Swarm manager, and the exact stack name. The command must run on a manager node, not merely on a machine that has Docker installed. No step needs sudo unless your Docker setup requires elevated access to the daemon socket.

1. Check the installed command

Read the local command help before using it:

$ docker stack services --help
Usage:  docker stack services [OPTIONS] STACK

List the services in the stack

The important shape is docker stack services [OPTIONS] STACK. STACK is a stack name, not a service name or a Compose file. The available options on this installation are --filter, --format and --quiet, with the short forms -f and -q where provided.

Checkpoint: record the version and confirm which binary will run:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ command -v docker
/usr/bin/docker

2. Confirm manager access before querying

Use a real stack name from your deployment. The query below only reads Swarm state, but it still needs a manager:

$ docker stack services STACK_NAME

Replace STACK_NAME with a name such as myapp. Do not type the placeholder literally. On a manager with that stack, the default table contains columns such as ID, NAME, REPLICAS, IMAGE and COMMAND. Service IDs, images and replica counts are deployment-specific, so do not compare them with an example from another cluster.

A successful command normally exits silently apart from the table. Check the status immediately if a script depends on it:

$ docker stack services STACK_NAME > /tmp/stack-services.txt
$ status=$?
$ printf 'docker status: %s\n' "$status"
docker status: 0

The temporary file is only an example of capturing output. Use a private, controlled path if service names or image details are sensitive. Remove it after inspection with rm -- /tmp/stack-services.txt when you no longer need it.

If Docker reports that the node is not a Swarm manager, stop there. Moving to a manager or joining a Swarm changes cluster state and is an administrative decision outside this guide. If the stack name does not exist, check the spelling with the person or deployment that owns the Swarm; do not create a stack just to make a read-only query succeed.

3. Read the default service table

Run the query without formatting first:

$ docker stack services myapp
ID             NAME          MODE         REPLICAS   IMAGE          PORTS
7be5ei6sqeye   myapp_web     replicated   1/1        nginx:latest

Your Docker release may include slightly different columns or alignment. The useful fields are the service identity, mode, desired and running replicas, image, and any published ports. A replica value such as 0/1 is a warning to investigate, not a command to restart the service. Inspect task details with the separate Swarm commands used by your operations process.

Do not mistake this command for docker service ls. The latter lists services across the Swarm. docker stack services myapp limits the result to services associated with the named stack.

4. Filter the result

Use a filter when a stack contains more services than you need. The filter value is a key=value pair. For example, filter by service name:

$ docker stack services --filter name=myapp_web myapp
ID             NAME          MODE         REPLICAS   IMAGE          PORTS
7be5ei6sqeye   myapp_web     replicated   1/1        nginx:latest

The Docker documentation also describes id and label filters. Pass the option more than once when you need more than one value:

$ docker stack services \
    --filter name=myapp_web \
    --filter name=myapp_db \
    myapp

Multiple filter flags are combined as an OR filter in current Docker documentation. Keep that detail visible in scripts: two name filters select either named service, rather than requiring one service to have both names. If a filter returns no rows, check the stack name and the exact service name before treating that as evidence that the service is absent.

5. Use quiet output for service IDs

--quiet prints only service IDs, which is useful when another command will consume them:

$ docker stack services --quiet myapp
7be5ei6sqeye
dn7m7nhhfb9y

Do not parse the human-readable table when IDs are all you need. The output can contain more than one line, so treat it as a list rather than a single value. A missing stack or a manager error still produces a non-zero exit status; always check the status before passing captured IDs to another command.

6. Format fields for scripts

Use a Go template with --format when a script needs stable fields rather than padded table columns:

$ docker stack services \
    --format '{{.Name}} {{.Replicas}} {{.Image}}' \
    myapp
myapp_web 1/1 nginx:latest
myapp_db 1/1 postgres:16

The documented service placeholders include .ID, .Name, .Mode, .Replicas and .Image. The template controls the fields and separators, so choose a separator that cannot occur in the values you expect, or use a more structured format.

For one JSON object per service, use the installed CLI's JSON directive:

$ docker stack services --format json myapp
{"ID":"7be5ei6sqeye","Name":"myapp_web","Mode":"replicated","Replicas":"1/1","Image":"nginx:latest"}

JSON output is still a report, not a backup of the stack definition. It does not contain every deployment setting and it should not be edited and fed back to Docker. If a later tool processes the output, validate that the command exited successfully before parsing it.

7. Keep the inspection reversible

Every command in this workflow reads Swarm metadata. It does not change replicas, service definitions, images or routing, so there is no rollback step. The main operational trap is following an unhealthy replica count with an unplanned repair. Treat that as a separate change: record the observed output, identify the service owner, and use an approved deployment procedure before running commands such as service update, scale or remove.

For a repeatable check, save a timestamp beside a report rather than overwriting a useful one:

$ report="stack-services-$(date +%Y%m%d-%H%M%S).txt"
$ docker stack services --format '{{.Name}} {{.Mode}} {{.Replicas}} {{.Image}}' myapp > "$report"
$ test -s "$report" && sed -n '1,20p' "$report"
myapp_web replicated 1/1 nginx:latest

Check the report before archiving it. If the query failed, the redirection may still have created an empty file; remove only that known temporary report with rm -- "$report", not a broad wildcard.