Browse code
Merge pull request #15822 from vdemeester/docs-update-filtering-ps-and-images
Update filtering chapters on ps/images references
moxiegirl authored on 2015/08/28 02:39:20Showing 2 changed files
| ... | ... |
@@ -123,7 +123,7 @@ The currently supported filters are: |
| 123 | 123 |
* dangling (boolean - true or false) |
| 124 | 124 |
* label (`label=<key>` or `label=<key>=<value>`) |
| 125 | 125 |
|
| 126 |
-##### Untagged images |
|
| 126 |
+##### Untagged images (dangling) |
|
| 127 | 127 |
|
| 128 | 128 |
$ docker images --filter "dangling=true" |
| 129 | 129 |
|
| ... | ... |
@@ -155,3 +155,27 @@ Ready for use by `docker rmi ...`, like: |
| 155 | 155 |
NOTE: Docker will warn you if any containers exist that are using these untagged images. |
| 156 | 156 |
|
| 157 | 157 |
|
| 158 |
+##### Labeled images |
|
| 159 |
+ |
|
| 160 |
+The `label` filter matches images based on the presence of a `label` alone or a `label` and a |
|
| 161 |
+value. |
|
| 162 |
+ |
|
| 163 |
+The following filter matches images with the `com.example.version` label regardless of its value. |
|
| 164 |
+ |
|
| 165 |
+ $ docker images --filter "label=com.example.version" |
|
| 166 |
+ |
|
| 167 |
+ REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE |
|
| 168 |
+ match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB |
|
| 169 |
+ match-me-2 latest eeae25ada2aa About a minute ago 188.3 MB |
|
| 170 |
+ |
|
| 171 |
+The following filter matches images with the `com.example.version` label with the `1.0` value. |
|
| 172 |
+ |
|
| 173 |
+ $ docker images --filter "label=com.example.version=1.0" |
|
| 174 |
+ REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE |
|
| 175 |
+ match-me latest eeae25ada2aa About a minute ago 188.3 MB |
|
| 176 |
+ |
|
| 177 |
+In this example, with the `0.1` value, it returns an empty set because no matches were found. |
|
| 178 |
+ |
|
| 179 |
+ $ docker images --filter "label=com.example.version=0.1" |
|
| 180 |
+ REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE |
|
| 181 |
+ |
| ... | ... |
@@ -51,7 +51,47 @@ The currently supported filters are: |
| 51 | 51 |
* exited (int - the code of exited containers. Only useful with `--all`) |
| 52 | 52 |
* status (created|restarting|running|paused|exited) |
| 53 | 53 |
|
| 54 |
-## Successfully exited containers |
|
| 54 |
+ |
|
| 55 |
+#### Label |
|
| 56 |
+ |
|
| 57 |
+The `label` filter matches containers based on the presence of a `label` alone or a `label` and a |
|
| 58 |
+value. |
|
| 59 |
+ |
|
| 60 |
+The following filter matches containers with the `color` label regardless of its value. |
|
| 61 |
+ |
|
| 62 |
+ $ docker ps --filter "label=color" |
|
| 63 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 64 |
+ 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley |
|
| 65 |
+ d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani |
|
| 66 |
+ |
|
| 67 |
+The following filter matches containers with the `color` label with the `blue` value. |
|
| 68 |
+ |
|
| 69 |
+ $ docker ps --filter "label=color=blue" |
|
| 70 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 71 |
+ d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani |
|
| 72 |
+ |
|
| 73 |
+#### Name |
|
| 74 |
+ |
|
| 75 |
+The `name` filter matches on all or part of a container's name. |
|
| 76 |
+ |
|
| 77 |
+The following filter matches all containers with a name containing the `nostalgic_stallman` string. |
|
| 78 |
+ |
|
| 79 |
+ $ docker ps --filter "name=nostalgic_stallman" |
|
| 80 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 81 |
+ 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman |
|
| 82 |
+ |
|
| 83 |
+You can also filter for a substring in a name as this shows: |
|
| 84 |
+ |
|
| 85 |
+ $ docker ps --filter "name=nostalgic" |
|
| 86 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 87 |
+ 715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic |
|
| 88 |
+ 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman |
|
| 89 |
+ 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley |
|
| 90 |
+ |
|
| 91 |
+#### Exited |
|
| 92 |
+ |
|
| 93 |
+The `exited` filter matches containers by exist status code. For example, to filter for containers |
|
| 94 |
+that have exited successfully: |
|
| 55 | 95 |
|
| 56 | 96 |
$ docker ps -a --filter 'exited=0' |
| 57 | 97 |
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
| ... | ... |
@@ -59,7 +99,62 @@ The currently supported filters are: |
| 59 | 59 |
106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani |
| 60 | 60 |
48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds |
| 61 | 61 |
|
| 62 |
-This shows all the containers that have exited with status of '0' |
|
| 62 |
+#### Status |
|
| 63 |
+ |
|
| 64 |
+The `status` filter matches containers by status. You can filter using `created`, `restarting`, `running`, `paused` and `exited`. For example, to filter for `running` containers: |
|
| 65 |
+ |
|
| 66 |
+ $ docker ps --filter status=running |
|
| 67 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 68 |
+ 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic |
|
| 69 |
+ d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top |
|
| 70 |
+ 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman |
|
| 71 |
+ |
|
| 72 |
+To filter for `paused` containers: |
|
| 73 |
+ |
|
| 74 |
+ $ docker ps --filter status=paused |
|
| 75 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 76 |
+ 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley |
|
| 77 |
+ |
|
| 78 |
+#### Ancestor |
|
| 79 |
+ |
|
| 80 |
+The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the |
|
| 81 |
+following image representation: |
|
| 82 |
+ |
|
| 83 |
+- image |
|
| 84 |
+- image:tag |
|
| 85 |
+- image:tag@digest |
|
| 86 |
+- short-id |
|
| 87 |
+- full-id |
|
| 88 |
+ |
|
| 89 |
+If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the |
|
| 90 |
+latest `ubuntu` image: |
|
| 91 |
+ |
|
| 92 |
+ $ docker ps --filter ancestor=ubuntu |
|
| 93 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 94 |
+ 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace |
|
| 95 |
+ 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet |
|
| 96 |
+ 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose |
|
| 97 |
+ bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath |
|
| 98 |
+ |
|
| 99 |
+Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`: |
|
| 100 |
+ |
|
| 101 |
+ $ docker ps --filter ancestor=ubuntu-c1 |
|
| 102 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 103 |
+ 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace |
|
| 104 |
+ |
|
| 105 |
+Match containers based on the `ubuntu` version `12.04.5` image: |
|
| 106 |
+ |
|
| 107 |
+ $ docker ps --filter ancestor=ubuntu:12.04.5 |
|
| 108 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 109 |
+ 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose |
|
| 110 |
+ |
|
| 111 |
+The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer |
|
| 112 |
+in it's layer stack. |
|
| 113 |
+ |
|
| 114 |
+ $ docker ps --filter ancestor=d0e008c6cf02 |
|
| 115 |
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
|
| 116 |
+ 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose |
|
| 117 |
+ |
|
| 63 | 118 |
|
| 64 | 119 |
## Formatting |
| 65 | 120 |
|