Merge pull request #133 from thaJeztah/cli-docs-cherry-picks

[17.06] CLI reference docs cherry-picks (and 1 completion fix)
2017-07-26 16:18:23 -07:00
parent 903138e5fc a0a268737c
commit eafd4433aa
8 changed files with 133 additions and 32 deletions
@@ -3195,6 +3195,7 @@ _docker_service_update() {
 # and `docker service update`
 _docker_service_update_and_create() {
 	local options_with_args="
+		--credential-spec
 		--endpoint-mode
 		--entrypoint
 		--env -e
@@ -138,7 +138,7 @@ be UPPERCASE to distinguish them from arguments more easily.
 Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must
 start with a \`FROM\` instruction**. The `FROM` instruction specifies the [*Base
 Image*](glossary.md#base-image) from which you are building. `FROM` may only be
-proceeded by one or more `ARG` instructions, which declare arguments that are used
+preceded by one or more `ARG` instructions, which declare arguments that are used
 in `FROM` lines in the `Dockerfile`.

 Docker treats lines that *begin* with `#` as a comment, unless the line is
@@ -499,7 +499,7 @@ valid `Dockerfile` must start with a `FROM` instruction. The image can be
 any valid image – it is especially easy to start by **pulling an image** from 
 the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/).

- `ARG` is the only instruction that may proceed `FROM` in the `Dockerfile`. 
+- `ARG` is the only instruction that may precede `FROM` in the `Dockerfile`.
  See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact).

 - `FROM` can appear multiple times within a single `Dockerfile` to 
@@ -530,15 +530,16 @@ FROM extras:${CODE_VERSION}
 CMD  /code/run-extras
 ```

-To use the default value of an `ARG` declared before the first `FROM` use an
-`ARG` instruction without a value:
+An `ARG` declared before a `FROM` is outside of a build stage, so it
+can't be used in any instruction after a `FROM`. To use the default value of
+an `ARG` declared before the first `FROM` use an `ARG` instruction without
+a value inside of a build stage:

 ```Dockerfile
-ARG  SETTINGS=default
-
-FROM busybox
-ARG  SETTINGS
-
+ARG VERSION=latest
+FROM busybox:$VERSION
+ARG VERSION
+RUN echo $VERSION > image_version
 ```

 ## RUN
@@ -1364,8 +1365,8 @@ defined in the Dockerfile, the build outputs a warning.
 [Warning] One or more build-args [foo] were not consumed.
 ```

-The Dockerfile author can define a single variable by specifying `ARG` once or many
-variables by specifying `ARG` more than once. For example, a valid Dockerfile:
+A Dockerfile may include one or more `ARG` instructions. For example,
+the following is a valid Dockerfile:

 ```
 FROM busybox
@@ -1374,7 +1375,13 @@ ARG buildno
 ...
 ```

-A Dockerfile author may optionally specify a default value for an `ARG` instruction:
+> **Warning:** It is not recommended to use build-time variables for
+>  passing secrets like github keys, user credentials etc. Build-time variable
+>  values are visible to any user of the image with the `docker history` command.
+
+### Default values
+
+An `ARG` instruction can optionally include a default value:

 ```
 FROM busybox
@@ -1383,8 +1390,10 @@ ARG buildno=1
 ...
 ```

-If an `ARG` value has a default and if there is no value passed at build-time, the
-builder uses the default.
+If an `ARG` instruction has a default value and if there is no value passed
+at build-time, the builder uses the default.
+
+### Scope

 An `ARG` variable definition comes into effect from the line on which it is
 defined in the `Dockerfile` not from the argument's use on the command-line or
@@ -1408,9 +1417,21 @@ subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is
 defined and the `what_user` value was passed on the command line. Prior to its definition by an
 `ARG` instruction, any use of a variable results in an empty string.

-> **Warning:** It is not recommended to use build-time variables for
->  passing secrets like github keys, user credentials etc. Build-time variable
->  values are visible to any user of the image with the `docker history` command.
+An `ARG` instruction goes out of scope at the end of the build
+stage where it was defined. To use an arg in multiple stages, each stage must
+include the `ARG` instruction.
+
+```
+FROM busybox
+ARG SETTINGS
+RUN ./run/setup $SETTINGS
+
+FROM busybox
+ARG SETTINGS
+RUN ./run/other $SETTINGS
+```
+
+### Using ARG variables

 You can use an `ARG` or an `ENV` instruction to specify variables that are
 available to the `RUN` instruction. Environment variables defined using the
@@ -1459,6 +1480,8 @@ from the command line and persist them in the final image by leveraging the
 `ENV` instruction. Variable expansion is only supported for [a limited set of
 Dockerfile instructions.](#environment-replacement)

+### Predefined ARGs
+
 Docker has a set of predefined `ARG` variables that you can use without a
 corresponding `ARG` instruction in the Dockerfile.

@@ -28,6 +28,7 @@ container source to stdout.

 Options:
  -L, --follow-link   Always follow symbol link in SRC_PATH
+  -a, --archive       Archive mode (copy all uid/gid information)
      --help          Print usage
 ```

@@ -53,7 +54,9 @@ copied recursively with permissions preserved if possible. Ownership is set to
 the user and primary group at the destination. For example, files copied to a
 container are created with `UID:GID` of the root user. Files copied to the local
 machine are created with the `UID:GID` of the user which invoked the `docker cp`
-command.  If you specify the `-L` option, `docker cp` follows any symbolic link
+command. However, if you specify the `-a` option, `docker cp` sets the ownership
+to the user and primary group at the source.
+If you specify the `-L` option, `docker cp` follows any symbolic link
 in the `SRC_PATH`.  `docker cp` does *not* create parent directories for
 `DEST_PATH` if they do not exist.

@@ -80,9 +80,9 @@ Docker images report the following events:

 Docker plugins report the following events:

- `install`
 - `enable`
 - `disable`
+- `install`
 - `remove`

 #### Volumes
@@ -90,9 +90,9 @@ Docker plugins report the following events:
 Docker volumes report the following events:

 - `create`
+- `destroy`
 - `mount`
 - `unmount`
- `destroy`

 #### Networks

@@ -100,8 +100,9 @@ Docker networks report the following events:

 - `create`
 - `connect`
- `disconnect`
 - `destroy`
+- `disconnect`
+- `remove`

 #### Daemons

@@ -109,6 +110,38 @@ Docker daemons report the following events:

 - `reload`

+#### Services
+
+Docker services report the following events:
+
+- `create`
+- `remove`
+- `update`
+
+#### Nodes
+
+Docker nodes report the following events:
+
+- `create`
+- `remove`
+- `update`
+
+#### Secrets
+
+Docker secrets report the following events:
+
+- `create`
+- `remove`
+- `update`
+
+#### Configs
+
+Docker configs report the following events:
+
+- `create`
+- `remove`
+- `update`
+
 ### Limiting, filtering, and formatting the output

 #### Limit events by time
@@ -149,7 +182,8 @@ The currently supported filters are:
 * label (`label=<key>` or `label=<key>=<value>`)
 * network (`network=<name or id>`)
 * plugin (`plugin=<name or id>`)
-* type (`type=<container or image or volume or network or daemon or plugin>`)
+* scope (`scope=<local or swarm>`)
+* type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
 * volume (`volume=<name or id>`)

 #### Format
@@ -317,6 +351,29 @@ $ docker events --filter 'type=plugin'

 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
+
+$ docker events -f type=service
+
+2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
+2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
+
+$ docker events -f type=node
+
+2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown)
+
+$ docker events -f type=secret
+
+2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
+2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
+
+$  docker events -f type=config
+2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
+2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
+
+$ docker events --filter 'scope=swarm'
+
+2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson)
+2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret)
 ```

 ### Format the output
@@ -94,7 +94,6 @@ radial/busyboxplus   Full-chain, Internet enabled, busybox made from scratch. Co
 The flag `--limit` is the maximum number of results returned by a search. This value could
 be in the range between 1 and 100. The default value of `--limit` is 25.

-
 ### Filtering

 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
@@ -103,9 +102,8 @@ than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bi
 The currently supported filters are:

 * stars (int - number of stars the image has)
-* is-automated (true|false) - is the image automated or not
-* is-official (true|false) - is the image official or not
-
+* is-automated (boolean - true or false) - is the image automated or not
+* is-official (boolean - true or false) - is the image official or not

 #### stars

@@ -121,7 +119,6 @@ progrium/busybox                                                     50
 radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
 ```

-
 #### is-automated

 This example displays images with a name containing 'busybox'
@@ -23,6 +23,7 @@ Create a new service
 Options:
      --constraint list                    Placement constraints
      --container-label list               Container labels
+      --credential-spec                    Credential spec for managed service account (Windows only)
  -d, --detach                             Exit immediately instead of waiting for the service to converge (default true)
      --dns list                           Set custom DNS servers
      --dns-option list                    Set DNS options
@@ -779,6 +780,24 @@ $ docker service create --name dns-cache -p 53:53/tcp -p 53:53/udp dns-cache
 $ docker service create --name dns-cache -p 53:53/udp dns-cache
 ```

+### Provide credential specs for managed service accounts (Windows only)
+
+This option is only used for services using Windows containers. The
+`--credential-spec` must be in the format `file://<filename>` or
+`registry://<value-name>`.
+
+When using the `file://<filename>` format, the referenced file must be
+present in the `CredentialSpecs` subdirectory in the docker data directory,
+which defaults to `C:\ProgramData\Docker\` on Windows. For example,
+specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`.
+
+When using the `registry://<value-name>` format, the credential spec is
+read from the Windows registry on the daemon's host. The specified
+registry value must be located in:
+
+    HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs
+
+
 ### Create services using templates

 You can use templates for some flags of `service create`, using the syntax
@@ -26,6 +26,7 @@ Options:
      --constraint-rm list                 Remove a constraint
      --container-label-add list           Add or update a container label
      --container-label-rm list            Remove a container label by its key
+      --credential-spec                    Credential spec for managed service account (Windows only)
  -d, --detach                             Exit immediately instead of waiting for the service to converge (default true)
      --dns-add list                       Add or update a custom DNS server
      --dns-option-add list                Add or update a DNS option
@@ -168,11 +168,11 @@ Valid placeholders for the Go template are listed below:

 Placeholder   | Description
 --------------|------------------------------------------------------------------------------------------
-`.Name`       | Network name
-`.Driver`     | Network driver
-`.Scope`      | Network scope (local, global)
-`.Mountpoint` | Whether the network is internal or not.
-`.Labels`     | All labels assigned to the volume.
+`.Name`       | Volume name
+`.Driver`     | Volume driver
+`.Scope`      | Volume scope (local, global)
+`.Mountpoint` | The mount point of the volume on the host
+`.Labels`     | All labels assigned to the volume
 `.Label`      | Value of a specific label for this volume. For example `{{.Label "project.version"}}`

 When using the `--format` option, the `volume ls` command will either