diff --git a/components/cli/contrib/completion/bash/docker b/components/cli/contrib/completion/bash/docker index cc95639b709..b20a6bf7e77 100644 --- a/components/cli/contrib/completion/bash/docker +++ b/components/cli/contrib/completion/bash/docker @@ -3046,6 +3046,7 @@ _docker_service_update() { # and `docker service update` _docker_service_update_and_create() { local options_with_args=" + --credential-spec --endpoint-mode --entrypoint --env -e diff --git a/components/cli/docs/reference/builder.md b/components/cli/docs/reference/builder.md index d6274407e61..16c1b48d319 100644 --- a/components/cli/docs/reference/builder.md +++ b/components/cli/docs/reference/builder.md @@ -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. diff --git a/components/cli/docs/reference/commandline/cp.md b/components/cli/docs/reference/commandline/cp.md index 5cbbee25ae0..8b067f22cd1 100644 --- a/components/cli/docs/reference/commandline/cp.md +++ b/components/cli/docs/reference/commandline/cp.md @@ -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. diff --git a/components/cli/docs/reference/commandline/events.md b/components/cli/docs/reference/commandline/events.md index 71475b43ec1..65b4f290136 100644 --- a/components/cli/docs/reference/commandline/events.md +++ b/components/cli/docs/reference/commandline/events.md @@ -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=` or `label==`) * network (`network=`) * plugin (`plugin=`) -* type (`type=`) +* scope (`scope=`) +* type (`type=`) * volume (`volume=`) #### 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 diff --git a/components/cli/docs/reference/commandline/search.md b/components/cli/docs/reference/commandline/search.md index f645c786030..83a44251ddc 100644 --- a/components/cli/docs/reference/commandline/search.md +++ b/components/cli/docs/reference/commandline/search.md @@ -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' diff --git a/components/cli/docs/reference/commandline/service_create.md b/components/cli/docs/reference/commandline/service_create.md index a1b6d18f9dd..d09a6bf8e6f 100644 --- a/components/cli/docs/reference/commandline/service_create.md +++ b/components/cli/docs/reference/commandline/service_create.md @@ -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://` or +`registry://`. + +When using the `file://` 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://` 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 diff --git a/components/cli/docs/reference/commandline/service_update.md b/components/cli/docs/reference/commandline/service_update.md index 93c5750eeef..8f075d2c19f 100644 --- a/components/cli/docs/reference/commandline/service_update.md +++ b/components/cli/docs/reference/commandline/service_update.md @@ -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 diff --git a/components/cli/docs/reference/commandline/volume_ls.md b/components/cli/docs/reference/commandline/volume_ls.md index 713922d60fe..6a6e85225cc 100644 --- a/components/cli/docs/reference/commandline/volume_ls.md +++ b/components/cli/docs/reference/commandline/volume_ls.md @@ -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