Add docs for option --isolation

WeiZhang555 · WeiZhang555 · commit 38ec5d86a355 · 2015-12-02T22:24:33.000+08:00
Add docs for `run`/`create`/`build` command option `isolation`

Signed-off-by: Zhang Wei &lt;zhangwei555@huawei.com&gt;
diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md
@@ -25,6 +25,7 @@ parent = "smn_cli"
       -f, --file=""                   Name of the Dockerfile (Default is 'PATH/Dockerfile')
       --force-rm=false                Always remove intermediate containers
       --help=false                    Print usage
+      --isolation=""                  Container isolation technology
       -m, --memory=""                 Memory limit for all build containers
       --memory-swap=""                Total memory (memory + swap), `-1` to disable swap
       --no-cache=false                Do not use cache when building the image
@@ -301,3 +302,19 @@ like `ENV` values do.
 
 For detailed information on using `ARG` and `ENV` instructions, see the
 [Dockerfile reference](../builder.md).
+
+### Specify isolation technology for container (--isolation)
+
+This option is useful in situations where you are running Docker containers on
+Windows. The `--isolation=<value>` option sets a container's isolation
+technology. On Linux, the only supported is the `default` option which uses
+Linux namespaces. On Microsoft Windows, you can specify these values:
+
+
+| Value     | Description                                                                                                                                                   |
+|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value.  |
+| `process` | Namespace isolation only.                                                                                                                                     |
+| `hyperv`   | Hyper-V hypervisor partition-based isolation.                                                                                                                  |
+
+Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md
@@ -43,6 +43,7 @@ Creates a new container.
       --help=false                  Print usage
       -i, --interactive=false       Keep STDIN open even if not attached
       --ipc=""                      IPC namespace to use
+      --isolation=""                Container isolation technology
       --kernel-memory=""            Kernel memory limit
       -l, --label=[]                Set metadata on the container (e.g., --label=com.example.key=value)
       --label-file=[]               Read in a line delimited file of labels
@@ -125,3 +126,19 @@ then be used from the subsequent container:
     -rw-r--r--  1 1000 staff  920 Nov 28 11:51 .profile
     drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
     drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker
+
+### Specify isolation technology for container (--isolation)
+
+This option is useful in situations where you are running Docker containers on
+Windows. The `--isolation=<value>` option sets a container's isolation
+technology. On Linux, the only supported is the `default` option which uses
+Linux namespaces. On Microsoft Windows, you can specify these values:
+
+
+| Value     | Description                                                                                                                                                   |
+|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value.  |
+| `process` | Namespace isolation only.                                                                                                                                     |
+| `hyperv`   | Hyper-V hypervisor partition-based isolation.                                                                                                                  |
+
+Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
diff --git a/docs/reference/commandline/daemon.md b/docs/reference/commandline/daemon.md
@@ -454,6 +454,14 @@ This example sets the `cgroupdriver` to `systemd`:
 
 Setting this option applies to all containers the daemon launches.
 
+Also Windows Container makes use of `--exec-opt` for special purpose. Docker user
+can specify default container isolation technology with this, for example:
+
+    $ docker daemon --exec-opt isolation=hyperv
+
+Will make `hyperv` the default isolation technology on Windows, without specifying
+isolation value on daemon start, Windows isolation technology will default to `process`.
+
 ## Daemon DNS options
 
 To set the DNS server for all Docker containers, use
diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
@@ -42,6 +42,7 @@ parent = "smn_cli"
       --help=false                  Print usage
       -i, --interactive=false       Keep STDIN open even if not attached
       --ipc=""                      IPC namespace to use
+      --isolation=""                Container isolation technology
       --kernel-memory=""            Kernel memory limit
       -l, --label=[]                Set metadata on the container (e.g., --label=com.example.key=value)
       --label-file=[]               Read in a file of labels (EOL delimited)
@@ -546,3 +547,38 @@ the three processes quota set for the `daemon` user.
 The `--stop-signal` flag sets the system call signal that will be sent to the container to exit.
 This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9,
 or a signal name in the format SIGNAME, for instance SIGKILL.
+
+### Specify isolation technology for container (--isolation)
+
+This option is useful in situations where you are running Docker containers on
+Microsoft Windows. The `--isolation <value>` option sets a container's isolation
+technology. On Linux, the only supported is the `default` option which uses
+Linux namespaces. These two commands are equivalent on Linux:
+
+```
+$ docker run -d busybox top
+$ docker run -d --isolation default busybox top
+```
+
+On Microsoft Windows, can take any of these values:
+
+
+| Value     | Description                                                                                                                                                   |
+|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value.  |
+| `process` | Namespace isolation only.                                                                                                                                     |
+| `hyperv`   | Hyper-V hypervisor partition-based isolation.                                                                                                                  |
+
+In practice, when running on Microsoft Windows without a `daemon` option set,  these two commands are equivalent:
+
+```
+$ docker run -d --isolation default busybox top
+$ docker run -d --isolation process busybox top
+```
+
+If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, any of these commands also result in `hyperv` isolation:
+
+```
+$ docker run -d --isolation default busybox top
+$ docker run -d --isolation hyperv busybox top
+```
diff --git a/man/docker-build.1.md b/man/docker-build.1.md
@@ -12,6 +12,7 @@ docker-build - Build a new image from the source code at PATH
 [**--help**]
 [**-f**|**--file**[=*PATH/Dockerfile*]]
 [**--force-rm**[=*false*]]
+[**--isolation**[=*default*]]
 [**--no-cache**[=*false*]]
 [**--pull**[=*false*]]
 [**-q**|**--quiet**[=*false*]]
@@ -67,6 +68,9 @@ set as the **URL**, the repository is cloned locally and then sent as the contex
 **--force-rm**=*true*|*false*
    Always remove intermediate containers, even after unsuccessful builds. The default is *false*.
 
+**--isolation**="*default*"
+   Isolation specifies the type of isolation technology used by containers. 
+
 **--no-cache**=*true*|*false*
    Do not use cache when building the image. The default is *false*.
 
@@ -277,6 +281,19 @@ the system will look for that file inside the contents of the tarball.
 
 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and 'identity' (no compression).
 
+## Specify isolation technology for container (--isolation)
+
+This option is useful in situations where you are running Docker containers on
+Windows. The `--isolation=<value>` option sets a container's isolation
+technology. On Linux, the only supported is the `default` option which uses
+Linux namespaces. On Microsoft Windows, you can specify these values:
+
+* `default`: Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value.
+* `process`: Namespace isolation only.
+* `hyperv`: Hyper-V hypervisor partition-based isolation.
+
+Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
+
 # HISTORY
 March 2014, Originally compiled by William Henry (whenry at redhat dot com)
 based on docker.com source material and internal work.
diff --git a/man/docker-create.1.md b/man/docker-create.1.md
@@ -32,6 +32,7 @@ docker-create - Create a new container
 [**--help**]
 [**-i**|**--interactive**[=*false*]]
 [**--ipc**[=*IPC*]]
+[**--isolation**[=*default*]]
 [**--kernel-memory**[=*KERNEL-MEMORY*]]
 [**-l**|**--label**[=*[]*]]
 [**--label-file**[=*[]*]]
@@ -159,6 +160,9 @@ two memory nodes.
                                'container:<name|id>': reuses another container shared memory, semaphores and message queues
                                'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
 
+**--isolation**="*default*"
+   Isolation specifies the type of isolation technology used by containers. 
+
 **--kernel-memory**=""
    Kernel memory limit (format: `<number>[<unit>]`, where unit = b, k, m or g)
 
@@ -287,6 +291,21 @@ This value should always larger than **-m**, so you should always use this with
 **-w**, **--workdir**=""
    Working directory inside the container
 
+# EXAMPLES
+
+## Specify isolation technology for container (--isolation)
+
+This option is useful in situations where you are running Docker containers on
+Windows. The `--isolation=<value>` option sets a container's isolation
+technology. On Linux, the only supported is the `default` option which uses
+Linux namespaces. On Microsoft Windows, you can specify these values:
+
+* `default`: Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value.
+* `process`: Namespace isolation only.
+* `hyperv`: Hyper-V hypervisor partition-based isolation.
+
+Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
+
 # HISTORY
 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
diff --git a/man/docker-run.1.md b/man/docker-run.1.md
@@ -33,6 +33,7 @@ docker-run - Run a command in a new container
 [**--help**]
 [**-i**|**--interactive**[=*false*]]
 [**--ipc**[=*IPC*]]
+[**--isolation**[=*default*]]
 [**--kernel-memory**[=*KERNEL-MEMORY*]]
 [**-l**|**--label**[=*[]*]]
 [**--label-file**[=*[]*]]
@@ -253,6 +254,9 @@ redirection on the host system.
                                'container:<name|id>': reuses another container shared memory, semaphores and message queues
                                'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
 
+**--isolation**="*default*"
+   Isolation specifies the type of isolation technology used by containers.
+
 **-l**, **--label**=[]
    Set metadata on the container (e.g., --label com.example.key=value)
 
@@ -772,6 +776,38 @@ weight by `--blkio-weight-device` flag. Use the following command:
 
    # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu
 
+## Specify isolation technology for container (--isolation)
+
+This option is useful in situations where you are running Docker containers on
+Microsoft Windows. The `--isolation <value>` option sets a container's isolation
+technology. On Linux, the only supported is the `default` option which uses
+Linux namespaces. These two commands are equivalent on Linux:
+
+```
+$ docker run -d busybox top
+$ docker run -d --isolation default busybox top
+```
+
+On Microsoft Windows, can take any of these values:
+
+* `default`: Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value.
+* `process`: Namespace isolation only.
+* `hyperv`: Hyper-V hypervisor partition-based isolation.
+
+In practice, when running on Microsoft Windows without a `daemon` option set,  these two commands are equivalent:
+
+```
+$ docker run -d --isolation default busybox top
+$ docker run -d --isolation process busybox top
+```
+
+If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, any of these commands also result in `hyperv` isolation:
+
+```
+$ docker run -d --isolation default busybox top
+$ docker run -d --isolation hyperv busybox top
+```
+
 # HISTORY
 April 2014, Originally compiled by William Henry (whenry at redhat dot com)
 based on docker.com source material and internal work.
