From aad95ccba97e0e8e4c405f1766a485ea597395e6 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Wed, 22 Mar 2017 10:06:50 +0100 Subject: [PATCH] Merge pull request #31749 from yallop/docs-31047 Add documentation for bind mount consistency flags (#31047). (cherry picked from commit 94394026a8c6d99e13d7fb369698e2673ebfc722) Signed-off-by: Sebastiaan van Stijn --- api/swagger.yaml | 3 +++ docs/api/version-history.md | 1 + docs/reference/commandline/create.md | 3 ++- docs/reference/commandline/run.md | 3 ++- docs/reference/commandline/service_create.md | 15 ++++++++++++++- man/docker-run.1.md | 10 +++++++--- man/src/container/create.md | 9 ++++++--- 7 files changed, 35 insertions(+), 9 deletions(-) diff --git a/api/swagger.yaml b/api/swagger.yaml index 7a46efa3ae7509ac75254203626c5865d7bf12bc..cf25487fdd78b7165369ca58204244197e7f3fde 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -244,6 +244,9 @@ definitions: ReadOnly: description: "Whether the mount should be read-only." type: "boolean" + Consistency: + description: "The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`." + type: "string" BindOptions: description: "Optional configuration for the `bind` type." type: "object" diff --git a/docs/api/version-history.md b/docs/api/version-history.md index 3a92bdbb5d75a0dcc3b6de9c12e3c7a8d7a75e02..24c9b9038b8804aefb91ad03b5e4db25c7144aa2 100644 --- a/docs/api/version-history.md +++ b/docs/api/version-history.md @@ -18,6 +18,7 @@ keywords: "API, Docker, rcli, REST, documentation" [Docker Engine API v1.28](https://docs.docker.com/engine/api/v1.28/) documentation +* `POST /containers/create` now includes a `Consistency` field to specify the consistency level for each `Mount`, with possible values `default`, `consistent`, `cached`, or `delegated`. * `GET /containers/create` now takes a `DeviceCgroupRules` field in `HostConfig` allowing to set custom device cgroup rules for the created container. * Optional query parameter `verbose` for `GET /networks/(id or name)` will now list all services with all the tasks, including the non-local tasks on the given network. * `GET /containers/(id or name)/attach/ws` now returns WebSocket in binary frame format for API version >= v1.28, and returns WebSocket in text frame format for API version< v1.28, for the purpose of backward-compatibility. diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index 756b2b4099e89f51e3e8fda914d35312df23539e..0fbe07fbe2f046825678ba706ca5ee00bb883c45 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -126,7 +126,8 @@ Options: -v, --volume value Bind mount a volume (default []). The format is `[host-src:]container-dest[:]`. The comma-delimited `options` are [rw|ro], - [z|Z], [[r]shared|[r]slave|[r]private], and + [z|Z], [[r]shared|[r]slave|[r]private], + [delegated|cached|consistent], and [nocopy]. The 'host-src' is an absolute path or a name value. --volume-driver string Optional volume driver for the container diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 09d7d21c49563c5d1aef1d37c59ceb49f372eafc..6a9bbd54595251e69029446012929a2336e896a4 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -137,7 +137,8 @@ Options: -v, --volume value Bind mount a volume (default []). The format is `[host-src:]container-dest[:]`. The comma-delimited `options` are [rw|ro], - [z|Z], [[r]shared|[r]slave|[r]private], and + [z|Z], [[r]shared|[r]slave|[r]private], + [delegated|cached|consistent], and [nocopy]. The 'host-src' is an absolute path or a name value. --volume-driver string Optional volume driver for the container diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index 1b9921c1bf8933278ef84aa08d2726d3f884533b..c7f48fdd179717632bc8b989480b7341cc010a85 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -320,9 +320,22 @@ volumes in a service:

+ + consistency + + +

The consistency requirements for the mount; one of +

    +
  • default: Equivalent to consistent.
    • +
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
    • +
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
    • +
  • delegated: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are are visible on the host.
    • +
+

+ + - #### Bind Propagation Bind propagation refers to whether or not mounts created within a given diff --git a/man/docker-run.1.md b/man/docker-run.1.md index 4d35b1ec4091bcbf1ca1eb8b7d73dfebaa6a16f0..66c6b6704bccb63e95bde03d133f43d6a03ed277 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -625,6 +625,7 @@ any options, the systems uses the following options: * [rw|ro] * [z|Z] * [`[r]shared`|`[r]slave`|`[r]private`] + * [`delegated`|`cached`|`consistent`] * [nocopy] The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR` @@ -642,9 +643,12 @@ You can specify multiple **-v** options to mount one or more mounts to a container. To use these same mounts in other containers, specify the **--volumes-from** option also. -You can add `:ro` or `:rw` suffix to a volume to mount it read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. -See examples. +You can supply additional options for each bind-mount following an additional +colon. A `:ro` or `:rw` suffix mounts a volume in read-only or read-write +mode, respectively. By default, volumes are mounted in read-write mode. +You can also specify the consistency requirement for the mount, either +`:consistent` (the default), `:cached`, or `:delegated`. Multiple options are +separated by commas, e.g. `:ro,cached`. Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might diff --git a/man/src/container/create.md b/man/src/container/create.md index 66068ff64407d0551770836c36e0b2979522de8e..e47bb38db1e85e54e23a7d87f4236dafed20f462 100644 --- a/man/src/container/create.md +++ b/man/src/container/create.md @@ -23,9 +23,12 @@ You can specify multiple **-v** options to mount one or more mounts to a container. To use these same mounts in other containers, specify the **--volumes-from** option also. -You can add `:ro` or `:rw` suffix to a volume to mount it read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. -See examples. +You can supply additional options for each bind-mount following an additional +colon. A `:ro` or `:rw` suffix mounts a volume in read-only or read-write +mode, respectively. By default, volumes are mounted in read-write mode. +You can also specify the consistency requirement for the mount, either +`:consistent` (the default), `:cached`, or `:delegated`. Multiple options are +separated by commas, e.g. `:ro,cached`. Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might