Documentation for bind mount consistency flags.

Signed-off-by: Jeremy Yallop <yallop@docker.com>

api/swagger.yaml

@@ -245,6 +245,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"

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.

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[:<options>]`.
                                     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

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[:<options>]`.
                                     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

docs/reference/commandline/service_create.md

@@ -320,9 +320,22 @@ volumes in a service:
       </ul></p>
     </td>
   </tr>
+  <tr>
+    <td><b>consistency</b></td>
+    <td></td>
+    <td>
+      <p>The consistency requirements for the mount; one of
+         <ul>
+           <li><tt>default</tt>: Equivalent to <tt>consistent</tt>.</li>
+           <li><tt>consistent</tt>: Full consistency.  The container runtime and the host maintain an identical view of the mount at all times.</li>
+           <li><tt>cached</tt>: The host's view of the mount is authoritative.  There may be delays before updates made on the host are visible within a container.</li>
+           <li><tt>delegated</tt>: 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.</li>
+        </ul>
+     </p>
+    </td>
+  </tr>
 </table>
 
-
 #### Bind Propagation
 
 Bind propagation refers to whether or not mounts created within a given

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

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