Update docs of label filter for docker system prune

This fix updates docs of `label` filter for `docker system prune`. This fix is related to #30740 and #29999, and specifically to comment https://github.com/docker/docker/pull/30740#issuecomment-293012957. Signed-off-by: Yong Tang <yong.tang.github@outlook.com>
2017-04-10 11:08:40 -07:00 · 2017-04-10 11:08:40 -07:00 · 5b0ab45a1e
commit 5b0ab45a1e
parent 9d4a8cda6b
7 changed files with 47 additions and 2 deletions
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@ -4393,6 +4393,7 @@ paths:

            Available filters:
            - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
+            - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels.
          type: "string"
      responses:
        200:
@ -5083,6 +5084,7 @@ paths:
               unused *and* untagged images. When set to `false`
               (or `0`), all unused images are pruned.
            - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
+            - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels.
          type: "string"
      responses:
        200:
@ -6186,6 +6188,7 @@ paths:
            Filters to process on the prune list, encoded as JSON (a `map[string][]string`).

            Available filters:
+            - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
          type: "string"
      responses:
        200:
@ -6554,6 +6557,7 @@ paths:

            Available filters:
            - `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
+            - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels.
          type: "string"
      responses:
        200:
--- a/docs/api/version-history.md
+++ b/docs/api/version-history.md
@ -27,6 +27,7 @@ keywords: "API, Docker, rcli, REST, documentation"
 * `GET /networks/` now supports a `scope` filter to filter networks based on the network mode (`swarm`, `global`, or `local`).
 * `POST /containers/create`, `POST /service/create` and `POST /services/(id or name)/update` now takes the field `StartPeriod` as a part of the `HealthConfig` allowing for specification of a period during which the container should not be considered unhealthy even if health checks do not pass.
 * `GET /services/(id)` now accepts an `insertDefaults` query-parameter to merge default values into the service inspect output. 
+* `POST /containers/prune`, `POST /images/prune`, `POST /volumes/prune`, and `POST /networks/prune` now support a `label` filter to filter containers, images, volumes, or networks based on the label. The format of the label filter could be `label=<key>`/`label=<key>=<value>` to remove those with the specified labels, or `label!=<key>`/`label!=<key>=<value>` to remove those without the specified labels.

 ## v1.28 API changes

--- a/docs/reference/commandline/container_prune.md
+++ b/docs/reference/commandline/container_prune.md
@ -54,6 +54,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b
 The currently supported filters are:

 * until (`<timestamp>`) - only remove containers created before given timestamp
+* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove containers with (or without, in case `label!=...` is used) the specified labels.

 The `until` filter can be Unix timestamps, date formatted
 timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
@ -67,6 +68,11 @@ that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
 fraction of a second no more than nine digits long.

+The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`),
+which removes containers with the specified labels. The other
+format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
+containers without the specified labels.
+
 The following removes containers created more than 5 minutes ago:

 ```bash
--- a/docs/reference/commandline/image_prune.md
+++ b/docs/reference/commandline/image_prune.md
@ -76,6 +76,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b
 The currently supported filters are:

 * until (`<timestamp>`) - only remove images created before given timestamp
+* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove images with (or without, in case `label!=...` is used) the specified labels.

 The `until` filter can be Unix timestamps, date formatted
 timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
@ -89,6 +90,11 @@ that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
 fraction of a second no more than nine digits long.

+The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`),
+which removes images with the specified labels. The other
+format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
+images without the specified labels.
+
 The following removes images created before `2017-01-04T00:00:00`:

 ```bash
--- a/docs/reference/commandline/network_prune.md
+++ b/docs/reference/commandline/network_prune.md
@ -42,6 +42,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b
 The currently supported filters are:

 * until (`<timestamp>`) - only remove networks created before given timestamp
+* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove networks with (or without, in case `label!=...` is used) the specified labels.

 The `until` filter can be Unix timestamps, date formatted
 timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
@ -55,6 +56,11 @@ that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
 fraction of a second no more than nine digits long.

+The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`),
+which removes networks with the specified labels. The other
+format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
+networks without the specified labels.
+
 The following removes networks created more than 5 minutes ago. Note that
 system networks such as `bridge`, `host`, and `none` will never be pruned:

--- a/docs/reference/commandline/system_prune.md
+++ b/docs/reference/commandline/system_prune.md
@ -76,6 +76,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b
 The currently supported filters are:

 * until (`<timestamp>`) - only remove containers, images, and networks created before given timestamp
+* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove containers, images, networks, and volumes with (or without, in case `label!=...` is used) the specified labels.

 The `until` filter can be Unix timestamps, date formatted
 timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
@ -89,6 +90,11 @@ that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
 fraction of a second no more than nine digits long.

+The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`),
+which removes containers, images, networks, and volumes with the specified labels. The other
+format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
+containers, images, networks, and volumes without the specified labels.
+
 ## Related commands

 * [volume create](volume_create.md)
--- a/docs/reference/commandline/volume_prune.md
+++ b/docs/reference/commandline/volume_prune.md
@ -21,8 +21,9 @@ Usage:	docker volume prune [OPTIONS]
 Remove all unused volumes

 Options:
-  -f, --force   Do not prompt for confirmation
-      --help    Print usage
+      --filter filter   Provide filter values (e.g. 'label=<label>')
+  -f, --force           Do not prompt for confirmation
+      --help            Print usage
 ```

 ## Description
@ -43,6 +44,21 @@ my-named-vol
 Total reclaimed space: 36 B
 ```

+## Filtering
+
+The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
+than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
+
+The currently supported filters are:
+
+* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove volumes with (or without, in case `label!=...` is used) the specified labels.
+
+The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`),
+which removes volumes with the specified labels. The other
+format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
+volumes without the specified labels.
+
+
 ## Related commands

 * [volume create](volume_create.md)