From cbacdb2041cb5fa534a792bd7ab9e90e8818fce5 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Mon, 5 Aug 2024 13:35:54 -0500 Subject: [PATCH] DOCS: CE-659 chroot limitations for isolated fork/exec driver (#23739) --- website/content/docs/configuration/client.mdx | 15 +++++++-------- website/content/docs/drivers/exec.mdx | 19 ++++++++++--------- .../content/partials/chroot-limitations.mdx | 3 +++ 3 files changed, 20 insertions(+), 17 deletions(-) create mode 100644 website/content/partials/chroot-limitations.mdx diff --git a/website/content/docs/configuration/client.mdx b/website/content/docs/configuration/client.mdx index 657f1cae9..6de90ccd3 100644 --- a/website/content/docs/configuration/client.mdx +++ b/website/content/docs/configuration/client.mdx @@ -214,9 +214,8 @@ client { ### `chroot_env` Parameters -Drivers based on [isolated fork/exec](/nomad/docs/drivers/exec) implement file -system isolation using chroot on Linux. The `chroot_env` map allows the chroot -environment to be configured using source paths on the host operating system. +On Linux, drivers based on [isolated fork/exec](/nomad/docs/drivers/exec) implement file system isolation using chroot. The `chroot_env` map lets you configure the chroot environment using source paths on the host operating system. + The mapping format is: ```text @@ -240,13 +239,13 @@ client { } ``` -When `chroot_env` is unspecified, the `exec` driver will use a default chroot -environment with the most commonly used parts of the operating system. Please -see the [Nomad `exec` driver documentation](/nomad/docs/drivers/exec#chroot) for +@include 'chroot-limitations.mdx' + +When `chroot_env` is unspecified, the `exec` driver uses a default chroot +environment with the most commonly used parts of the operating system. Refer to the [Nomad `exec` driver documentation](/nomad/docs/drivers/exec#chroot) for the full list. -Nomad will never attempt to embed the `alloc_dir` in the -chroot as doing so would cause infinite recursion. +Nomad never attempts to embed the `alloc_dir` in the chroot as doing so would cause infinite recursion. ### `options` Parameters diff --git a/website/content/docs/drivers/exec.mdx b/website/content/docs/drivers/exec.mdx index d14588956..a1e46c910 100644 --- a/website/content/docs/drivers/exec.mdx +++ b/website/content/docs/drivers/exec.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: 'Drivers: Exec' -description: The Exec task driver is used to run binaries using OS isolation primitives. +description: The Exec task driver runs binaries using OS isolation primitives. --- # Isolated Fork/Exec Driver @@ -229,8 +229,9 @@ on [cgroup controller requirements][] for more details. ### Chroot -The chroot is populated with data in the following directories from the host -machine: +Chroot changes the root directory of the current process and all its child processes. Nomad uses a chroot environment to implement file system isolation. + +Nomad populates the chroot environment with data in the following host machine directories: ``` [ @@ -245,13 +246,13 @@ machine: ] ``` -The task's chroot is populated by linking or copying the data from the host into -the chroot. Note that this can take considerable disk space. Since Nomad v0.5.3, -the client manages garbage collection locally which mitigates any issue this may -create. +Nomad populates the task's chroot environment by linking or copying the data from the host into the chroot. Note that this can take considerable disk space. +The client manages garbage collection locally, which mitigates any issue this may create. -This list is configurable through the agent client -[configuration file](/nomad/docs/configuration/client#chroot_env). +@include 'chroot-limitations.mdx' + +Configure the chroot environment list through the agent client's +[`chroot_env` attribute](/nomad/docs/configuration/client#chroot_env). ### CPU diff --git a/website/content/partials/chroot-limitations.mdx b/website/content/partials/chroot-limitations.mdx new file mode 100644 index 000000000..f576d37e9 --- /dev/null +++ b/website/content/partials/chroot-limitations.mdx @@ -0,0 +1,3 @@ +!> **Warning chroot limitations:** Nomad by default doesn't copy the ephemeral runtime files in the `/run` directory. For exampe, on Ubuntu, `/etc/resolv.conf` is a symlink to `/run/systemd/resolve/stub-resolv.conf`, so Nomad doesn't copy `resolv.conf` to the chroot environment. + +In these cases, configure your job's [network block](/nomad/docs/job-specification/network) for each chroot task.