Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Misty's edits and additions 

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
(cherry picked from commit 3de7d725137ee1620ae2050e65ace4990a3af87e)
This commit is contained in:
Misty Stanley-Jones 2016-09-09 17:29:32 -07:00 committed by Tibor Vass
parent 060fd9fa5c
commit b3341fb7af
3 changed files with 132 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
docs/reference/commandline/service_create.md
View File

@ -137,54 +137,116 @@ $ docker service create \
For more information about labels, refer to [apply custom For more information about labels, refer to [apply custom
metadata](../../userguide/labels-custom-metadata.md). metadata](../../userguide/labels-custom-metadata.md).
### Add volumes or bind-mounts ### Add bind-mounts or volumes
The following table describes the options for defining mounts in a service: 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_.
| Option | Required | Description 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
| **type** | | The type of mount, can be either "volume", or "bind". Defaults to "volume" if no type is specified.<ul><li>`volume`: (default) 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> read-write. For example, a container might share its host's DNS information by
| **src** | `bind`&nbsp;only | <ul><li>`type=volume`: Use `src` to specify the name of the volume (e.g., `src=my-volume`). If a volume with the given name does not exist, it is automatically created. If this option is omitted, an ephemeral volume with a random name is generated. Random names are guaranteed to be unique on the host, but may not be unique cluster-wide. Ephemeral volumes have the same lifecycle as the container it is attached to, and are destroyed when the *container* is destroyed (which is upon `service update`, or when scaling or re-balancing the service).</li><li>`type=bind`: Use `src` to specify host-path to bind mount (e.g., `src=/path/on/host/`). When using a bind-mount (`"type=bind"`), the `src` path must be specified as an absolute path, and *must* be a pre-existing path, or an error is produced.</li></ul> means of a bind-mount of the host's `/etc/resolv.conf` or a container might
| **source** | | Alias for `src`. write logs to its host's `/var/log/myContainerLogs` directory. If you use
| **dst** | 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. bind-mounts and your host and containers have different notions of permissions,
| **destination** | | Alias for `dst`. access controls, or other such details, you will run into portability issues.
| **target** | | Alias for `dst`.
| **readonly** | | By default, the Engine mounts binds and volumes `read-write`. Pass the `readonly` option to mount the bind or volume `read-only` in the container.<br /><br />A value is optional:<ul><li>`true` or `1`: Default if you do not provide a value. Mounts the bind or volume read-only in the container.</li><li>`false` or `0`: Mounts the bind or volume read-write in the container.</li></ul>
| **ro** | | Alias for `readonly`.
The following options can only be used for bind-mounts (`type=bind`); 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.
| Option | Description For more information about named volumes, see
|:----------------------|:-------------------------------------------------------------------------------------------------------------------- [Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/).
| **bind-propagation** | Bind propagation options to set on the mount at runtime. Valid options are `shared`, `slave`, `private`, `rshared`, `rslave`, and `rprivate`. Defaults to `rprivate` if not specified. For volumes, bind propagation is not configurable, and also defaults to `rprivate`.
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`&nbsp;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`); The following options can only be used for named volumes (`type=volume`);
| Option | Description | Option | Description
|:----------------------|:-------------------------------------------------------------------------------------------------------------------- |:----------------------|:--------------------------------------------------------------------------------------------------------------------
| **volume-driver** | Name of the volume-driver plugin to use for the volume. Defaults to the ``"local"`` volume driver to create the volume if it does not exist. | **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** | Custom metadata ("labels") to apply to the volume upon creation. Labels are provided as comma-separated list of key/value pairs, for example, `volume-label=hello=world`. For more information about labels, refer to [apply custom metadata](../../userguide/labels-custom-metadata.md). | **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, the Engine propagates the files and directories that are present at the mount-path (`dst`) inside the container into the volume. 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-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** | Volume driver-specific options to use when creating the volume. Options are provided as comma-separated list of key/value pairs, for example, `volume-opt=some-option=some-value,some-other-option=some-other-value`. For available options, refer to the documentation of the volume driver that is used. | **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" #### Differences between "--mount" and "--volume"
The `--mount` flag features most options that are supported by the `-v` / The `--mount` flag supports most options that are supported by the `-v`
`--volume` flag for `docker run`. There are some differences; or `--volume` flag for `docker run`, with some important exceptions:
- The `--mount` flag allows specifying a volume driver, and volume driver - The `--mount` flag allows you to specify a volume driver and volume driver
options *per volume*, without having to create volumes in advance. When using options *per volume*, without creating the volumes in advance. In contrast,
`docker run`, only a single volume driver can be specified (using the `docker run` allows you to specify a single volume driver which is shared
`--volume-driver` flag), which is shared by all volumes. by all volumes, using the `--volume-driver` flag.
- The `--mount` flag allows specifying custom metadata ("labels") for the volume,
without having to create the volume out of band. - The `--mount` flag allows you to specify custom metadata ("labels") for a volume,
- When using `type=bind`, the host-path must refer to an *existing* path on the before the volume is created.
host, and is not automatically created if the path does not exist. If the
specified path does not exist on the host, an error is produced, and the - When you use `--mount` with `type=bind`, the host-path must refer to an *existing*
service will fail to be deployed succesfully. path on the host. The path will not be created for you and the service will fail
- The `--mount` flag does not allow you to relabel volumes with `Z` or `z` 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 #### Create a service using a named volume
@ -215,7 +277,7 @@ 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 into account that containers can be re-scheduled by the Swarm orchestrator and
be deployed on a different node. be deployed on a different node.
#### Create a service that uses an anonymous (ephemeral) volume #### Create a service that uses an anonymous volume
The following command creates a service with three replicas with an anonymous The following command creates a service with three replicas with an anonymous
volume on `/path/in/container`: volume on `/path/in/container`:
@ -228,10 +290,10 @@ $ docker service create \
nginx:alpine nginx:alpine
``` ```
In this example, no name (`source`) is specified for the volume, hence a new, In this example, no name (`source`) is specified for the volume, so a new volume
*randomly named* volume is created for each task. This guarantees that each task is created for each task. This guarantees that each task gets its own volume,
gets its own volume, and volumes are not shared between tasks. Unnamed volumes and volumes are not shared between tasks. Anonymous volumes are removed after
are considered "ephemeral", and are destroyed when the container is destroyed. the task using them is complete.
#### Create a service that uses a bind-mounted host directory #### Create a service that uses a bind-mounted host directory
@ -247,11 +309,11 @@ $ docker service create \
### Set service mode (--mode) ### Set service mode (--mode)
You can set the service mode to "replicated" (default) or to "global". A The service mode determines whether this is a _replicated_ service or a _global_
replicated service runs the number of replica tasks you specify. A global service. A replicated service runs as many tasks as specified, while a global
service runs on each active node in the swarm. service runs on each active node in the swarm.
The following command creates a "global" service: The following command creates a global service:
```bash ```bash
$ docker service create \ $ docker service create \
@ -350,4 +412,3 @@ the service running on the node. For more information refer to
* [service update](service_update.md) * [service update](service_update.md)
<style>table tr > td:first-child { white-space: nowrap;}</style> <style>table tr > td:first-child { white-space: nowrap;}</style>

37
docs/reference/commandline/service_update.md
View File

@ -69,19 +69,36 @@ $ docker service update --limit-cpu 2 redis
### Adding and removing mounts ### Adding and removing mounts
You can add, or remove bind-mounts or volumes to a service using the Use the `--mount-add` or `--mount-rm` options add or remove a service's bind-mounts
`--mount-add` and `--mount-rm` options. or volumes.
The following example creates a service using the `test-data` volume, then The following example creates a service which mounts the `test-data` volume to
updates the service to mount another volume, and finally unmounts the first `/somewhere`. The next step updates the service to also mount the `other-volume`
volume: volume to `/somewhere-else`volume, The last step unmounts the `/somewhere` mount
point, effectively removing the `test-data` volume. Each command returns the
service name.
- The `--mount-add` flag takes the same parameters as the `--mount` flag on
`service create`. Refer to the [volumes and
bind-mounts](service_create.md#volumes-and-bind-mounts-mount) section in the
`service create` reference for details.
- The `--mount-rm` flag takes the `target` path of the mount.
```bash ```bash
$ docker service create --name=myservice --mount type=volume,source=test-data,target=/somewhere nginx:alpine $ docker service create \
--name=myservice \
--mount \
type=volume,source=test-data,target=/somewhere \
nginx:alpine \
myservice
myservice myservice
$ docker service update --mount-add type=volume,source=other-volume,target=/somewhere-else myservice $ docker service update \
--mount-add \
type=volume,source=other-volume,target=/somewhere-else \
myservice
myservice myservice
@ -90,12 +107,6 @@ $ docker service update --mount-rm /somewhere myservice
myservice myservice
``` ```
The `--mount-rm` flag takes the `target` path of the mount. The `--mount-add`
flag takes the same parameters as the `--mount` flag on `service create`. Refer
to the [volumes and bind-mounts](service_create.md#volumes-and-bind-mounts-mount) section in the
`service create` reference for details.
## Related information ## Related information
* [service create](service_create.md) * [service create](service_create.md)