From 77f4189cd25933838acee962f02b9bb422f379ae Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Wed, 22 Jul 2020 12:14:20 -0400 Subject: [PATCH] docs: expand explanation of task driver capabilities (#8485) --- website/pages/docs/drivers/docker.mdx | 13 +++--- website/pages/docs/drivers/exec.mdx | 13 +++--- website/pages/docs/drivers/java.mdx | 12 +++--- website/pages/docs/drivers/qemu.mdx | 12 +++--- website/pages/docs/drivers/raw_exec.mdx | 12 +++--- .../docs/internals/plugins/task-drivers.mdx | 40 ++++++++++++++----- 6 files changed, 61 insertions(+), 41 deletions(-) diff --git a/website/pages/docs/drivers/docker.mdx b/website/pages/docs/drivers/docker.mdx index 9b2375ac8..72a55429a 100644 --- 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 index b1a32cff6..43686b2d9 100644 --- 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 index 3917c28d1..4b686aa09 100644 --- 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 index f4c0184f6..2973f54d5 100644 --- 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 index 0520bb1ed..e57f9c5d2 100644 --- 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 index 7a45b0cb9..50bf95877 100644 --- 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