diff --git a/website/redirects.txt b/website/redirects.txt index 07bc3497c..19bd934c9 100644 --- a/website/redirects.txt +++ b/website/redirects.txt @@ -145,6 +145,9 @@ /docs/service-discovery/ /guides/operations/consul-integration/index.html /docs/service-discovery/index.html /guides/operations/consul-integration/index.html +# Redirect old LXC driver doc to new one in /docs/external +/docs/drivers/lxc.html /docs/drivers/external/lxc.html + # API /docs/http/index.html /api/index.html /docs/http/json-jobs.html /api/json-jobs.html diff --git a/website/source/docs/configuration/client.html.md b/website/source/docs/configuration/client.html.md index 09fe5c222..7a52da877 100644 --- a/website/source/docs/configuration/client.html.md +++ b/website/source/docs/configuration/client.html.md @@ -28,6 +28,15 @@ client { } ``` +## Plugin Options + +Nomad 0.9 now supports pluggable drivers. Operators should use the new +[plugin][plugin-stanza] syntax to modify driver configuration. To find the +plugin options supported by each individual Nomad driver, please see the +[drivers documentation](/docs/drivers/index.html). The pre-0.9 `client.options` +stanza will be supported in 0.9 for backward compatibility (except for the `lxc` +driver) but will be removed in a future release. + ## `client` Parameters - `alloc_dir` `(string: "[data_dir]/alloc")` - Specifies the directory to use @@ -158,6 +167,9 @@ the full list. ### `options` Parameters +~> Note: client configuration options for drivers will soon be deprecated. See +the [plugin stanza][plugin-stanza] documentation for more information. + The following is not an exhaustive list of options for only the Nomad client. To find the options supported by each individual Nomad driver, please see the [drivers documentation](/docs/drivers/index.html). @@ -356,4 +368,6 @@ client { } } ``` +[plugin-options]: #plugin-options +[plugin-stanza]: /docs/configuration/plugin.html [server-join]: /docs/configuration/server_join.html "Server Join" diff --git a/website/source/docs/configuration/plugin.html.md b/website/source/docs/configuration/plugin.html.md index bbbb9fc4b..359530632 100644 --- a/website/source/docs/configuration/plugin.html.md +++ b/website/source/docs/configuration/plugin.html.md @@ -17,7 +17,7 @@ description: |- -The `plugin` stanza is used to configure an individual plugin. +The `plugin` stanza is used to configure plugins. ```hcl plugin "example-plugin" { diff --git a/website/source/docs/drivers/custom.html.md b/website/source/docs/drivers/custom.html.md deleted file mode 100644 index 7f2bde558..000000000 --- a/website/source/docs/drivers/custom.html.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: "docs" -page_title: "Drivers: Custom" -sidebar_current: "docs-drivers-custom" -description: |- - Create custom task drivers for Nomad. ---- - -# Custom Drivers - -Nomad does not currently support pluggable task drivers, however the -interface that a task driver must implement is minimal. In the short term, -custom drivers can be implemented in Go and compiled into the binary, -however in the long term we plan to expose a plugin interface such that -task drivers can be dynamically registered without recompiling the Nomad binary. - diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md index 42e654d90..9d4e5914e 100644 --- a/website/source/docs/drivers/docker.html.md +++ b/website/source/docs/drivers/docker.html.md @@ -363,7 +363,7 @@ The `docker` driver supports the following configuration in the job spec. Only * `cap_add` - (Optional) A list of Linux capabilities as strings to pass directly to [`--cap-add`](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). Effective capabilities (computed from `cap_add` and `cap_drop`) have to match the configured whitelist. - The whitelist can be customized using the `docker.caps.whitelist` key in the client node's configuration. + The whitelist can be customized using the [`allow_caps`](#plugin_caps) plugin option key in the client node's configuration. For example: @@ -378,7 +378,7 @@ The `docker` driver supports the following configuration in the job spec. Only * `cap_drop` - (Optional) A list of Linux capabilities as strings to pass directly to [`--cap-drop`](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). Effective capabilities (computed from `cap_add` and `cap_drop`) have to match the configured whitelist. - The whitelist can be customized using the `docker.caps.whitelist` key in the client node's configuration. + The whitelist can be customized using the [`allow_caps`](#plugin_caps) plugin option key in the client node's configuration. For example: @@ -427,10 +427,11 @@ you will need to specify credentials in your job via: * the `auth` option in the task config. * by storing explicit repository credentials or by specifying Docker - `credHelpers` in a file and setting the [docker.auth.config](#auth_file) - value on the client. + `credHelpers` in a file and setting the auth [config](#plugin_auth_file) + value on the client in the plugin options. - * by specifying a [docker.auth.helper](#auth_helper) on the client + * by specifying an auth [helper](#plugin_auth_helper) on the client in the + plugin options. The `auth` object supports the following keys: @@ -481,8 +482,13 @@ $PATH ```hcl client { enabled = true - options { - "docker.auth.helper" = "ecr" +} + +plugin "docker" { + config { + auth { + helper = "docker-credential-ecr" + } } } ``` @@ -614,8 +620,117 @@ user to the `docker` group so you can run Nomad without root: For the best performance and security features you should use recent versions of the Linux Kernel and Docker daemon. +If you would like to change any of the options related to the `docker` driver on +a Nomad client, you can modify them with the [plugin stanza][plugin-stanza] syntax. Below is an example of a configuration (many of the values are the default). See the next section for more information on the options. + +```hcl +plugin "docker" { + config { + endpoint = "unix:///var/run/docker.sock" + + auth { + config = "/etc/docker-auth.json" + helper = "docker-credential-aws" + } + + tls { + cert = "/etc/nomad/nomad.pub" + key = "/etc/nomad/nomad.pem" + ca = "/etc/nomad/nomad.cert" + } + + gc { + image = true + image_delay = "3m" + container = true + } + + volumes { + enabled = true + selinuxlabel = "z" + } + + allow_privileged = false + allow_caps = ["CHOWN", "NET_RAW"] + + # allow_caps can also be set to "ALL" + # allow_caps = ["ALL"] + } +} +``` +## Plugin Options + +* `endpoint` - If using a non-standard socket, HTTP or another location, or if + TLS is being used, docker.endpoint must be set. If unset, Nomad will attempt + to instantiate a Docker client using the DOCKER_HOST environment variable and + then fall back to the default listen address for the given operating system. + Defaults to unix:///var/run/docker.sock on Unix platforms and + npipe:////./pipe/docker_engine for Windows. + +* `allow_privileged` - Defaults to `false`. Changing this to true will allow + containers to use privileged mode, which gives the containers full access to + the host's devices. Note that you must set a similar setting on the Docker + daemon for this to work. + +* `allow_caps` - A list of allowed Linux capabilities. + Defaults to + "CHOWN,DAC_OVERRIDE,FSETID,FOWNER,MKNOD,NET_RAW,SETGID,SETUID,SETFCAP,SETPCAP, + NET_BIND_SERVICE,SYS_CHROOT,KILL,AUDIT_WRITE", which is the list of + capabilities allowed by docker by default, as defined here. Allows the + operator to control which capabilities can be obtained by tasks using cap_add + and cap_drop options. Supports the value "ALL" as a shortcut for whitelisting + all capabilities. + +* `auth` stanza: + * `config` - Allows an operator to specify a + JSON file which is in the dockercfg format containing authentication + information for a private registry, from either (in order) `auths`, + `credHelpers` or `credsStore`. + * `helper` - Allows an operator to specify a + [credsStore](https://docs.docker.com/engine/reference/commandline/login/#credential-helper-protocol) + -like script on $PATH to lookup authentication information from external + sources. The script's name must begin with `docker-credential-` and this + option should include only the basename of the script, not the path. + +* `tls` stanza: + * `cert` - Path to the server's certificate file (`.pem`). Specify this + along with `key` and `ca` to use a TLS client to connect to the docker + daemon. `endpoint` must also be specified or this setting will be ignored. + * `key` - Path to the client's private key (`.pem`). Specify this along with + `cert` and `ca` to use a TLS client to connect to the docker daemon. + `endpoint` must also be specified or this setting will be ignored. + * `ca` - Path to the server's CA file (`.pem`). Specify this along with + `cert` and `key` to use a TLS client to connect to the docker daemon. + `endpoint` must also be specified or this setting will be ignored. + +* `gc` stanza: + * `image` - Defaults to `true`. Changing this to `false` will prevent Nomad + from removing images from stopped tasks. + * `image_delay` - A time duration, as [defined + here](https://golang.org/pkg/time/#ParseDuration), that defaults to `3m`. + The delay controls how long Nomad will wait between an image being unused + and deleting it. If a tasks is received that uses the same image within + the delay, the image will be reused. + * `container` - Defaults to `true`. This option can be used to disable Nomad + from removing a container when the task exits. Under a name conflict, + Nomad may still remove the dead container. + +* `volumes` stanza: + * `enabled` - Defaults to `true`. Allows tasks to bind host paths + (`volumes`) inside their container and use volume drivers + (`volume_driver`). Binding relative paths is always allowed and will be + resolved relative to the allocation's directory. + * `selinuxlabel` - Allows the operator to set a SELinux label to the + allocation and task local bind-mounts to containers. If used with + `docker.volumes.enabled` set to false, the labels will still be applied to + the standard binds in the container. + ## Client Configuration +~> Note: client configuration options will soon be deprecated. Please use +[plugin options][plugin-options] instead. See the [plugin stanza][plugin-stanza] +documentation for more information. + The `docker` driver has the following [client configuration options](/docs/configuration/client.html#options): @@ -631,21 +746,21 @@ options](/docs/configuration/client.html#options): information for a private registry, from either (in order) `auths`, `credHelpers` or `credsStore`. -* `docker.auth.helper` - Allows an operator to specify - a [credsStore](https://docs.docker.com/engine/reference/commandline/login/#credential-helper-protocol) +* `docker.auth.helper` - Allows an operator to specify a + [credsStore](https://docs.docker.com/engine/reference/commandline/login/#credential-helper-protocol) -like script on $PATH to lookup authentication information from external sources. The script's name must begin with `docker-credential-` and this option should include only the basename of the script, not the path. * `docker.tls.cert` - Path to the server's certificate file (`.pem`). Specify this along with `docker.tls.key` and `docker.tls.ca` to use a TLS client to - connect to the docker daemon. `docker.endpoint` must also be specified or - this setting will be ignored. + connect to the docker daemon. `docker.endpoint` must also be specified or this + setting will be ignored. * `docker.tls.key` - Path to the client's private key (`.pem`). Specify this along with `docker.tls.cert` and `docker.tls.ca` to use a TLS client to - connect to the docker daemon. `docker.endpoint` must also be specified or - this setting will be ignored. + connect to the docker daemon. `docker.endpoint` must also be specified or this + setting will be ignored. * `docker.tls.ca` - Path to the server's CA file (`.pem`). Specify this along with `docker.tls.cert` and `docker.tls.key` to use a TLS client to connect to @@ -666,10 +781,10 @@ options](/docs/configuration/client.html#options): Binding relative paths is always allowed and will be resolved relative to the allocation's directory. -* `docker.volumes.selinuxlabel`: Allows the operator to set a SELinux - label to the allocation and task local bind-mounts to containers. If used - with `docker.volumes.enabled` set to false, the labels will still be applied - to the standard binds in the container. +* `docker.volumes.selinuxlabel`: Allows the operator to set a SELinux label to + the allocation and task local bind-mounts to containers. If used with + `docker.volumes.enabled` set to false, the labels will still be applied to the + standard binds in the container. * `docker.privileged.enabled` Defaults to `false`. Changing this to `true` will allow containers to use `privileged` mode, which gives the containers full @@ -677,11 +792,12 @@ options](/docs/configuration/client.html#options): Docker daemon for this to work. * `docker.caps.whitelist`: A list of allowed Linux capabilities. Defaults to - `"CHOWN,DAC_OVERRIDE,FSETID,FOWNER,MKNOD,NET_RAW,SETGID,SETUID,SETFCAP,SETPCAP,NET_BIND_SERVICE,SYS_CHROOT,KILL,AUDIT_WRITE"`, - which is the list of capabilities allowed by docker by default, as - [defined here](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). - Allows the operator to control which capabilities can be obtained by - tasks using `cap_add` and `cap_drop` options. Supports the value `"ALL"` as a + `"CHOWN,DAC_OVERRIDE,FSETID,FOWNER,MKNOD,NET_RAW,SETGID,SETUID,SETFCAP, + SETPCAP,NET_BIND_SERVICE,SYS_CHROOT,KILL,AUDIT_WRITE"`, which is the list of + capabilities allowed by docker by default, as [defined + here](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). + Allows the operator to control which capabilities can be obtained by tasks + using `cap_add` and `cap_drop` options. Supports the value `"ALL"` as a shortcut for whitelisting all capabilities. * `docker.cleanup.container`: Defaults to `true`. This option can be used to @@ -776,3 +892,5 @@ Windows is relatively new and rapidly evolving you may want to consult the [list of relevant issues on GitHub][WinIssues]. [WinIssues]: https://github.com/hashicorp/nomad/issues?q=is%3Aopen+is%3Aissue+label%3Adriver%2Fdocker+label%3Aplatform-windows +[plugin-options]: #plugin-options +[plugin-stanza]: /docs/configuration/plugin.html diff --git a/website/source/docs/drivers/external/index.html.md b/website/source/docs/drivers/external/index.html.md new file mode 100644 index 000000000..45c2503ff --- /dev/null +++ b/website/source/docs/drivers/external/index.html.md @@ -0,0 +1,19 @@ +--- +layout: "docs" +page_title: "External Plugins" +sidebar_current: "docs-external-plugins" +description: |- + External plugins allow you easily extend Nomad's functionality and further + support customized workloads. +--- + +# External Plugins + +Starting with Nomad 0.9, task and device drivers are now pluggable. This gives users the flexibility to introduce their own drivers without having to recompile Nomad. You can view the [plugin stanza][plugin] documentation for examples on how to use the `plugin` stanza in Nomad's client configuration. + +Below is a list of external drivers you can use with Nomad: + +- [LXC][lxc] + +[lxc]: /docs/drivers/external/lxc.html +[plugin]: /docs/configuration/plugin.html diff --git a/website/source/docs/drivers/external/lxc.html.md b/website/source/docs/drivers/external/lxc.html.md new file mode 100644 index 000000000..819fa60d0 --- /dev/null +++ b/website/source/docs/drivers/external/lxc.html.md @@ -0,0 +1,147 @@ +--- +layout: "docs" +page_title: "Drivers: LXC" +sidebar_current: "docs-external-plugins-lxc" +description: |- + The LXC task driver is used to run application containers using LXC. +--- + +# LXC Driver + +Name: `lxc` + +The `lxc` driver provides an interface for using LXC for running application +containers. You can download the external LXC driver [here][lxc-driver]. + +~> The LXC client set up has changed in Nomad 0.9. You must use the new [plugin syntax][plugin] and install the external LXC driver in the [plugin_dir][plugin_dir] prior to upgrading. See [plugin options][plugin-options] below for an example. Note the job specification remains the same. + +## Task Configuration + +```hcl +task "busybox" { + driver = "lxc" + + config { + log_level = "trace" + verbosity = "verbose" + template = "/usr/share/lxc/templates/lxc-busybox" + } +} +``` + +The `lxc` driver supports the following configuration in the job spec: + +* `template` - The LXC template to run. + + ```hcl + config { + template = "/usr/share/lxc/templates/lxc-alpine" + } + ``` + +* `log_level` - (Optional) LXC library's logging level. Defaults to `error`. + Must be one of `trace`, `debug`, `info`, `warn`, or `error`. + + ```hcl + config { + log_level = "debug" + } + ``` + +* `verbosity` - (Optional) Enables extra verbosity in the LXC library's + logging. Defaults to `quiet`. Must be one of `quiet` or `verbose`. + + ```hcl + config { + verbosity = "quiet" + } + ``` + +* `volumes` - (Optional) A list of `host_path:container_path` strings to bind-mount host paths to container paths. Mounting host paths outside of the allocation directory can be disabled on clients by setting the [`volumes_enabled`](#volumes_enabled) option set to false. This will limit volumes to directories that exist inside the allocation directory. + + Note that unlike the similar option for the docker driver, this + option must not have an absolute path as the `container_path` + component. This will cause an error when submitting a job. + + Setting this does not affect the standard bind-mounts of `alloc`, + `local`, and `secrets`, which are always created. + +```hcl +config { + volumes = [ + # Use absolute paths to mount arbitrary paths on the host + "/path/on/host:path/in/container", + + # Use relative paths to rebind paths already in the allocation dir + "relative/to/task:also/in/container" + ] +} +``` + +## Networking + +Currently the `lxc` driver only supports host networking. See the `none` +networking type in the `lxc.container.conf` [manual][lxc_man] for more +information. + +## Client Requirements + +The `lxc` driver requires the following: + +* 64-bit Linux host +* The `linux_amd64` Nomad binary +* The LXC driver binary placed in the [plugin_dir][plugin_dir] directory. +* `liblxc` to be installed +* `lxc-templates` to be installed + +## Plugin Options + +* `enabled` - The `lxc` driver may be disabled on hosts by setting this option to `false` (defaults to `true`). + +* `volumes_enabled` - Specifies whether host can bind-mount host paths to container paths (defaults to `true`). + +* `lxc_path` - The location in which all containers are stored (commonly defaults to `/var/lib/lxc`). See [`lxc-create`][lxc-create] for more details. + +An example of using these plugin options with the new [plugin +syntax][plugin] is shown below: + +```hcl +plugin "nomad-driver-lxc" { + config { + enabled = true + volumes_enabled = true + lxc_path = "/var/lib/lxc" + } +} +``` +Please note the plugin name should match whatever name you have specified for the external driver in the [plugin_dir][plugin_dir] directory. + +## Client Configuration + +~> Only use this section for pre-0.9 releases of Nomad. If you are using Nomad +0.9 or above, please see [plugin options][plugin-options] + +The `lxc` driver has the following [client configuration +options](/docs/configuration/client.html#options): + +* `lxc.enable` - The `lxc` driver may be disabled on hosts by setting this + option to `false` (defaults to `true`). + +## Client Attributes + +The `lxc` driver will set the following client attributes: + +* `driver.lxc` - Set to `1` if LXC is found and enabled on the host node. +* `driver.lxc.version` - Version of `lxc` e.g.: `1.1.0`. + +## Resource Isolation + +This driver supports CPU and memory isolation via the `lxc` library. Network +isolation is not supported as of now. + +[lxc-create]: https://linuxcontainers.org/lxc/manpages/man1/lxc-create.1.html +[lxc-driver]: https://releases.hashicorp.com/nomad-driver-lxc +[lxc_man]: https://linuxcontainers.org/lxc/manpages/man5/lxc.container.conf.5.html#lbAM +[plugin]: /docs/configuration/plugin.html +[plugin_dir]: /docs/configuration/index.html#plugin_dir +[plugin-options]: #plugin_options diff --git a/website/source/docs/drivers/index.html.md b/website/source/docs/drivers/index.html.md index 36168452c..0e208bc7a 100644 --- a/website/source/docs/drivers/index.html.md +++ b/website/source/docs/drivers/index.html.md @@ -12,13 +12,25 @@ Task drivers are used by Nomad clients to execute a task and provide resource isolation. By having extensible task drivers, Nomad has the flexibility to support a broad set of workloads across all major operating systems. -The list of supported task drivers is provided on the left of this page. -Each task driver documents the configuration available in a -[job specification](/docs/job-specification/index.html), the environments it -can be used in, and the resource isolation mechanisms available. +Starting with Nomad 0.9, task drivers are now pluggable. This gives users the +flexibility to introduce their own drivers without having to recompile Nomad. +You can view the [plugin stanza][plugin] documentation for examples on how to +use the `plugin` stanza in Nomad's client configuration. Note that we have +introduced new syntax when specifying driver options in the client configuration +(see [docker][docker_plugin] for an example). Keep in mind that even though all +built-in drivers are now plugins, Nomad remains a single binary and maintains +backwards compatibility except with the `lxc` driver. + +The list of supported task drivers is provided on the left of this page. Each +task driver documents the configuration available in a [job +specification](/docs/job-specification/index.html), the environments it can be +used in, and the resource isolation mechanisms available. Nomad strives to mask the details of running a task from users and instead provides a clean abstraction. It is possible for the same task to be executed -with different isolation levels depending on the client running the task. -The goal is to use the strictest isolation available and gracefully degrade +with different isolation levels depending on the client running the task. The +goal is to use the strictest isolation available and gracefully degrade protections where necessary. + +[plugin]: /docs/configuration/plugin.html +[docker_plugin]: /docs/drivers/docker.html#client-requirements diff --git a/website/source/docs/drivers/lxc.html.md b/website/source/docs/drivers/lxc.html.md deleted file mode 100644 index 4ab17d7f8..000000000 --- a/website/source/docs/drivers/lxc.html.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -layout: "docs" -page_title: "Drivers: LXC" -sidebar_current: "docs-drivers-lxc" -description: |- - The LXC task driver is used to run application containers using LXC. ---- - -# LXC Driver - -Name: `lxc` - -The `lxc` driver provides an interface for using LXC for running application -containers. - -!> **Experimental!** Currently, the LXC driver supports launching containers -via templates but only supports host networking. If both an LXC image and the -host it is run on use upstart or systemd, shutdown signals may be passed from -the container to the host. - -~> LXC is only enabled in the special `linux_amd64_lxc` build of Nomad because -it links to the `liblxc` system library. Use the `lxc` build tag if compiling -Nomad yourself. - -## Task Configuration - -```hcl -task "busybox" { - driver = "lxc" - - config { - log_level = "trace" - verbosity = "verbose" - template = "/usr/share/lxc/templates/lxc-busybox" - } -} -``` - -The `lxc` driver supports the following configuration in the job spec: - -* `template` - The LXC template to run. - - ```hcl - config { - template = "/usr/share/lxc/templates/lxc-alpine" - } - ``` - -* `log_level` - (Optional) LXC library's logging level. Defaults to `error`. - Must be one of `trace`, `debug`, `info`, `warn`, or `error`. - - ```hcl - config { - log_level = "debug" - } - ``` - -* `verbosity` - (Optional) Enables extra verbosity in the LXC library's - logging. Defaults to `quiet`. Must be one of `quiet` or `verbose`. - - ```hcl - config { - verbosity = "quiet" - } - ``` - -* `volumes` - (Optional) A list of `host_path:container_path` strings to bind-mount - host paths to container paths. Mounting host paths outside of the allocation - directory can be disabled on clients by setting the `lxc.volumes.enabled` - option set to false. This will limit volumes to directories that exist inside - the allocation directory. - - Note that unlike the similar option for the docker driver, this - option must not have an absolute path as the `container_path` - component. This will cause an error when submitting a job. - - Setting this does not affect the standard bind-mounts of `alloc`, - `local`, and `secrets`, which are always created. - - ```hcl - config { - volumes = [ - # Use absolute paths to mount arbitrary paths on the host - "/path/on/host:path/in/container", - - # Use relative paths to rebind paths already in the allocation dir - "relative/to/task:also/in/container" - ] - } - ``` - -## Networking - -Currently the `lxc` driver only supports host networking. See the `none` -networking type in the [`lxc.container.conf` manual][lxc_man] for more -information. - -[lxc_man]: https://linuxcontainers.org/lxc/manpages/man5/lxc.container.conf.5.html#lbAM - -## Client Requirements - -The `lxc` driver requires the following: - -* 64-bit Linux host -* The `linux_amd64_lxc` Nomad binary -* `liblxc` to be installed -* `lxc-templates` to be installed - -## Client Configuration - -* `lxc.enable` - The `lxc` driver may be disabled on hosts by setting this - [client configuration][/docs/configuration/client.html##options-parameters] - option to `false` (defaults to `true`). - -## Client Attributes - -The `lxc` driver will set the following client attributes: - -* `driver.lxc` - Set to `1` if LXC is found and enabled on the host node. -* `driver.lxc.version` - Version of `lxc` e.g.: `1.1.0`. - -## Resource Isolation - -This driver supports CPU and memory isolation via the `lxc` library. Network -isolation is not supported as of now. diff --git a/website/source/docs/drivers/raw_exec.html.md b/website/source/docs/drivers/raw_exec.html.md index 3067e3fd3..aea7abff6 100644 --- a/website/source/docs/drivers/raw_exec.html.md +++ b/website/source/docs/drivers/raw_exec.html.md @@ -32,7 +32,7 @@ The `raw_exec` driver supports the following configuration in the job spec: * `command` - The command to execute. Must be provided. If executing a binary that exists on the host, the path must be absolute. If executing a binary that is downloaded from an [`artifact`](/docs/job-specification/artifact.html), the - path can be relative from the allocations's root directory. + path can be relative from the allocation's root directory. * `args` - (Optional) A list of arguments to the `command`. References to environment variables or any [interpretable Nomad @@ -78,8 +78,18 @@ task "example" { The `raw_exec` driver can run on all supported operating systems. For security reasons, it is disabled by default. To enable raw exec, the Nomad client -configuration must explicitly enable the `raw_exec` driver in the client's -[options](/docs/configuration/client.html#options): +configuration must explicitly enable the `raw_exec` driver in the plugin's options: + +``` +plugin "raw_exec" { + config { + enabled = true + } +} +``` + +Prior to Nomad 0.9, the client configuration would look like this (this syntax +will soon be deprecated): ``` client { @@ -89,10 +99,24 @@ client { } ``` +## Plugin Options + +* `enabled` - Specifies whether the driver should be enabled or disabled. + Defaults to `false`. + +* `no_cgroups` - Specifies whether the driver should not use + cgroups to manage the process group launched by the driver. By default, + cgroups are used to manage the process tree to ensure full cleanup of all + processes started by the task. The driver only uses cgroups when Nomad is + launched as root, on Linux and when cgroups are detected. + ## Client Options +~> Note: client configuration options will soon be deprecated. Please use +[plugin options][plugin-options] instead. See the [plugin stanza][plugin-stanza] documentation for more information. + * `driver.raw_exec.enable` - Specifies whether the driver should be enabled or - disabled. + disabled. Defaults to `false`. * `driver.raw_exec.no_cgroups` - Specifies whether the driver should not use cgroups to manage the process group launched by the driver. By default, @@ -114,5 +138,8 @@ If the launched process creates a new process group, it is possible that Nomad will leak processes on shutdown unless the application forwards signals properly. Nomad will not leak any processes if cgroups are being used to manage the process tree. Cgroups are used on Linux when Nomad is being run with -appropriate priviledges, the cgroup system is mounted and the operator hasn't +appropriate privileges, the cgroup system is mounted and the operator hasn't disabled cgroups for the driver. + +[plugin-options]: #plugin-options +[plugin-stanza]: /docs/configuration/plugin.html diff --git a/website/source/docs/drivers/rkt.html.md b/website/source/docs/drivers/rkt.html.md index c1f271507..aa969f578 100644 --- a/website/source/docs/drivers/rkt.html.md +++ b/website/source/docs/drivers/rkt.html.md @@ -168,12 +168,20 @@ The `trust_prefix` must be accessible by the node running Nomad. This can be an internal source, private to your cluster, but it must be reachable by the client over HTTP. +## Plugin Options + +* `volumes_enabled` - Defaults to `true`. Allows tasks to bind host paths + (`volumes`) inside their container. Binding relative paths is always allowed + and will be resolved relative to the allocation's directory. + ## Client Configuration +~> Note: client configuration options will soon be deprecated. Please use [plugin options][plugin-options] instead. See the [plugin stanza][plugin-stanza] documentation for more information. + The `rkt` driver has the following [client configuration options](/docs/configuration/client.html#options): -* `rkt.volumes.enabled`: Defaults to `true`. Allows tasks to bind host paths +* `rkt.volumes.enabled` - Defaults to `true`. Allows tasks to bind host paths (`volumes`) inside their container. Binding relative paths is always allowed and will be resolved relative to the allocation's directory. @@ -208,3 +216,5 @@ isolation is not supported as of now. [user]: /docs/job-specification/task.html#user +[plugin-options]: #plugin-options +[plugin-stanza]: /docs/configuration/plugin.html diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 484c79559..84b1160ea 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -430,10 +430,6 @@ Java - > - LXC - - > Qemu @@ -447,9 +443,6 @@ Rkt - > - Custom - @@ -486,6 +479,10 @@ Vault Integration + > + External Plugins + +
>