docs: expand explanation of task driver capabilities (#8485)

hashicorp · Jul 22, 2020 · 31be70b · 31be70b
1 parent e8ce66d
commit 31be70b
Show file tree

Hide file tree

Showing 6 changed files with 61 additions and 41 deletions.
diff --git a/website/pages/docs/drivers/docker.mdx b/website/pages/docs/drivers/docker.mdx
@@ -629,16 +629,15 @@ through Nomad plugins or dynamic job configuration.
 
 ## Capabilities
 
-The `docker` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error)
+The `docker` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error).
 
 | Feature | Implementation |
 | --- | --- |
-| SendSignals | true |
-| Exec | true |
-| FSIsolation | image |
-| NetIsolationModes | host, group, task |
-| MustInitiateNetwork | true |
-| MountConfigs | all |
+| `nomad alloc signal` | true |
+| `nomad alloc exec` | true |
+| filesystem isolation | image |
+| network isolation | host, group, task |
+| volume mounting | all |
 
 ## Client Requirements
 

diff --git a/website/pages/docs/drivers/exec.mdx b/website/pages/docs/drivers/exec.mdx
@@ -79,16 +79,15 @@ task "example" {
 
 ## Capabilities
 
-The `exec` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error)
+The `exec` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error).
 
 | Feature | Implementation |
 | --- | --- |
-| SendSignals | true |
-| Exec | true |
-| FSIsolation | chroot |
-| NetIsolationModes | host, group |
-| MustInitiateNetwork | false |
-| MountConfigs | all |
+| `nomad alloc signal` | true |
+| `nomad alloc exec` | true |
+| filesystem isolation | chroot |
+| network isolation | host, group |
+| volume mounting | all |
 
 ## Client Requirements
 

diff --git a/website/pages/docs/drivers/java.mdx b/website/pages/docs/drivers/java.mdx
@@ -99,15 +99,15 @@ task "web" {
 
 ## Capabilities
 
-The `java` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error)
+The `java` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error).
 
 | Feature | Implementation |
 | --- | --- |
-| SendSignals | false |
-| Exec | false |
-| FSIsolation | none, chroot (only for linux)  |
-| NetIsolationModes | host, group |
-| MountConfigs | none, all (only for linux) |
+| `nomad alloc signal` | false |
+| `nomad alloc exec` | false |
+| filesystem isolation | none, chroot (only for linux) |
+| network isolation | host, group |
+| volume mounting | none, all (only for linux) |
 
 ## Client Requirements
 

diff --git a/website/pages/docs/drivers/qemu.mdx b/website/pages/docs/drivers/qemu.mdx
@@ -103,15 +103,15 @@ task "virtual" {
 
 ## Capabilities
 
-The `qemu` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error)
+The `qemu` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error).
 
 | Feature | Implementation |
 | --- | --- |
-| SendSignals | false |
-| Exec | false |
-| FSIsolation | image |
-| NetIsolationModes | none |
-| MountConfigs | none |
+| `nomad alloc signal` | false |
+| `nomad alloc exec` | false |
+| filesystem isolation | image |
+| network isolation | none |
+| volume mounting | none |
 
 ## Client Requirements
 

diff --git a/website/pages/docs/drivers/raw_exec.mdx b/website/pages/docs/drivers/raw_exec.mdx
@@ -75,15 +75,15 @@ task "example" {
 
 ## Capabilities
 
-The `raw_exec` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error)
+The `raw_exec` driver implements the following [capabilities](/docs/internals/plugins/task-drivers#capabilities-capabilities-error).
 
 | Feature | Implementation |
 | --- | --- |
-| SendSignals | true |
-| Exec | true |
-| FSIsolation | none  |
-| NetIsolationModes | host, group |
-| MountConfigs | none |
+| `nomad alloc signal` | true |
+| `nomad alloc exec` | true |
+| filesystem isolation | none |
+| network isolation | host, group |
+| volume mounting | none |
 
 ## Client Requirements
 

diff --git a/website/pages/docs/internals/plugins/task-drivers.mdx b/website/pages/docs/internals/plugins/task-drivers.mdx
@@ -47,32 +47,54 @@ Capabilities define what features the driver implements. Example:
 
 ```go
 Capabilities {
-    // Does the driver support sending OS signals to the task?
+    // Does the driver support sending OS signals to the task? This capability
+    // is used by 'nomad alloc signal'.
     SendSignals: true,
+
     // Does the driver support executing a command within the task execution
-    // environment?
+    // environment? This capability is used by 'nomad alloc exec'.
     Exec:        true,
+
     // What filesystem isolation is supported by the driver. Options include
-    // FSIsolationImage, FSIsolationChroot, and FSIsolationNone
+    // FSIsolationImage, FSIsolationChroot, and FSIsolationNone. See below for
+    // more details.
     FSIsolation: FSIsolationImage,
 
-    // NetIsolationModes lists the set of isolation modes supported by the driver.
-    // Options include NetIsolationModeHost, NetIsolationModeGroup,
-    // NetIsolationModeTask, and NetIsolationModeNone.
+    // NetIsolationModes lists the set of isolation modes supported by the
+    // driver.  Options include NetIsolationModeHost, NetIsolationModeGroup,
+    // NetIsolationModeTask, and NetIsolationModeNone. See below for more
+    // details.
     NetIsolationModes []NetIsolationMode
 
     // MustInitiateNetwork tells Nomad that the driver must create the network
-    // namespace and that the CreateNetwork and DestroyNetwork RPCs are implemented.
+    // namespace and that the CreateNetwork and DestroyNetwork RPCs are
+    // implemented.
     MustInitiateNetwork bool
 
     // MountConfigs tells Nomad which mounting config options the driver
     // supports. This is used to check whether mounting host volumes or CSI
-    // volumes is allowed. Options include MountConfigSupportAll (default),
-    // or MountConfigSupportNone.
+    // volumes is allowed. Options include MountConfigSupportAll (default), or
+    // MountConfigSupportNone.
     MountConfigs MountConfigSupport
 }
 ```
 
+The file system isolation options are:
+- `FSIsolationImage`: The task driver isolates tasks as machine images.
+- `FSIsolationChroot`: The task driver isolates tasks with `chroot` or
+  `pivot_root`.
+- `FSIsolationNone`: The task driver has no filesystem isolation.
+
+The network isolation modes are:
+- `NetIsolationModeHost`: The task driver supports disabling network isolation
+  and using thre host network.
+- `NetIsolationModeGroup`: The task driver supports using the task group
+  network namespace.
+- `NetIsolationModeTask`: The task driver supports isolating the network to
+  just the task.
+- `NetIsolationModeNone`: There is no network to isolate. This is used for
+  task that the client manages remotely.
+
 ### `Fingerprint(context.Context) (<-chan *Fingerprint, error)`
 
 This function is called by the client when the plugin is started. It allows the