1# stack ps
2
3<!---MARKER_GEN_START-->
4List the tasks in the stack
5
6### Options
7
8| Name | Type | Default | Description |
9|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
10| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
11| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
12| [`--no-resolve`](#no-resolve) | | | Do not map IDs to Names |
13| [`--no-trunc`](#no-trunc) | | | Do not truncate output |
14| [`-q`](#quiet), [`--quiet`](#quiet) | | | Only display task IDs |
15
16
17<!---MARKER_GEN_END-->
18
19## Description
20
21Lists the tasks that are running as part of the specified stack.
22
23> **Note**
24>
25> This is a cluster management command, and must be executed on a swarm
26> manager node. To learn about managers and workers, refer to the
27> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
28> documentation.
29
30## Examples
31
32### List the tasks that are part of a stack
33
34The following command shows all the tasks that are part of the `voting` stack:
35
36```console
37$ docker stack ps voting
38
39ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
40xim5bcqtgk1b voting_worker.1 dockersamples/examplevotingapp_worker:latest node2 Running Running 2 minutes ago
41q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 2 minutes ago
42rx5yo0866nfx voting_vote.1 dockersamples/examplevotingapp_vote:before node3 Running Running 2 minutes ago
43tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 2 minutes ago
44w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 3 minutes ago
456jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 2 minutes ago
46kqgdmededccb voting_vote.2 dockersamples/examplevotingapp_vote:before node2 Running Running 2 minutes ago
47t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 3 minutes ago
48```
49
50### <a name="filter"></a> Filtering (--filter)
51
52The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there
53is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
54Multiple filter flags are combined as an `OR` filter. For example,
55`-f name=redis.1 -f name=redis.7` returns both `redis.1` and `redis.7` tasks.
56
57The currently supported filters are:
58
59* [id](#id)
60* [name](#name)
61* [node](#node)
62* [desired-state](#desired-state)
63
64#### id
65
66The `id` filter matches on all or a prefix of a task's ID.
67
68```console
69$ docker stack ps -f "id=t" voting
70
71ID NAME IMAGE NODE DESIRED STATE CURRENTSTATE ERROR PORTS
72tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 14 minutes ago
73t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 14 minutes ago
74```
75
76#### name
77
78The `name` filter matches on task names.
79
80```console
81$ docker stack ps -f "name=voting_redis" voting
82
83ID NAME IMAGE NODE DESIRED STATE CURRENTSTATE ERROR PORTS
84w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 17 minutes ago
85t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 17 minutes ago
86```
87
88#### node
89
90The `node` filter matches on a node name or a node ID.
91
92```console
93$ docker stack ps -f "node=node1" voting
94
95ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
96q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 18 minutes ago
97tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 18 minutes ago
986jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 18 minutes ago
99```
100
101#### desired-state
102
103The `desired-state` filter can take the values `running`, `shutdown`, `ready` or `accepted`.
104
105```console
106$ docker stack ps -f "desired-state=running" voting
107
108ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
109xim5bcqtgk1b voting_worker.1 dockersamples/examplevotingapp_worker:latest node2 Running Running 21 minutes ago
110q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 21 minutes ago
111rx5yo0866nfx voting_vote.1 dockersamples/examplevotingapp_vote:before node3 Running Running 21 minutes ago
112tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 21 minutes ago
113w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 21 minutes ago
1146jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 21 minutes ago
115kqgdmededccb voting_vote.2 dockersamples/examplevotingapp_vote:before node2 Running Running 21 minutes ago
116t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 21 minutes ago
117```
118
119### <a name="format"></a> Format the output (--format)
120
121The formatting options (`--format`) pretty-prints tasks output using a Go template.
122
123Valid placeholders for the Go template are listed below:
124
125| Placeholder | Description |
126|-----------------|------------------------------------------------------------------|
127| `.ID` | Task ID |
128| `.Name` | Task name |
129| `.Image` | Task image |
130| `.Node` | Node ID |
131| `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
132| `.CurrentState` | Current state of the task |
133| `.Error` | Error |
134| `.Ports` | Task published ports |
135
136When using the `--format` option, the `stack ps` command will either
137output the data exactly as the template declares or, when using the
138`table` directive, includes column headers as well.
139
140The following example uses a template without headers and outputs the
141`Name` and `Image` entries separated by a colon (`:`) for all tasks:
142
143```console
144$ docker stack ps --format "{{.Name}}: {{.Image}}" voting
145
146voting_worker.1: dockersamples/examplevotingapp_worker:latest
147voting_result.1: dockersamples/examplevotingapp_result:before
148voting_vote.1: dockersamples/examplevotingapp_vote:before
149voting_db.1: postgres:9.4
150voting_redis.1: redis:alpine
151voting_visualizer.1: dockersamples/visualizer:stable
152voting_vote.2: dockersamples/examplevotingapp_vote:before
153voting_redis.2: redis:alpine
154```
155
156To list all tasks in JSON format, use the `json` directive:
157```console
158$ docker stack ps --format json myapp
159{"CurrentState":"Preparing 23 seconds ago","DesiredState":"Running","Error":"","ID":"2ufjubh79tn0","Image":"localstack/localstack:latest","Name":"myapp_localstack.1","Node":"docker-desktop","Ports":""}
160{"CurrentState":"Running 20 seconds ago","DesiredState":"Running","Error":"","ID":"roee387ngf5r","Image":"redis:6.0.9-alpine3.12","Name":"myapp_redis.1","Node":"docker-desktop","Ports":""}
161{"CurrentState":"Preparing 13 seconds ago","DesiredState":"Running","Error":"","ID":"yte68ouq7glh","Image":"postgres:13.2-alpine","Name":"myapp_repos-db.1","Node":"docker-desktop","Ports":""}
162```
163
164### <a name="no-resolve"></a> Do not map IDs to Names (--no-resolve)
165
166The `--no-resolve` option shows IDs for task name, without mapping IDs to Names.
167
168```console
169$ docker stack ps --no-resolve voting
170
171ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
172xim5bcqtgk1b 10z9fjfqzsxnezo4hb81p8mqg.1 dockersamples/examplevotingapp_worker:latest qaqt4nrzo775jrx6detglho01 Running Running 30 minutes ago
173q7yik0ks1in6 hbxltua1na7mgqjnidldv5m65.1 dockersamples/examplevotingapp_result:before mxpaef1tlh23s052erw88a4w5 Running Running 30 minutes ago
174rx5yo0866nfx qyprtqw1g5nrki557i974ou1d.1 dockersamples/examplevotingapp_vote:before kanqcxfajd1r16wlnqcblobmm Running Running 31 minutes ago
175tz6j82jnwrx7 122f0xxngg17z52be7xspa72x.1 postgres:9.4 mxpaef1tlh23s052erw88a4w5 Running Running 31 minutes ago
176w48spazhbmxc tg61x8myx563ueo3urmn1ic6m.1 redis:alpine qaqt4nrzo775jrx6detglho01 Running Running 31 minutes ago
1776jj1m02freg1 8cqlyi444kzd3panjb7edh26v.1 dockersamples/visualizer:stable mxpaef1tlh23s052erw88a4w5 Running Running 31 minutes ago
178kqgdmededccb qyprtqw1g5nrki557i974ou1d.2 dockersamples/examplevotingapp_vote:before qaqt4nrzo775jrx6detglho01 Running Running 31 minutes ago
179t72q3z038jeh tg61x8myx563ueo3urmn1ic6m.2 redis:alpine kanqcxfajd1r16wlnqcblobmm Running Running 31 minutes ago
180```
181
182### <a name="no-trunc"></a> Do not truncate output (--no-trunc)
183
184When deploying a service, docker resolves the digest for the service's
185image, and pins the service to that digest. The digest is not shown by
186default, but is printed if `--no-trunc` is used. The `--no-trunc` option
187also shows the non-truncated task IDs, and error-messages, as can be seen below:
188
189```console
190$ docker stack ps --no-trunc voting
191
192ID NAME IMAGE NODE DESIRED STATE CURREN STATE ERROR PORTS
193xim5bcqtgk1bxqz91jzo4a1s5 voting_worker.1 dockersamples/examplevotingapp_worker:latest@sha256:3e4ddf59c15f432280a2c0679c4fc5a2ee5a797023c8ef0d3baf7b1385e9fed node2 Running Runnin 32 minutes ago
194q7yik0ks1in6kv32gg6y6yjf7 voting_result.1 dockersamples/examplevotingapp_result:before@sha256:83b56996e930c292a6ae5187fda84dd6568a19d97cdb933720be15c757b7463 node1 Running Runnin 32 minutes ago
195rx5yo0866nfxc58zf4irsss6n voting_vote.1 dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6 node3 Running Runnin 32 minutes ago
196tz6j82jnwrx7n2offljp3mn03 voting_db.1 postgres:9.4@sha256:6046af499eae34d2074c0b53f9a8b404716d415e4a03e68bc1d2f8064f2b027 node1 Running Runnin 32 minutes ago
197w48spazhbmxcmbjfi54gs7x90 voting_redis.1 redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7 node2 Running Runnin 32 minutes ago
1986jj1m02freg1n3z9n1evrzsbl voting_visualizer.1 dockersamples/visualizer:stable@sha256:f924ad66c8e94b10baaf7bdb9cd491ef4e982a1d048a56a17e02bf5945401e5 node1 Running Runnin 32 minutes ago
199kqgdmededccbhz2wuc0e9hx7g voting_vote.2 dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6 node2 Running Runnin 32 minutes ago
200t72q3z038jehe1wbh9gdum076 voting_redis.2 redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7 node3 Running Runnin 32 minutes ago
201```
202
203### <a name="quiet"></a> Only display task IDs (-q, --quiet)
204
205The `-q ` or `--quiet` option only shows IDs of the tasks in the stack.
206This example outputs all task IDs of the `voting` stack:
207
208```console
209$ docker stack ps -q voting
210xim5bcqtgk1b
211q7yik0ks1in6
212rx5yo0866nfx
213tz6j82jnwrx7
214w48spazhbmxc
2156jj1m02freg1
216kqgdmededccb
217t72q3z038jeh
218```
219
220This option can be used to perform batch operations. For example, you can use
221the task IDs as input for other commands, such as `docker inspect`. The
222following example inspects all tasks of the `voting` stack:
223
224```console
225$ docker inspect $(docker stack ps -q voting)
226
227[
228 {
229 "ID": "xim5bcqtgk1b1gk0krq1",
230 "Version": {
231<...>
232```
233
234## Related commands
235
236* [stack deploy](stack_deploy.md)
237* [stack ls](stack_ls.md)
238* [stack rm](stack_rm.md)
239* [stack services](stack_services.md)
View as plain text