docs: clarify task working directories (#9098)

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.

Co-authored-by: Charlie Voiselle <464492+angrycub@users.noreply.github.com>

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,9 @@ nomad alloc fs [options] <allocation> <path>
 ```
 
 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 optional and relative to the root of the [allocation working
+directory].
 
 ## General Options
 
@@ -108,3 +108,5 @@ nomad alloc fs -job <job-id> <path>
 
 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 'Task Directories'

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 'Task directories'

website/pages/docs/drivers/docker.mdx

@@ -267,11 +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
-  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] 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 {
@@ -1022,3 +1024,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 'Task Directories'

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 'Task Directories'

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 'Task Directories'

website/pages/docs/drivers/external/lxc.mdx

@@ -71,7 +71,12 @@ 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] 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`
@@ -187,3 +192,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 'Task Directories'

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 'Task Directories'

website/pages/docs/job-specification/template.mdx

@@ -59,7 +59,11 @@ 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: <required>)` - 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 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))
@@ -220,6 +224,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. 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" {
+  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 +378,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 Directories'

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.