Merge pull request #2957 from thaJeztah/20.10_backport_docs_fixes

[20.10 backport] documentation and completion-script fixes

Author: silvin-lubecki

contrib/completion/bash/docker

@@ -935,7 +935,7 @@ __docker_complete_log_options() {
 	# awslogs does not implement the $common_options2.
 	local awslogs_options="$common_options1 awslogs-create-group awslogs-credentials-endpoint awslogs-datetime-format awslogs-group awslogs-multiline-pattern awslogs-region awslogs-stream tag"
 
-	local fluentd_options="$common_options1 $common_options2 fluentd-address fluentd-async-connect fluentd-buffer-limit fluentd-retry-wait fluentd-max-retries fluentd-sub-second-precision tag"
+	local fluentd_options="$common_options1 $common_options2 fluentd-address fluentd-async fluentd-buffer-limit fluentd-request-ack fluentd-retry-wait fluentd-max-retries fluentd-sub-second-precision tag"
 	local gcplogs_options="$common_options1 $common_options2 gcp-log-cmd gcp-meta-id gcp-meta-name gcp-meta-zone gcp-project"
 	local gelf_options="$common_options1 $common_options2 gelf-address gelf-compression-level gelf-compression-type gelf-tcp-max-reconnect gelf-tcp-reconnect-delay tag"
 	local journald_options="$common_options1 $common_options2 tag"
@@ -1955,6 +1955,7 @@ _docker_container_run_and_create() {
 		--pid
 		--pids-limit
 		--publish -p
+		--pull
 		--restart
 		--runtime
 		--security-opt
@@ -2153,6 +2154,10 @@ _docker_container_run_and_create() {
 			esac
 			return
 			;;
+		--pull)
+		  COMPREPLY=( $( compgen -W 'always missing never' -- "$cur" ) )
+		  return
+		  ;;
 		--runtime)
 			__docker_complete_runtimes
 			return
@@ -2548,6 +2553,7 @@ _docker_daemon() {
 		--ip-forward=false
 		--ip-masq=false
 		--iptables=false
+		--ip6tables
 		--ipv6
 		--live-restore
 		--no-new-privileges
@@ -3601,7 +3607,7 @@ _docker_service_ls() {
 			return
 			;;
 		mode)
-			COMPREPLY=( $( compgen -W "global replicated" -- "${cur##*=}" ) )
+			COMPREPLY=( $( compgen -W "global global-job replicated replicated-job" -- "${cur##*=}" ) )
 			return
 			;;
 		name)
@@ -3731,6 +3737,7 @@ _docker_service_update_and_create() {
 		--limit-pids
 		--log-driver
 		--log-opt
+		--max-replicas
 		--replicas
 		--replicas-max-per-node
 		--reserve-cpu
@@ -3804,7 +3811,7 @@ _docker_service_update_and_create() {
 				return
 				;;
 			--mode)
-				COMPREPLY=( $( compgen -W "global replicated" -- "$cur" ) )
+				COMPREPLY=( $( compgen -W "global global-job replicated replicated-job" -- "$cur" ) )
 				return
 				;;
 		esac
@@ -4348,6 +4355,9 @@ _docker_node_ls() {
 			__docker_complete_nodes --cur "${cur##*=}" --id
 			return
 			;;
+		label|node.label)
+			return
+			;;
 		membership)
 			COMPREPLY=( $( compgen -W "accepted pending" -- "${cur##*=}" ) )
 			return
@@ -4364,7 +4374,7 @@ _docker_node_ls() {
 
 	case "$prev" in
 		--filter|-f)
-			COMPREPLY=( $( compgen -W "id label membership name role" -S = -- "$cur" ) )
+			COMPREPLY=( $( compgen -W "id label membership name node.label role" -S = -- "$cur" ) )
 			__docker_nospace
 			return
 			;;

contrib/completion/zsh/_docker

@@ -1343,7 +1343,7 @@ __docker_node_complete_ls_filters() {
                 ;;
         esac
     else
-        opts=('id' 'label' 'membership' 'name' 'role')
+        opts=('id' 'label' 'membership' 'name' 'node.label' 'role')
         _describe -t filter-opts "filter options" opts -qS "=" && ret=0
     fi
 
@@ -2544,6 +2544,82 @@ __docker_volume_subcommand() {
 
 # EO volume
 
+# BO context
+
+__docker_complete_contexts() {
+    [[ $PREFIX = -* ]] && return 1
+    integer ret=1
+    declare -a contexts
+
+    contexts=(${(f)${:-"$(_call_program commands docker $docker_options context ls -q)"$'\n'}})
+
+    _describe -t context-list "context" contexts && ret=0
+    return ret
+}
+
+__docker_context_commands() {
+    local -a _docker_context_subcommands
+    _docker_context_subcommands=(
+        "create:Create new context"
+        "inspect:Display detailed information on one or more contexts"
+        "list:List available contexts"
+        "rm:Remove one or more contexts"
+        "show:Print the current context"
+        "update:Update a context"
+        "use:Set the default context"
+    )
+    _describe -t docker-context-commands "docker context command" _docker_context_subcommands
+}
+
+__docker_context_subcommand() {
+    local -a _command_args opts_help
+    local expl help="--help"
+    integer ret=1
+
+    opts_help=("(: -)--help[Print usage]")
+
+    case "$words[1]" in
+        (create)
+            _arguments $(__docker_arguments) \
+                $opts_help \
+                "($help)--default-stack-orchestrator=[Default orchestrator for stack operations to use with this context]:default-stack-orchestrator:(swarm kubernetes all)" \
+                "($help)--description=[Description of the context]:description:" \
+                "($help)--docker=[Set the docker endpoint]:docker:" \
+                "($help)--kubernetes=[Set the kubernetes endpoint]:kubernetes:" \
+                "($help)--from=[Create context from a named context]:from:__docker_complete_contexts" \
+                "($help -):name: " && ret=0
+            ;;
+        (use)
+            _arguments $(__docker_arguments) \
+                $opts_help \
+                "($help -)1:context:__docker_complete_contexts" && ret=0
+            ;;
+        (inspect)
+            _arguments $(__docker_arguments) \
+                $opts_help \
+                "($help -)1:context:__docker_complete_contexts" && ret=0
+            ;;
+        (rm)
+            _arguments $(__docker_arguments) \
+                $opts_help \
+                "($help -)1:context:__docker_complete_contexts" && ret=0
+            ;;
+        (update)
+            _arguments $(__docker_arguments) \
+                $opts_help \
+                "($help)--default-stack-orchestrator=[Default orchestrator for stack operations to use with this context]:default-stack-orchestrator:(swarm kubernetes all)" \
+                "($help)--description=[Description of the context]:description:" \
+                "($help)--docker=[Set the docker endpoint]:docker:" \
+                "($help)--kubernetes=[Set the kubernetes endpoint]:kubernetes:" \
+                "($help -):name:" && ret=0
+            ;;
+    esac
+
+    return ret
+}
+
+# EO context
+
 __docker_caching_policy() {
   oldp=( "$1"(Nmh+1) )     # 1 hour
   (( $#oldp ))
@@ -2631,6 +2707,23 @@ __docker_subcommand() {
                     ;;
             esac
             ;;
+        (context)
+            local curcontext="$curcontext" state
+            _arguments $(__docker_arguments) \
+                $opts_help \
+                "($help -): :->command" \
+                "($help -)*:: :->option-or-argument" && ret=0
+
+            case $state in
+                (command)
+                    __docker_context_commands && ret=0
+                    ;;
+                (option-or-argument)
+                    curcontext=${curcontext%:*:*}:docker-${words[-1]}:
+                    __docker_context_subcommand && ret=0
+                    ;;
+            esac
+            ;;
         (daemon)
             _arguments $(__docker_arguments) \
                 $opts_help \

docs/deprecated.md

@@ -52,6 +52,7 @@ Status     | Feature
 -----------|------------------------------------------------------------------------------------------------------------------------------------|------------|------------
 Deprecated | [Pulling images from non-compliant image registries](#pulling-images-from-non-compliant-image-registries)                          | v20.10     | -
 Deprecated | [Linux containers on Windows (LCOW)](#linux-containers-on-windows-lcow-experimental)                                               | v20.10     | -
+Deprecated | [BLKIO weight options with cgroups v1](#blkio-weight-options–with-cgroups-v1)                                                      | v20.10     | -
 Deprecated | [Kernel memory limit](#kernel-memory-limit)                                                                                        | v20.10     | -
 Deprecated | [Classic Swarm and overlay networks using external key/value stores](#classic-swarm-and-overlay-networks-using-cluster-store)      | v20.10     | -
 Deprecated | [Support for the legacy `~/.dockercfg` configuration file for authentication](#support-for-legacy-dockercfg-configuration-files)   | v20.10     | -
@@ -140,6 +141,16 @@ now stopped in favor of running docker natively on Linux in WSL2.
 Developers who want to run Linux workloads on a Windows host are encouraged to use
 [Docker Desktop with WSL2](https://docs.docker.com/docker-for-windows/wsl/) instead.
 
+### BLKIO weight options with cgroups v1
+
+**Deprecated in Release: v20.10**
+
+Specifying blkio weight (`docker run --blkio-weight` and `docker run --blkio-weight-device`)
+is now marked as deprecated when using cgroups v1 because the corresponding features
+were [removed in Linux kernel v5.0 and up](https://github.com/torvalds/linux/commit/f382fb0bcef4c37dc049e9f6963e3baf204d815c).
+When using cgroups v2, the `--blkio-weight` options are implemented using
+[`io.weight](https://github.com/torvalds/linux/blob/v5.0/Documentation/admin-guide/cgroup-v2.rst#io).
+
 ### Kernel memory limit
 
 **Deprecated in Release: v20.10**

docs/reference/commandline/node_ls.md

@@ -60,6 +60,7 @@ The currently supported filters are:
 
 * [id](#id)
 * [label](#label)
+* [node.label](#nodelabel)
 * [membership](#membership)
 * [name](#name)
 * [role](#role)
@@ -77,7 +78,10 @@ ID                         HOSTNAME       STATUS  AVAILABILITY  MANAGER STATUS
 
 #### label
 
-The `label` filter matches nodes based on engine labels and on the presence of a `label` alone or a `label` and a value. Node labels are currently not used for filtering.
+The `label` filter matches nodes based on engine labels and on the presence of a
+`label` alone or a `label` and a value. Engine labels are configured in
+the [daemon configuration](dockerd.md#daemon-configuration-file). To filter on
+Swarm `node` labels, use [`node.label` instead](#nodelabel).
 
 The following filter matches nodes with the `foo` label regardless of its value.
 
@@ -88,6 +92,42 @@ ID                         HOSTNAME       STATUS  AVAILABILITY  MANAGER STATUS
 1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active
 ```
 
+#### node.label
+
+The `node.label` filter matches nodes based on node labels and on the presence
+of a `node.label` alone or a `node.label` and a value.
+
+The following filter updates nodes to have a `region` node label:
+
+```console
+$ docker node update --label-add region=region-a swarm-test-01
+$ docker node update --label-add region=region-a swarm-test-02
+$ docker node update --label-add region=region-b swarm-test-03
+$ docker node update --label-add region=region-b swarm-test-04
+```
+
+Show all nodes that have a `region` node label set:
+
+```console
+$ docker node ls --filter node.label=region
+
+ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
+yg550ettvsjn6g6t840iaiwgb *   swarm-test-01   Ready     Active         Leader           20.10.2
+2lm9w9kbepgvkzkkeyku40e65     swarm-test-02   Ready     Active         Reachable        20.10.2
+hc0pu7ntc7s4uvj4pv7z7pz15     swarm-test-03   Ready     Active         Reachable        20.10.2
+n41b2cijmhifxxvz56vwrs12q     swarm-test-04   Ready     Active                          20.10.2
+```
+
+Show all nodes that have a `region` node label, with value `region-a`:
+
+```console
+$ docker node ls --filter node.label=region=region-a
+
+ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
+yg550ettvsjn6g6t840iaiwgb *   swarm-test-01   Ready     Active         Leader           20.10.2
+2lm9w9kbepgvkzkkeyku40e65     swarm-test-02   Ready     Active         Reachable        20.10.2
+```
+
 #### membership
 
 The `membership` filter matches nodes based on the presence of a `membership` and a value

docs/reference/commandline/push.md

@@ -76,7 +76,7 @@ listed.
 
 ### Push all tags of an image
 
-Use the `-a` (or `--all-tags`) option to push To push all tags of a local image.
+Use the `-a` (or `--all-tags`) option to push all tags of a local image.
 
 The following example creates multiple tags for an image, and pushes all those
 tags to Docker Hub.

docs/reference/run.md

@@ -1,6 +1,8 @@
 ---
 description: "Configure containers at runtime"
 keywords: "docker, run, configure, runtime"
+redirect_from:
+- /reference/run/
 ---
 
 <!-- This file is maintained within the docker/cli GitHub
@@ -1738,7 +1740,7 @@ volume mounted on the host).
 
 The `container-dest` must always be an absolute path such as `/src/docs`.
 The `host-src` can either be an absolute path or a `name` value. If you
-supply an absolute path for the `host-dir`, Docker bind-mounts to the path
+supply an absolute path for the `host-src`, Docker bind-mounts to the path
 you specify. If you supply a `name`, Docker creates a named volume by that `name`.
 
 A `name` value must start with an alphanumeric character,

man/docker-run.1.md

@@ -504,13 +504,13 @@ and foreground Docker containers.
 **--network**=*type*
    Set the Network mode for the container. Supported values are:
 
-| Value                       | Description                                                                              |
-|:----------------------------|:-----------------------------------------------------------------------------------------|
-| **none**                    | No networking in the container.                                                          |
-| **bridge**                  | Connect the container to the default Docker bridge via veth interfaces.                  |
-| **host**                    | Use the host's network stack inside the container.                                       |
-| **container:**_name_|_id_   | Use the network stack of another container, specified via its _name_ or _id_.            |
-| _network-name_|_network-id_ | Connects the container to a user created network (using `docker network create` command) |
+| Value                        | Description                                                                              |
+|:-----------------------------|:-----------------------------------------------------------------------------------------|
+| **none**                     | No networking in the container.                                                          |
+| **bridge**                   | Connect the container to the default Docker bridge via veth interfaces.                  |
+| **host**                     | Use the host's network stack inside the container.                                       |
+| **container:**_name_\|_id_   | Use the network stack of another container, specified via its _name_ or _id_.            |
+| _network-name_\|_network-id_ | Connects the container to a user created network (using `docker network create` command) |
 
 Default is **bridge**.