|
|
@@ -137,13 +137,183 @@ $ docker service create \
|
|
|
For more information about labels, refer to [apply custom
|
|
|
metadata](../../userguide/labels-custom-metadata.md).
|
|
|
|
|
|
+### Add bind-mounts or volumes
|
|
|
+
|
|
|
+Docker supports two different kinds of mounts, which allow containers to read to
|
|
|
+or write from files or directories on other containers or the host operating
|
|
|
+system. These types are _data volumes_ (often referred to simply as volumes) and
|
|
|
+_bind-mounts_.
|
|
|
+
|
|
|
+A **bind-mount** makes a file or directory on the host available to the
|
|
|
+container it is mounted within. A bind-mount may be either read-only or
|
|
|
+read-write. For example, a container might share its host's DNS information by
|
|
|
+means of a bind-mount of the host's `/etc/resolv.conf` or a container might
|
|
|
+write logs to its host's `/var/log/myContainerLogs` directory. If you use
|
|
|
+bind-mounts and your host and containers have different notions of permissions,
|
|
|
+access controls, or other such details, you will run into portability issues.
|
|
|
+
|
|
|
+A **named volume** is a mechanism for decoupling persistent data needed by your
|
|
|
+container from the image used to create the container and from the host machine.
|
|
|
+Named volumes are created and managed by Docker, and a named volume persists
|
|
|
+even when no container is currently using it. Data in named volumes can be
|
|
|
+shared between a container and the host machine, as well as between multiple
|
|
|
+containers. Docker uses a _volume driver_ to create, manage, and mount volumes.
|
|
|
+You can back up or restore volumes using Docker commands.
|
|
|
+
|
|
|
+Consider a situation where your image starts a lightweight web server. You could
|
|
|
+use that image as a base image, copy in your website's HTML files, and package
|
|
|
+that into another image. Each time your website changed, you'd need to update
|
|
|
+the new image and redeploy all of the containers serving your website. A better
|
|
|
+solution is to store the website in a named volume which is attached to each of
|
|
|
+your web server containers when they start. To update the website, you just
|
|
|
+update the named volume.
|
|
|
+
|
|
|
+For more information about named volumes, see
|
|
|
+[Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/).
|
|
|
+
|
|
|
+The following table describes options which apply to both bind-mounts and named
|
|
|
+volumes in a service:
|
|
|
+
|
|
|
+| Option | Required | Description
|
|
|
+|:-----------------------------------------|:--------------------------|:-----------------------------------------------------------------------------------------
|
|
|
+| **type** | | The type of mount, can be either `volume`, or `bind`. Defaults to `volume` if no type is specified.<ul><li>`volume`: mounts a [managed volume](volume_create.md) into the container.</li><li>`bind`: bind-mounts a directory or file from the host into the container.</li></ul>
|
|
|
+| **src** or **source** | for `type=bind` only | <ul><li>`type=volume`: `src` is an optional way to specify the name of the volume (for example, `src=my-volume`). If the named volume does not exist, it is automatically created. If no `src` is specified, the volume is assigned a random name which is guaranteed to be unique on the host, but may not be unique cluster-wide. A randomly-named volume has the same lifecycle as its container and is destroyed when the *container* is destroyed (which is upon `service update`, or when scaling or re-balancing the service).</li><li>`type=bind`: `src` is required, and specifies an absolute path to the file or directory to bind-mount (for example, `src=/path/on/host/`). An error is produced if the file or directory does not exist.</li></ul>
|
|
|
+| **dst** or **destination** or **target** | yes | Mount path inside the container, for example `/some/path/in/container/`. If the path does not exist in the container's filesystem, the Engine creates a directory at the specified location before mounting the volume or bind-mount.
|
|
|
+| **readonly** or **ro** | | The Engine mounts binds and volumes `read-write` unless `readonly` option is given when mounting the bind or volume.<br /><br /><ul><li>`true` or `1` or no value: Mounts the bind or volume read-only.</li><li>`false` or `0`: Mounts the bind or volume read-write.</li></ul>
|
|
|
+
|
|
|
+#### Bind Propagation
|
|
|
+
|
|
|
+Bind propagation refers to whether or not mounts created within a given
|
|
|
+bind-mount or named volume can be propagated to replicas of that mount. Consider
|
|
|
+a mount point `/mnt`, which is also mounted on `/tmp`. The propation settings
|
|
|
+control whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each
|
|
|
+propagation setting has a recursive counterpoint. In the case of recursion,
|
|
|
+consider that `/tmp/a` is also mounted as `/foo`. The propagation settings
|
|
|
+control whether `/mnt/a` and/or `/tmp/a` would exist.
|
|
|
+
|
|
|
+The `bind-propagation` option defaults to `rprivate` for both bind-mounts and
|
|
|
+volume mounts, and is only configurable for bind-mounts. In other words, named
|
|
|
+volumes do not support bind propagation.
|
|
|
+
|
|
|
+- **`shared`**: Sub-mounts of the original mount are exposed to replica mounts,
|
|
|
+ and sub-mounts of replica mounts are also propagated to the
|
|
|
+ original mount.
|
|
|
+- **`slave`**: similar to a shared mount, but only in one direction. If the
|
|
|
+ original mount exposes a sub-mount, the replica mount can see it.
|
|
|
+ However, if the replica mount exposes a sub-mount, the original
|
|
|
+ mount cannot see it.
|
|
|
+- **`private`**: The mount is private. Sub-mounts within it are not exposed to
|
|
|
+ replica mounts, and sub-mounts of replica mounts are not
|
|
|
+ exposed to the original mount.
|
|
|
+- **`rshared`**: The same as shared, but the propagation also extends to and from
|
|
|
+ mount points nested within any of the original or replica mount
|
|
|
+ points.
|
|
|
+- **`rslave`**: The same as `slave`, but the propagation also extends to and from
|
|
|
+ mount points nested within any of the original or replica mount
|
|
|
+ points.
|
|
|
+- **`rprivate`**: The default. The same as `private`, meaning that no mount points
|
|
|
+ anywhere within the original or replica mount points propagate
|
|
|
+ in either direction.
|
|
|
+
|
|
|
+For more information about bind propagation, see the
|
|
|
+[Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt).
|
|
|
+
|
|
|
+#### Options for Named Volumes
|
|
|
+The following options can only be used for named volumes (`type=volume`);
|
|
|
+
|
|
|
+| Option | Description
|
|
|
+|:----------------------|:--------------------------------------------------------------------------------------------------------------------
|
|
|
+| **volume-driver** | Name of the volume-driver plugin to use for the volume. Defaults to ``"local"``, to use the local volume driver to create the volume if the volume does not exist.
|
|
|
+| **volume-label** | One or more custom metadata ("labels") to apply to the volume upon creation. For example, `volume-label=mylabel=hello-world,my-other-label=hello-mars`. For more information about labels, refer to [apply custom metadata](../../userguide/labels-custom-metadata.md).
|
|
|
+| **volume-nocopy** | By default, if you attach an empty volume to a container, and files or directories already existed at the mount-path in the container (`dst`), the Engine copies those files and directories into the volume, allowing the host to access them. Set `volume-nocopy` to disables copying files from the container's filesystem to the volume and mount the empty volume.<br /><br />A value is optional:<ul><li>`true` or `1`: Default if you do not provide a value. Disables copying.</li><li>`false` or `0`: Enables copying.</li></ul>
|
|
|
+| **volume-opt** | Options specific to a given volume driver, which will be passed to the driver when creating the volume. Options are provided as a comma-separated list of key/value pairs, for example, `volume-opt=some-option=some-value,some-other-option=some-other-value`. For available options for a given driver, refer to that driver's documentation.
|
|
|
+
|
|
|
+#### Differences between "--mount" and "--volume"
|
|
|
+
|
|
|
+The `--mount` flag supports most options that are supported by the `-v`
|
|
|
+or `--volume` flag for `docker run`, with some important exceptions:
|
|
|
+
|
|
|
+- The `--mount` flag allows you to specify a volume driver and volume driver
|
|
|
+ options *per volume*, without creating the volumes in advance. In contrast,
|
|
|
+ `docker run` allows you to specify a single volume driver which is shared
|
|
|
+ by all volumes, using the `--volume-driver` flag.
|
|
|
+
|
|
|
+- The `--mount` flag allows you to specify custom metadata ("labels") for a volume,
|
|
|
+ before the volume is created.
|
|
|
+
|
|
|
+- When you use `--mount` with `type=bind`, the host-path must refer to an *existing*
|
|
|
+ path on the host. The path will not be created for you and the service will fail
|
|
|
+ with an error if the path does not exist.
|
|
|
+
|
|
|
+- The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags,
|
|
|
+ which are used for `selinux` labeling.
|
|
|
+
|
|
|
+#### Create a service using a named volume
|
|
|
+
|
|
|
+The following example creates a service that uses a named volume:
|
|
|
+
|
|
|
+```bash
|
|
|
+$ docker service create \
|
|
|
+ --name my-service \
|
|
|
+ --replicas 3 \
|
|
|
+ --mount type=volume,source=my-volume,destination=/path/in/container,volume-label="color=red",volume-label="shape=round" \
|
|
|
+ nginx:alpine
|
|
|
+```
|
|
|
+
|
|
|
+For each replica of the service, the engine requests a volume named "my-volume"
|
|
|
+from the default ("local") volume driver where the task is deployed. If the
|
|
|
+volume does not exist, the engine creates a new volume and applies the "color"
|
|
|
+and "shape" labels.
|
|
|
+
|
|
|
+When the task is started, the volume is mounted on `/path/in/container/` inside
|
|
|
+the container.
|
|
|
+
|
|
|
+Be aware that the default ("local") volume is a locally scoped volume driver.
|
|
|
+This means that depending on where a task is deployed, either that task gets a
|
|
|
+*new* volume named "my-volume", or shares the same "my-volume" with other tasks
|
|
|
+of the same service. Multiple containers writing to a single shared volume can
|
|
|
+cause data corruption if the software running inside the container is not
|
|
|
+designed to handle concurrent processes writing to the same location. Also take
|
|
|
+into account that containers can be re-scheduled by the Swarm orchestrator and
|
|
|
+be deployed on a different node.
|
|
|
+
|
|
|
+#### Create a service that uses an anonymous volume
|
|
|
+
|
|
|
+The following command creates a service with three replicas with an anonymous
|
|
|
+volume on `/path/in/container`:
|
|
|
+
|
|
|
+```bash
|
|
|
+$ docker service create \
|
|
|
+ --name my-service \
|
|
|
+ --replicas 3 \
|
|
|
+ --mount type=volume,destination=/path/in/container \
|
|
|
+ nginx:alpine
|
|
|
+```
|
|
|
+
|
|
|
+In this example, no name (`source`) is specified for the volume, so a new volume
|
|
|
+is created for each task. This guarantees that each task gets its own volume,
|
|
|
+and volumes are not shared between tasks. Anonymous volumes are removed after
|
|
|
+the task using them is complete.
|
|
|
+
|
|
|
+#### Create a service that uses a bind-mounted host directory
|
|
|
+
|
|
|
+The following example bind-mounts a host directory at `/path/in/container` in
|
|
|
+the containers backing the service:
|
|
|
+
|
|
|
+```bash
|
|
|
+$ docker service create \
|
|
|
+ --name my-service \
|
|
|
+ --mount type=bind,source=/path/on/host,destination=/path/in/container \
|
|
|
+ nginx:alpine
|
|
|
+```
|
|
|
+
|
|
|
### Set service mode (--mode)
|
|
|
|
|
|
-You can set the service mode to "replicated" (default) or to "global". A
|
|
|
-replicated service runs the number of replica tasks you specify. A global
|
|
|
+The service mode determines whether this is a _replicated_ service or a _global_
|
|
|
+service. A replicated service runs as many tasks as specified, while a global
|
|
|
service runs on each active node in the swarm.
|
|
|
|
|
|
-The following command creates a "global" service:
|
|
|
+The following command creates a global service:
|
|
|
|
|
|
```bash
|
|
|
$ docker service create \
|
|
|
@@ -159,13 +329,13 @@ constraint expressions. Multiple constraints find nodes that satisfy every
|
|
|
expression (AND match). Constraints can match node or Docker Engine labels as
|
|
|
follows:
|
|
|
|
|
|
-| node attribute | matches | example |
|
|
|
-|:------------- |:-------------| :---------------------------------------------|
|
|
|
-| node.id | node ID | `node.id == 2ivku8v2gvtg4` |
|
|
|
-| node.hostname | node hostname | `node.hostname != node-2` |
|
|
|
-| node.role | node role: manager | `node.role == manager` |
|
|
|
-| node.labels | user defined node labels | `node.labels.security == high` |
|
|
|
-| engine.labels | Docker Engine's labels | `engine.labels.operatingsystem == ubuntu 14.04`|
|
|
|
+| node attribute | matches | example |
|
|
|
+|:----------------|:--------------------------|:------------------------------------------------|
|
|
|
+| node.id | node ID | `node.id == 2ivku8v2gvtg4` |
|
|
|
+| node.hostname | node hostname | `node.hostname != node-2` |
|
|
|
+| node.role | node role: manager | `node.role == manager` |
|
|
|
+| node.labels | user defined node labels | `node.labels.security == high` |
|
|
|
+| engine.labels | Docker Engine's labels | `engine.labels.operatingsystem == ubuntu 14.04` |
|
|
|
|
|
|
`engine.labels` apply to Docker Engine labels like operating system,
|
|
|
drivers, etc. Swarm administrators add `node.labels` for operational purposes by
|
|
|
@@ -240,3 +410,5 @@ the service running on the node. For more information refer to
|
|
|
* [service scale](service_scale.md)
|
|
|
* [service ps](service_ps.md)
|
|
|
* [service update](service_update.md)
|
|
|
+
|
|
|
+<style>table tr > td:first-child { white-space: nowrap;}</style>
|
Sebastiaan van Stijn