From 4fad037af92cd753b91df8a5a8bbbeb1e51e84b6 Mon Sep 17 00:00:00 2001 From: hc-github-team-nomad-core <82989552+hc-github-team-nomad-core@users.noreply.github.com> Date: Tue, 28 Mar 2023 13:39:52 -0400 Subject: [PATCH] docs: clarify capabilities options for `docker` driver (#16693) (#16699) 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. Co-authored-by: Tim Gross --- website/content/docs/drivers/docker.mdx | 48 ++++++++++++++----------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/website/content/docs/drivers/docker.mdx b/website/content/docs/drivers/docker.mdx index 58356840eef..08508ea664a 100644 --- a/website/content/docs/drivers/docker.mdx +++ b/website/content/docs/drivers/docker.mdx @@ -501,11 +501,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 { @@ -513,11 +513,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 { @@ -881,11 +881,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 @@ -1204,8 +1207,13 @@ Windows is relatively new and rapidly evolving you may want to consult the [upgrade_guide_extra_hosts]: /docs/upgrade/upgrade-specific#docker-driver [tini]: https://github.com/krallin/tini [docker_caps]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities -[allow_caps]: /docs/drivers/docker#allow_caps -[Connect]: /docs/job-specification/connect -[`bridge`]: /docs/job-specification/network#bridge -[network block]: /docs/job-specification/network#bridge-mode -[`pids_limit`]: /docs/drivers/docker#pids_limit +[allow_caps]: /nomad/docs/drivers/docker#allow_caps +[Connect]: /nomad/docs/job-specification/connect +[`bridge`]: /nomad/docs/job-specification/network#bridge +[network block]: /nomad/docs/job-specification/network#bridge-mode +[`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 +[`--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)