Merge pull request #32481 from yongtang/30740-docs-prune-label

Update docs of `label` filter for `docker system prune`

api/swagger.yaml

@@ -4399,6 +4399,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:
@@ -5089,6 +5090,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:
@@ -6192,6 +6194,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:
@@ -6560,6 +6563,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:

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
 

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

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

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:
 

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)

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)