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 7a46efa3ae..cf25487fdd 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 3a92bdbb5d..24c9b9038b 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 756b2b4099..0fbe07fbe2 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 09d7d21c49..6a9bbd5459 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 1b9921c1bf..c7f48fdd17 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 4d35b1ec40..66c6b6704b 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 66068ff644..e47bb38db1 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