[2/2] mesos git commit: Documented the `linux/devices` isolator.

[jp...@apache.org]

Documented the `linux/devices` isolator.

Documented the `linux/devices` isolator in the Mesos containerizer
documentation, upgrade guide and CHANGELOG.

Review: https://reviews.apache.org/r/67331/


Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/0ffafd47
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/0ffafd47
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/0ffafd47

Branch: refs/heads/master
Commit: 0ffafd47f0598fea978030f75035db5517cd1638
Parents: c442dfb
Author: James Peach <jp...@apache.org>
Authored: Tue May 29 14:58:38 2018 -0700
Committer: James Peach <jp...@apache.org>
Committed: Tue May 29 14:58:38 2018 -0700

----------------------------------------------------------------------
 CHANGELOG                       |  4 ++++
 docs/isolators/linux-devices.md | 32 ++++++++++++++++++++++++++++++++
 docs/mesos-containerizer.md     |  1 +
 docs/upgrades.md                |  7 +++++++
 4 files changed, 44 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/mesos/blob/0ffafd47/CHANGELOG
----------------------------------------------------------------------
diff --git a/CHANGELOG b/CHANGELOG
index e7c2904..52c7fc3 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -2,6 +2,10 @@ Release Notes - Mesos - Version 1.7.0 (WIP)
 -------------------------------------------
 This release contains the following new features:
 
+  * [MESOS-8792] - Added a new `linux/devices` isolator that automatically
+    populates containers with devices that have been whitelisted with the
+    `--allowed_devices` agent flag.
+
 Additional API Changes:
   * Container logger module interface has been changed. The `prepare()` method
     now takes `ContainerID` and `ContainerConfig` instead.

http://git-wip-us.apache.org/repos/asf/mesos/blob/0ffafd47/docs/isolators/linux-devices.md
----------------------------------------------------------------------
diff --git a/docs/isolators/linux-devices.md b/docs/isolators/linux-devices.md
new file mode 100644
index 0000000..6472772
--- /dev/null
+++ b/docs/isolators/linux-devices.md
@@ -0,0 +1,32 @@
+---
+title: Apache Mesos - Linux Devices Isolator in Mesos Containerizer
+layout: documentation
+---
+
+# Linux Devices in Mesos Containerizer
+
+While the `cgroups/devices` isolator allows operators to control
+container access to host devices, the container might still need
+additional privileges to create a device node to actually use the
+device. The `linux/devices` isolator ensures that containers that
+are granted access to host devices are populated with the the correct
+set of device nodes. Access to host devices is granted by using the
+[`--allowed_devices`](../configuration/agent.md#allowed_devices) flag
+on the agent.
+
+To enable the `linux/devices` isolator, append `linux/devices` to the
+[`--isolation`](../configuration/agent.md#isolation) flag when starting
+the Mesos agent.
+
+## Security Considerations
+
+Device access is configured at container
+granularity. For example, this means that if the
+[`--allowed_devices`](../configuration/agent.md#allowed_devices) flag
+specifies read access for a device, then every process in the container
+will be able to read from the specified device.
+
+The `linux/devices` isolator does not require the
+[`--allowed_devices`](../configuration/agent.md#allowed_devices) entry
+to grant `mknod` access, since it creates device nodes from outside
+the container.

http://git-wip-us.apache.org/repos/asf/mesos/blob/0ffafd47/docs/mesos-containerizer.md
----------------------------------------------------------------------
diff --git a/docs/mesos-containerizer.md b/docs/mesos-containerizer.md
index 42a0977..d15e825 100644
--- a/docs/mesos-containerizer.md
+++ b/docs/mesos-containerizer.md
@@ -48,6 +48,7 @@ Mesos supports the following built-in isolators.
 - filesystem/windows
 - [gpu/nvidia](gpu-support.md)
 - [linux/capabilities](isolators/linux-capabilities.md)
+- [linux/devices](isolators/linux-devices.md)
 - [namespaces/ipc](isolators/namespaces-ipc.md)
 - [namespaces/pid](isolators/namespaces-pid.md)
 - [network/cni](cni.md)

http://git-wip-us.apache.org/repos/asf/mesos/blob/0ffafd47/docs/upgrades.md
----------------------------------------------------------------------
diff --git a/docs/upgrades.md b/docs/upgrades.md
index fb6b865..1a1705c 100644
--- a/docs/upgrades.md
+++ b/docs/upgrades.md
@@ -48,6 +48,7 @@ We categorize the changes as follows:
 
   <td style="word-wrap: break-word; overflow-wrap: break-word;"><!--Mesos Core-->
     <ul style="padding-left:10px;">
+      <li>A <a href="#1-7-x-linux-devices-isolator">Linux devices isolator</a></li>
     </ul>
   </td>
 
@@ -430,6 +431,12 @@ We categorize the changes as follows:
 
 ## Upgrading from 1.6.x to 1.7.x ##
 
+<a name="1-7-x-linux-devices-isolator"></a>
+
+* A new [`linux/devices`](isolators/linux-devices.md) isolator has been
+  added. This isolator automatically populates containers with devices
+  that have been whitelisted with the `--allowed_devices` agent flag.
+
 <a name="1-7-x-container-logger"></a>
 
 * `ContainerLogger` module interface has been changed. The `prepare()` method now takes `ContainerID` and `ContainerConfig` instead.