From 3a3374d06fedc66f60829dbd1f8e709c58c295bb Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Tue, 28 Mar 2023 11:53:46 -0400 Subject: [PATCH] docs: clarify capabilities options for `docker` driver The `docker` driver cannot expand capabilities beyond the default set when the task is a non-root user. Clarify this in the documentation of `allow_caps` and update the `cap_add` and `cap_drop` to match the `exec` driver, which has more clear language overall. --- website/content/docs/drivers/docker.mdx | 37 ++++++++++++++----------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/website/content/docs/drivers/docker.mdx b/website/content/docs/drivers/docker.mdx index c2b4919e01e..322d540085d 100644 --- a/website/content/docs/drivers/docker.mdx +++ b/website/content/docs/drivers/docker.mdx @@ -504,11 +504,11 @@ config { } ``` -- `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 allowlist. - The allowlist can be customized using the [`allow_caps`][allow_caps] plugin option key in the client node's configuration. - For example: +- `cap_add` - (Optional) A list of Linux capabilities as strings to pass + directly to [`--cap-add`][]. Effective capabilities (computed from `cap_add` + and `cap_drop`) must be a subset of the allowed capabilities configured with + the [`allow_caps`][allow_caps] plugin option key in the client node's + configuration. For example: ```hcl config { @@ -516,11 +516,11 @@ config { } ``` -- `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 allowlist. - The allowlist can be customized using the [`allow_caps`][allow_caps] plugin option key in the client node's configuration. - For example: +- `cap_drop` - (Optional) A list of Linux capabilities as strings to pass + directly to [`--cap-drop`][]. Effective capabilities (computed from `cap_add` + and `cap_drop`) must be a subset of the allowed capabilities configured with + the [`allow_caps`][allow_caps] plugin option key in the client node's + configuration. For example: ```hcl config { @@ -884,11 +884,14 @@ plugin "docker" { "net_bind_service", "setfcap", "setgid", "setpcap", "setuid", "sys_chroot"] ``` - which is the same list of capabilities allowed by [docker by default][docker_caps] - (without [`NET_RAW`][no_net_raw]). Allows the operator to control which capabilities can be obtained - by tasks using [`cap_add`][cap_add] and [`cap_drop`][cap_drop] options. Supports - the value `"all"` as a shortcut for allow-listing all capabilities supported by - the operating system. + which is the same list of capabilities allowed by [docker by + default][docker_caps] (without [`NET_RAW`][no_net_raw]). Allows the operator + to control which capabilities can be obtained by tasks using + [`cap_add`][cap_add] and [`cap_drop`][cap_drop] options. Supports the value + `"all"` as a shortcut for allow-listing all capabilities supported by the + operating system. Note that due to a limitation in Docker, tasks running as + non-root users cannot expand the capabilities set beyond the default. They can + only have their capabilities reduced. !> **Warning:** Allowing more capabilities beyond the default may lead to undesirable consequences, including untrusted tasks being able to compromise the @@ -1219,4 +1222,6 @@ Windows is relatively new and rapidly evolving you may want to consult the [`pids_limit`]: /nomad/docs/drivers/docker#pids_limit [Windows isolation]: https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container [cores]: /nomad/docs/job-specification/resources#cores -[runtime_env]: /nomad/docs/runtime/environment#job-related-variables \ No newline at end of file +[runtime_env]: /nomad/docs/runtime/environment#job-related-variables +[`--cap-add`][](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) +[`--cap-drop`][](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)