From 75f269d08da6442ba6260b8dd64d2bb5401aec41 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Thu, 15 Oct 2020 09:53:25 -0400 Subject: [PATCH 1/6] docs: clarify task working directories The terms task directory and allocation directory are used throughout the documentation but these directories are not the same as the `NOMAD_TASK_DIR` and `NOMAD_ALLOC_DIR` locations. This is confusing when trying to use the `template` and `artifact` stanzas, especially when trying to use a destination outside the Nomad-mounted directories for Docker and similar drivers. This changeset introduces "allocation working directory" to mean the location on disk where the various directories and artifacts are staged, and "task working directory" for the task. Clarify how specific task drivers interact with the task working directory. --- website/pages/docs/commands/alloc/fs.mdx | 15 +++++--- website/pages/docs/configuration/client.mdx | 3 +- website/pages/docs/drivers/docker.mdx | 12 +++--- .../external/firecracker-task-driver.mdx | 5 ++- .../drivers/external/jail-task-driver.mdx | 3 +- website/pages/docs/drivers/external/lxc.mdx | 7 +++- .../pages/docs/job-specification/artifact.mdx | 14 ++++--- .../pages/docs/job-specification/template.mdx | 37 ++++++++++++++++++- website/pages/docs/runtime/environment.mdx | 14 +++++-- 9 files changed, 83 insertions(+), 27 deletions(-) diff --git a/website/pages/docs/commands/alloc/fs.mdx b/website/pages/docs/commands/alloc/fs.mdx index 25a404924..e9eb9a440 100644 --- a/website/pages/docs/commands/alloc/fs.mdx +++ b/website/pages/docs/commands/alloc/fs.mdx @@ -10,9 +10,9 @@ description: | **Alias: `nomad fs`** -The `alloc fs` command allows a user to navigate an allocation directory on a Nomad -client. The following functionalities are available - `cat`, `tail`, `ls` and -`stat`. +The `alloc fs` command allows a user to navigate an [allocation working +directory] on a Nomad client. The following functionalities are available - +`cat`, `tail`, `ls` and `stat`. - `cat`: If the target path is a file, Nomad will `cat` the file. @@ -32,9 +32,10 @@ nomad alloc fs [options] ``` This command accepts a single allocation ID (unless the `-job` flag is -specified, in which case an allocation is chosen from the given job) and a path. -The path is relative to the root of the allocation directory. The path is -optional and it defaults to `/` of the allocation directory. +specified, in which case an allocation is chosen from the given job) and a +path. The path is relative to the root of the [allocation working +directory]. The path is optional and it defaults to `/` of the allocation +directory. ## General Options @@ -108,3 +109,5 @@ nomad alloc fs -job This can be useful for debugging a job that has multiple allocations, and it is not required to observe a specific allocation. + +[allocation working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/configuration/client.mdx b/website/pages/docs/configuration/client.mdx index 1b713c816..620527782 100644 --- a/website/pages/docs/configuration/client.mdx +++ b/website/pages/docs/configuration/client.mdx @@ -350,7 +350,7 @@ see the [drivers documentation](/docs/drivers). - `disable_file_sandbox` `(bool: false)` - Allows templates access to arbitrary files on the client host via the `file` function. By default templates can - access files only within the task directory. + access files only within the [task working directory]. ### `host_volume` Stanza @@ -469,3 +469,4 @@ client { [plugin-stanza]: /docs/configuration/plugin [server-join]: /docs/configuration/server_join 'Server Join' [metadata_constraint]: /docs/job-specification/constraint#user-specified-metadata 'Nomad User-Specified Metadata Constraint Example' +[task working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/drivers/docker.mdx b/website/pages/docs/drivers/docker.mdx index 5986bdb51..3cf0ee110 100644 --- a/website/pages/docs/drivers/docker.mdx +++ b/website/pages/docs/drivers/docker.mdx @@ -267,11 +267,12 @@ The `docker` driver supports the following configuration in the job spec. Only docker daemon. - `volumes` - (Optional) A list of `host_path:container_path` strings to bind - host paths to container paths. Mounting host paths outside of the allocation - directory can be disabled on clients by setting the `docker.volumes.enabled` - option set to false. This will limit volumes to directories that exist inside - the allocation directory. We recommend using [`mounts`](#mounts) if you wish - to have more control over volume definitions. + host paths to container paths. Mounting host paths outside of the + [allocation working directory] can be disabled on clients by setting the + `docker.volumes.enabled` option set to false. This will limit volumes to + directories that exist inside the allocation working directory. We recommend + using [`mounts`](#mounts) if you wish to have more control over volume + definitions. ```hcl config { @@ -1022,3 +1023,4 @@ Windows is relatively new and rapidly evolving you may want to consult the [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 +[allocation working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/drivers/external/firecracker-task-driver.mdx b/website/pages/docs/drivers/external/firecracker-task-driver.mdx index 00f1a0f7d..1c5b91062 100644 --- a/website/pages/docs/drivers/external/firecracker-task-driver.mdx +++ b/website/pages/docs/drivers/external/firecracker-task-driver.mdx @@ -34,10 +34,10 @@ task "test01" { The firecracker task driver supports the following parameters: - `KernelImage` - (Optional) Path to the kernel image to be used on the microvm. - Defaults to 'vmlinux' on nomad's allocation directory. + Defaults to 'vmlinux' in the [allocation working directory]. - `BootDisk` - (Optional) Path to the ext4 rootfs to boot from. - Defaults to 'rootfs.ext4' on nomad's allocation directory. + Defaults to 'rootfs.ext4' in the [allocation working directory]. - `BootOptions` - (Optional) Kernel command line options to boot the microvm. Defaults to "ro console=ttyS0 reboot=k panic=1 pci=off" @@ -129,3 +129,4 @@ match the name of the network, and use the .conflist extension. [container network plugins]: https://github.com/containernetworking/plugins [firecracker binary]: https://github.com/firecracker-microvm/firecracker/releases [firecracker-task-guide]: https://github.com/cneira/firecracker-task-driver +[allocation working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/drivers/external/jail-task-driver.mdx b/website/pages/docs/drivers/external/jail-task-driver.mdx index a880fca82..6fc9b8d16 100644 --- a/website/pages/docs/drivers/external/jail-task-driver.mdx +++ b/website/pages/docs/drivers/external/jail-task-driver.mdx @@ -43,7 +43,7 @@ task "http-echo-jail" { The Jail task driver supports most of [JAIL(8)][jail(8)] parameters, for a list of the currently supported parameters, please refer to the [Parameter Documentation][parameter-doc]. - `Path` - (Optional) The directory which is to be the root of the jail. - Defaults to nomad's allocation directory. + Defaults to the [allocation working directory]. - `Ip4` - (Optional) Control the availability of IPv4 addresses. Possible values are **"inherit"** to allow unrestricted access to all system addresses, @@ -147,3 +147,4 @@ startup or the `Vnet` parameter to create a virtual network stack. Please refer [rctl-doc]: https://www.freebsd.org/doc/handbook/security-resourcelimits.html [parameter-doc]: https://github.com/cneira/jail-task-driver/blob/master/Parameters.md [plugin_dir]: /docs/configuration#plugin_dir +[allocation working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/drivers/external/lxc.mdx b/website/pages/docs/drivers/external/lxc.mdx index 0b5457cc6..26d3928c8 100644 --- a/website/pages/docs/drivers/external/lxc.mdx +++ b/website/pages/docs/drivers/external/lxc.mdx @@ -71,7 +71,11 @@ The `lxc` driver supports the following configuration in the job spec: } ``` -- `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. +- `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 working 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:** Unlike the similar option for the docker driver, this option must not have an absolute path as the `container_path` @@ -187,3 +191,4 @@ isolation is not supported as of now. [plugin_dir]: /docs/configuration#plugin_dir [plugin-options]: #plugin-options [client_options]: /docs/configuration/client#options +[allocation working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/job-specification/artifact.mdx b/website/pages/docs/job-specification/artifact.mdx index 9338e935d..0ae7c0ef6 100644 --- a/website/pages/docs/job-specification/artifact.mdx +++ b/website/pages/docs/job-specification/artifact.mdx @@ -39,11 +39,11 @@ automatically unarchived before the starting the task. ## `artifact` Parameters -- `destination` `(string: "local/")` - Specifies the directory path to download - the artifact, relative to the root of the task's directory. If omitted, the - default value is to place the artifact in `local/`. The destination is treated - as a directory unless `mode` is set to `file`. Source files will be downloaded - into that directory path. +- `destination` `(string: "local/")` - Specifies the directory path to + download the artifact, relative to the root of the [task's working + directory]. If omitted, the default value is to place the artifact in + `local/`. The destination is treated as a directory unless `mode` is set to + `file`. Source files will be downloaded into that directory path. - `mode` `(string: "any")` - One of `any`, `file`, or `dir`. If set to `file` the `destination` must be a file, not a directory. By default the @@ -65,7 +65,8 @@ The following examples only show the `artifact` stanzas. Remember that the ### Download File This example downloads the artifact from the provided URL and places it in -`local/file.txt`. The `local/` path is relative to the task's directory. +`local/file.txt`. The `local/` path is relative to the [task's working +directory]. ```hcl artifact { @@ -187,3 +188,4 @@ artifact { [s3-bucket-addr]: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro 'Amazon S3 Bucket Addressing' [s3-region-endpoints]: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region 'Amazon S3 Region Endpoints' [iam-instance-profiles]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html 'EC2 IAM instance profiles' +[task's working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/job-specification/template.mdx b/website/pages/docs/job-specification/template.mdx index a4feba161..c0b8072b7 100644 --- a/website/pages/docs/job-specification/template.mdx +++ b/website/pages/docs/job-specification/template.mdx @@ -59,7 +59,10 @@ README][ct]. Since Nomad v0.6.0, templates can be read as environment variables. templates, but we recommend using `source` for larger templates. - `destination` `(string: )` - Specifies the location where the - resulting template should be rendered, relative to the task directory. + resulting template should be rendered, relative to the [task working + directory]. Only drivers that build a chroot into the task working directory + (such as `exec` or `raw_exec`) can render templates outside of the + `NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, or `NOMAD_SECRETS_DIR`. - `env` `(bool: false)` - Specifies the template should be read back in as environment variables for the task. ([See below](#environment-variables)) @@ -220,6 +223,37 @@ DB_PASSWD={{ .Data.data.DB_PASSWD | toJSON }} For more details see [go-envparser's README][go-envparse]. +### Template Destinations + +Templates are rendered into the task working directory. Some drivers such as +`exec` or `raw_exec` build a chroot in the task working directory, so +templates can be rendered to arbitrary paths in the task. But task drivers +such as `docker` can only access templates rendered into the +`NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, or `NOMAD_SECRETS_DIR`. To workaround +this restriction, you can create a mount from the template `destination` to +another location in the task. + +```hcl +task "task" { + driver = "docker" + + config { + image = "redis:6.0" + mounts = [ + { + type = "bind" + source = "local" + target = "/etc/redis.d" + } + ] + } + + template { + destination = "local/redis.conf" + } +} +``` + ## Vault Integration ### PKI Certificate @@ -343,3 +377,4 @@ options](/docs/configuration/client#options): [env]: /docs/runtime/environment 'Nomad Runtime Environment' [nodevars]: /docs/runtime/interpolation#interpreted_node_vars 'Nomad Node Variables' [go-envparse]: https://github.com/hashicorp/go-envparse#readme 'The go-envparse Readme' +[task working directory]: /docs/runtime/environment 'Task Directories' diff --git a/website/pages/docs/runtime/environment.mdx b/website/pages/docs/runtime/environment.mdx index 03313bfbf..a8ff11d61 100644 --- a/website/pages/docs/runtime/environment.mdx +++ b/website/pages/docs/runtime/environment.mdx @@ -59,7 +59,12 @@ details. ### Task Directories -Nomad makes the following directories available to tasks: +Nomad creates a working directory for each allocation on a client. The +allocation working directory contains a task working directory for each task +in the allocation. + +Nomad makes the following directories available to tasks, relative to the task +working directory: - `alloc/`: This directory is shared across all tasks in a task group and can be used to store data that needs to be used by multiple tasks, such as a log @@ -75,9 +80,10 @@ These directories are persisted until the allocation is removed, which occurs hours after all the tasks in the task group enter terminal states. This gives time to view the data produced by tasks. -Depending on the driver and operating system being targeted, the directories are -made available in various ways. For example, on `docker` the directories are -bound to the container, while on `exec` on Linux the directories are mounted into the +Depending on the driver and operating system being targeted, the directories +are made available in various ways. For example, on `docker` the directories +are bound to the container, while on `exec` on Linux the chroot is built in +the task working directory, and the directories are mounted into that chroot. Regardless of how the directories are made available, the path to the directories can be read through the `NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, and `NOMAD_SECRETS_DIR` environment variables. From f3c7879dc7c0d5cca50e6adc4c87aaaa06045cac Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Thu, 15 Oct 2020 10:20:56 -0400 Subject: [PATCH 2/6] fix anchor links --- website/pages/docs/commands/alloc/fs.mdx | 2 +- website/pages/docs/configuration/client.mdx | 2 +- website/pages/docs/drivers/docker.mdx | 2 +- website/pages/docs/drivers/external/firecracker-task-driver.mdx | 2 +- website/pages/docs/drivers/external/jail-task-driver.mdx | 2 +- website/pages/docs/drivers/external/lxc.mdx | 2 +- website/pages/docs/job-specification/artifact.mdx | 2 +- website/pages/docs/job-specification/template.mdx | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/website/pages/docs/commands/alloc/fs.mdx b/website/pages/docs/commands/alloc/fs.mdx index e9eb9a440..03ddd1d2b 100644 --- a/website/pages/docs/commands/alloc/fs.mdx +++ b/website/pages/docs/commands/alloc/fs.mdx @@ -110,4 +110,4 @@ nomad alloc fs -job This can be useful for debugging a job that has multiple allocations, and it is not required to observe a specific allocation. -[allocation working directory]: /docs/runtime/environment 'Task Directories' +[allocation working directory]: /docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/pages/docs/configuration/client.mdx b/website/pages/docs/configuration/client.mdx index 620527782..7283ec00b 100644 --- a/website/pages/docs/configuration/client.mdx +++ b/website/pages/docs/configuration/client.mdx @@ -469,4 +469,4 @@ client { [plugin-stanza]: /docs/configuration/plugin [server-join]: /docs/configuration/server_join 'Server Join' [metadata_constraint]: /docs/job-specification/constraint#user-specified-metadata 'Nomad User-Specified Metadata Constraint Example' -[task working directory]: /docs/runtime/environment 'Task Directories' +[task working directory]: /docs/runtime/environment#task-directories 'Task directories' diff --git a/website/pages/docs/drivers/docker.mdx b/website/pages/docs/drivers/docker.mdx index 3cf0ee110..fbae2f272 100644 --- a/website/pages/docs/drivers/docker.mdx +++ b/website/pages/docs/drivers/docker.mdx @@ -1023,4 +1023,4 @@ Windows is relatively new and rapidly evolving you may want to consult the [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 -[allocation working directory]: /docs/runtime/environment 'Task Directories' +[allocation working directory]: /docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/pages/docs/drivers/external/firecracker-task-driver.mdx b/website/pages/docs/drivers/external/firecracker-task-driver.mdx index 1c5b91062..0fb5fa2cd 100644 --- a/website/pages/docs/drivers/external/firecracker-task-driver.mdx +++ b/website/pages/docs/drivers/external/firecracker-task-driver.mdx @@ -129,4 +129,4 @@ match the name of the network, and use the .conflist extension. [container network plugins]: https://github.com/containernetworking/plugins [firecracker binary]: https://github.com/firecracker-microvm/firecracker/releases [firecracker-task-guide]: https://github.com/cneira/firecracker-task-driver -[allocation working directory]: /docs/runtime/environment 'Task Directories' +[allocation working directory]: /docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/pages/docs/drivers/external/jail-task-driver.mdx b/website/pages/docs/drivers/external/jail-task-driver.mdx index 6fc9b8d16..4c6d52489 100644 --- a/website/pages/docs/drivers/external/jail-task-driver.mdx +++ b/website/pages/docs/drivers/external/jail-task-driver.mdx @@ -147,4 +147,4 @@ startup or the `Vnet` parameter to create a virtual network stack. Please refer [rctl-doc]: https://www.freebsd.org/doc/handbook/security-resourcelimits.html [parameter-doc]: https://github.com/cneira/jail-task-driver/blob/master/Parameters.md [plugin_dir]: /docs/configuration#plugin_dir -[allocation working directory]: /docs/runtime/environment 'Task Directories' +[allocation working directory]: /docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/pages/docs/drivers/external/lxc.mdx b/website/pages/docs/drivers/external/lxc.mdx index 26d3928c8..36e9af36f 100644 --- a/website/pages/docs/drivers/external/lxc.mdx +++ b/website/pages/docs/drivers/external/lxc.mdx @@ -191,4 +191,4 @@ isolation is not supported as of now. [plugin_dir]: /docs/configuration#plugin_dir [plugin-options]: #plugin-options [client_options]: /docs/configuration/client#options -[allocation working directory]: /docs/runtime/environment 'Task Directories' +[allocation working directory]: /docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/pages/docs/job-specification/artifact.mdx b/website/pages/docs/job-specification/artifact.mdx index 0ae7c0ef6..2a9d074f3 100644 --- a/website/pages/docs/job-specification/artifact.mdx +++ b/website/pages/docs/job-specification/artifact.mdx @@ -188,4 +188,4 @@ artifact { [s3-bucket-addr]: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro 'Amazon S3 Bucket Addressing' [s3-region-endpoints]: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region 'Amazon S3 Region Endpoints' [iam-instance-profiles]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html 'EC2 IAM instance profiles' -[task's working directory]: /docs/runtime/environment 'Task Directories' +[task's working directory]: /docs/runtime/environment#task-directories 'Task Directories' diff --git a/website/pages/docs/job-specification/template.mdx b/website/pages/docs/job-specification/template.mdx index c0b8072b7..027630a39 100644 --- a/website/pages/docs/job-specification/template.mdx +++ b/website/pages/docs/job-specification/template.mdx @@ -377,4 +377,4 @@ options](/docs/configuration/client#options): [env]: /docs/runtime/environment 'Nomad Runtime Environment' [nodevars]: /docs/runtime/interpolation#interpreted_node_vars 'Nomad Node Variables' [go-envparse]: https://github.com/hashicorp/go-envparse#readme 'The go-envparse Readme' -[task working directory]: /docs/runtime/environment 'Task Directories' +[task working directory]: /docs/runtime/environment#task-directories 'Task Directories' From 25818cefbf6ecd4ef6b5465bf3b00cc0918a5809 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Fri, 16 Oct 2020 10:19:12 -0400 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Charlie Voiselle <464492+angrycub@users.noreply.github.com> --- website/pages/docs/commands/alloc/fs.mdx | 5 ++--- website/pages/docs/drivers/docker.mdx | 13 +++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/website/pages/docs/commands/alloc/fs.mdx b/website/pages/docs/commands/alloc/fs.mdx index 03ddd1d2b..cb65e51a3 100644 --- a/website/pages/docs/commands/alloc/fs.mdx +++ b/website/pages/docs/commands/alloc/fs.mdx @@ -33,9 +33,8 @@ nomad alloc fs [options] This command accepts a single allocation ID (unless the `-job` flag is specified, in which case an allocation is chosen from the given job) and a -path. The path is relative to the root of the [allocation working -directory]. The path is optional and it defaults to `/` of the allocation -directory. +path. The path is optional and relative to the root of the [allocation working +directory]. ## General Options diff --git a/website/pages/docs/drivers/docker.mdx b/website/pages/docs/drivers/docker.mdx index fbae2f272..271fb5eb6 100644 --- a/website/pages/docs/drivers/docker.mdx +++ b/website/pages/docs/drivers/docker.mdx @@ -267,12 +267,13 @@ The `docker` driver supports the following configuration in the job spec. Only docker daemon. - `volumes` - (Optional) A list of `host_path:container_path` strings to bind - host paths to container paths. Mounting host paths outside of the - [allocation working directory] can be disabled on clients by setting the - `docker.volumes.enabled` option set to false. This will limit volumes to - directories that exist inside the allocation working directory. We recommend - using [`mounts`](#mounts) if you wish to have more control over volume - definitions. + host paths to container paths. Mounting host paths outside of the [allocation + working directory] is prevented by default and limits volumes to directories + that exist inside the allocation working directory. You can allow mounting + host paths outside of the [allocation working directory] on individual clients + by setting the `docker.volumes.enabled` option to `true` in the client's + configuration. We recommend using [`mounts`](#mounts) if you wish to have more + control over volume definitions. ```hcl config { From daaf9ca558778685454bd129f1316145eaac7f93 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Fri, 16 Oct 2020 11:38:23 -0400 Subject: [PATCH 4/6] clarify raw_exec doesn't have filesystem isolation --- .../pages/docs/job-specification/template.mdx | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/website/pages/docs/job-specification/template.mdx b/website/pages/docs/job-specification/template.mdx index 027630a39..aa2c462bd 100644 --- a/website/pages/docs/job-specification/template.mdx +++ b/website/pages/docs/job-specification/template.mdx @@ -60,9 +60,10 @@ README][ct]. Since Nomad v0.6.0, templates can be read as environment variables. - `destination` `(string: )` - Specifies the location where the resulting template should be rendered, relative to the [task working - directory]. Only drivers that build a chroot into the task working directory - (such as `exec` or `raw_exec`) can render templates outside of the - `NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, or `NOMAD_SECRETS_DIR`. + directory]. Only drivers without filesystem isolation (ex. `raw_exec`) or + that buiold a chroot in the task working directory (ex. `exec`) can render + templates outside of the `NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, or + `NOMAD_SECRETS_DIR`. - `env` `(bool: false)` - Specifies the template should be read back in as environment variables for the task. ([See below](#environment-variables)) @@ -225,13 +226,13 @@ For more details see [go-envparser's README][go-envparse]. ### Template Destinations -Templates are rendered into the task working directory. Some drivers such as -`exec` or `raw_exec` build a chroot in the task working directory, so -templates can be rendered to arbitrary paths in the task. But task drivers -such as `docker` can only access templates rendered into the -`NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, or `NOMAD_SECRETS_DIR`. To workaround -this restriction, you can create a mount from the template `destination` to -another location in the task. +Templates are rendered into the task working directory. Drivers without +filesystem isolation (such as `raw_exec`) or drivers that build a chroot in +the task working directory (such as `exec`) can have templates rendered to +arbitrary paths in the task. But task drivers such as `docker` can only access +templates rendered into the `NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, or +`NOMAD_SECRETS_DIR`. To workaround this restriction, you can create a mount +from the template `destination` to another location in the task. ```hcl task "task" { From 299b5b18aebae4012bdf018d28be7a0e6648ef81 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Fri, 16 Oct 2020 11:40:06 -0400 Subject: [PATCH 5/6] improve language for LXC volumes --- website/pages/docs/drivers/external/lxc.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/website/pages/docs/drivers/external/lxc.mdx b/website/pages/docs/drivers/external/lxc.mdx index 36e9af36f..b81833aa6 100644 --- a/website/pages/docs/drivers/external/lxc.mdx +++ b/website/pages/docs/drivers/external/lxc.mdx @@ -72,10 +72,11 @@ The `lxc` driver supports the following configuration in the job spec: ``` - `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 working 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. + bind-mount host paths to container paths. Mounting host paths outside of the + [allocation working directory] is allowed by default. You can prevent + mounting host paths outside of the [allocation working directory] on + individual clients by setting the [`volumes_enabled`](#volumes_enabled) + option to `false` in the client's configuration``` ~> **Note:** Unlike the similar option for the docker driver, this option must not have an absolute path as the `container_path` From ec67d8150e09e524f5fd44df21aa76fa0db0a86f Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Fri, 16 Oct 2020 12:55:45 -0400 Subject: [PATCH 6/6] Update website/pages/docs/drivers/external/lxc.mdx Co-authored-by: Charlie Voiselle <464492+angrycub@users.noreply.github.com> --- website/pages/docs/drivers/external/lxc.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/pages/docs/drivers/external/lxc.mdx b/website/pages/docs/drivers/external/lxc.mdx index b81833aa6..4fae13824 100644 --- a/website/pages/docs/drivers/external/lxc.mdx +++ b/website/pages/docs/drivers/external/lxc.mdx @@ -76,7 +76,7 @@ The `lxc` driver supports the following configuration in the job spec: [allocation working directory] is allowed by default. You can prevent mounting host paths outside of the [allocation working directory] on individual clients by setting the [`volumes_enabled`](#volumes_enabled) - option to `false` in the client's configuration``` + option to `false` in the client's configuration ~> **Note:** Unlike the similar option for the docker driver, this option must not have an absolute path as the `container_path`