From 6ca038f518e5643c7a0e44eea21f1ef102fcadc7 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Mon, 12 Oct 2020 09:09:01 -0400 Subject: [PATCH 1/2] docs: inclusive language configuration changes --- CHANGELOG.md | 3 +- website/pages/docs/configuration/client.mdx | 40 +++++++++---------- website/pages/docs/drivers/docker.mdx | 14 +++---- .../docs/integrations/vault-integration.mdx | 8 ++-- website/pages/docs/internals/security.mdx | 2 +- website/pages/docs/job-specification/task.mdx | 4 +- .../pages/docs/upgrade/upgrade-specific.mdx | 16 ++++++++ 7 files changed, 52 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b2273b064c1..692c4d994a6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,8 @@ IMPROVEMENTS: * client: Use ec2 CPU perf data from AWS API [[GH-7830](https://github.com/hashicorp/nomad/issues/7830)] * client: Added support for Azure fingerprinting. [[GH-8979](https://github.com/hashicorp/nomad/issues/8979)] * client: Added support for fingerprinting the client node's Consul segment. [[GH-7214](https://github.com/hashicorp/nomad/issues/7214)] - * client: Updated consul-template to v0.25.0 - config function_blacklist deprecated and replaced with function_denylist [[GH-8988](https://github.com/hashicorp/nomad/pull/8988)] + * client: Updated consul-template to v0.25.0 - config `function_blacklist` deprecated and replaced with `function_denylist` [[GH-8988](https://github.com/hashicorp/nomad/pull/8988)] + * config: Deprecated terms `blacklist` and `whitelist` from configuration. [GH-9019] * consul: Support Consul namespace (Consul Enterprise) in client configuration. [[GH-8849](https://github.com/hashicorp/nomad/pull/8849)] * csi: Relaxed validation requirements when checking volume capabilities with controller plugins, to accommodate existing plugin behaviors. [[GH-9049](https://github.com/hashicorp/nomad/issues/9049)] * driver/docker: Upgrade pause container and detect architecture [[GH-8957](https://github.com/hashicorp/nomad/pull/8957)] diff --git a/website/pages/docs/configuration/client.mdx b/website/pages/docs/configuration/client.mdx index 309cf6ff400e..1b713c81631f 100644 --- a/website/pages/docs/configuration/client.mdx +++ b/website/pages/docs/configuration/client.mdx @@ -199,32 +199,32 @@ The following is not an exhaustive list of options for only the Nomad client. To find the options supported by each individual Nomad driver, please see the [drivers documentation](/docs/drivers). -- `"driver.whitelist"` `(string: "")` - Specifies a comma-separated list of - whitelisted drivers . If specified, drivers not in the whitelist will be - disabled. If the whitelist is empty, all drivers are fingerprinted and enabled +- `"driver.allowlist"` `(string: "")` - Specifies a comma-separated list of + allowlisted drivers . If specified, drivers not in the allowlist will be + disabled. If the allowlist is empty, all drivers are fingerprinted and enabled where applicable. ```hcl client { options = { - "driver.whitelist" = "docker,qemu" + "driver.allowlist" = "docker,qemu" } } ``` -- `"driver.blacklist"` `(string: "")` - Specifies a comma-separated list of - blacklisted drivers . If specified, drivers in the blacklist will be +- `"driver.denylist"` `(string: "")` - Specifies a comma-separated list of + denylisted drivers . If specified, drivers in the denylist will be disabled. ```hcl client { options = { - "driver.blacklist" = "docker,qemu" + "driver.denylist" = "docker,qemu" } } ``` -- `"env.blacklist"` `(string: see below)` - Specifies a comma-separated list of +- `"env.denylist"` `(string: see below)` - Specifies a comma-separated list of environment variable keys not to pass to these tasks. Nomad passes the host environment variables to `exec`, `raw_exec` and `java` tasks. If specified, the defaults are overridden. If a value is provided, **all** defaults are @@ -233,7 +233,7 @@ see the [drivers documentation](/docs/drivers). ```hcl client { options = { - "env.blacklist" = "MY_CUSTOM_ENVVAR" + "env.denylist" = "MY_CUSTOM_ENVVAR" } } ``` @@ -250,15 +250,15 @@ see the [drivers documentation](/docs/drivers). GOOGLE_APPLICATION_CREDENTIALS ``` -- `"user.blacklist"` `(string: see below)` - Specifies a comma-separated - blacklist of usernames for which a task is not allowed to run. This only +- `"user.denylist"` `(string: see below)` - Specifies a comma-separated + denylist of usernames for which a task is not allowed to run. This only applies if the driver is included in `"user.checked_drivers"`. If a value is provided, **all** defaults are overridden (they are not merged). ```hcl client { options = { - "user.blacklist" = "root,ubuntu" + "user.denylist" = "root,ubuntu" } } ``` @@ -271,7 +271,7 @@ see the [drivers documentation](/docs/drivers). ``` - `"user.checked_drivers"` `(string: see below)` - Specifies a comma-separated - list of drivers for which to enforce the `"user.blacklist"`. For drivers using + list of drivers for which to enforce the `"user.denylist"`. For drivers using containers, this enforcement is usually unnecessary. If a value is provided, **all** defaults are overridden (they are not merged). @@ -291,27 +291,27 @@ see the [drivers documentation](/docs/drivers). java ``` -- `"fingerprint.whitelist"` `(string: "")` - Specifies a comma-separated list of - whitelisted fingerprinters. If specified, any fingerprinters not in the - whitelist will be disabled. If the whitelist is empty, all fingerprinters are +- `"fingerprint.allowlist"` `(string: "")` - Specifies a comma-separated list of + allowlisted fingerprinters. If specified, any fingerprinters not in the + allowlist will be disabled. If the allowlist is empty, all fingerprinters are used. ```hcl client { options = { - "fingerprint.whitelist" = "network" + "fingerprint.allowlist" = "network" } } ``` -- `"fingerprint.blacklist"` `(string: "")` - Specifies a comma-separated list of - blacklisted fingerprinters. If specified, any fingerprinters in the blacklist +- `"fingerprint.denylist"` `(string: "")` - Specifies a comma-separated list of + denylisted fingerprinters. If specified, any fingerprinters in the denylist will be disabled. ```hcl client { options = { - "fingerprint.blacklist" = "network" + "fingerprint.denylist" = "network" } } ``` diff --git a/website/pages/docs/drivers/docker.mdx b/website/pages/docs/drivers/docker.mdx index 498fee888cb8..5986bdb518b0 100644 --- a/website/pages/docs/drivers/docker.mdx +++ b/website/pages/docs/drivers/docker.mdx @@ -377,8 +377,8 @@ The `docker` driver supports the following configuration in the job spec. Only - `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 whitelist. - The whitelist can be customized using the [`allow_caps`](#plugin_caps) plugin option key in the client node's configuration. + Effective capabilities (computed from `cap_add` and `cap_drop`) have to match the configured allowlist. + The allowlist can be customized using the [`allow_caps`](#plugin_caps) plugin option key in the client node's configuration. For example: ```hcl @@ -391,8 +391,8 @@ The `docker` driver supports the following configuration in the job spec. Only - `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 whitelist. - The whitelist can be customized using the [`allow_caps`](#plugin_caps) plugin option key in the client node's configuration. + Effective capabilities (computed from `cap_add` and `cap_drop`) have to match the configured allowlist. + The allowlist can be customized using the [`allow_caps`](#plugin_caps) plugin option key in the client node's configuration. For example: ```hcl @@ -750,7 +750,7 @@ plugin "docker" { `CHOWN,DAC_OVERRIDE,FSETID,FOWNER,MKNOD,NET_RAW,SETGID,SETUID,SETFCAP,SETPCAP, NET_BIND_SERVICE,SYS_CHROOT,KILL,AUDIT_WRITE` which is the list of capabilities allowed by docker by default, as defined here. Allows the operator to control which capabilities can be obtained by tasks using cap_add - and cap_drop options. Supports the value "ALL" as a shortcut for whitelisting + and cap_drop options. Supports the value "ALL" as a shortcut for allowlisting all capabilities. - `allow_runtimes` - defaults to `["runc", "nvidia"]` - A list of the allowed @@ -896,13 +896,13 @@ options](/docs/configuration/client#options): access to the host's devices. Note that you must set a similar setting on the Docker daemon for this to work. -- `docker.caps.whitelist`: A list of allowed Linux capabilities. Defaults to +- `docker.caps.allowlist`: A list of allowed Linux capabilities. Defaults to `"CHOWN,DAC_OVERRIDE,FSETID,FOWNER,MKNOD,NET_RAW,SETGID,SETUID,SETFCAP, SETPCAP,NET_BIND_SERVICE,SYS_CHROOT,KILL,AUDIT_WRITE"`, which is the list of capabilities allowed by docker by default, as [defined here](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). Allows the operator to control which capabilities can be obtained by tasks using `cap_add` and `cap_drop` options. Supports the value `"ALL"` as a - shortcut for whitelisting all capabilities. + shortcut for allowlisting all capabilities. - `docker.cleanup.container`: Defaults to `true`. This option can be used to disable Nomad from removing a container when the task exits. Under a name diff --git a/website/pages/docs/integrations/vault-integration.mdx b/website/pages/docs/integrations/vault-integration.mdx index 96ab4e67f5e7..6f549c925967 100644 --- a/website/pages/docs/integrations/vault-integration.mdx +++ b/website/pages/docs/integrations/vault-integration.mdx @@ -50,7 +50,7 @@ Vault's [Token Authentication Backend][auth] supports a concept called "roles". Token roles allow policies to be grouped together and token creation to be delegated to a trusted service such as Nomad. By creating a token role, the set of policies that tasks managed by Nomad can access may be limited compared to -giving Nomad a root token. Token roles allow both white-list and blacklist +giving Nomad a root token. Token roles allow both allowlist and denylist management of policies accessible to the role. To configure Nomad and Vault to create tokens against a role, the following must @@ -129,13 +129,13 @@ $ vault policy write nomad-server nomad-server-policy.hcl A Vault token role must be created for use by Nomad. The token role can be used to manage what Vault policies are accessible by jobs submitted to Nomad. The -policies can be managed as a whitelist by using `allowed_policies` in the token -role definition or as a blacklist by using `disallowed_policies`. +policies can be managed as a allowlist by using `allowed_policies` in the token +role definition or as a denylist by using `disallowed_policies`. If using `allowed_policies`, tasks may only request Vault policies that are in the list. If `disallowed_policies` is used, task may request any policy that is not in the `disallowed_policies` list. There are trade-offs to both approaches -but generally it is easier to use the blacklist approach and add policies that +but generally it is easier to use the denylist approach and add policies that you would not like tasks to have access to into the `disallowed_policies` list. An example token role definition is given below: diff --git a/website/pages/docs/internals/security.mdx b/website/pages/docs/internals/security.mdx index 891aefc5f91a..8e66e8343eb7 100644 --- a/website/pages/docs/internals/security.mdx +++ b/website/pages/docs/internals/security.mdx @@ -191,7 +191,7 @@ environment. kernel for other containers and the Nomad client agent itself. Docker driver allows [customizing runtimes](/docs/drivers/docker#runtime). -- **[Disable Unused Drivers](/docs/configuration/client#driver-blacklist)** - +- **[Disable Unused Drivers](/docs/configuration/client#driver-denylist)** - Each driver provides different degrees of isolation, and bugs may allow unintended privilege escalation. If a task driver is not needed, you can disable it to reduce risk. diff --git a/website/pages/docs/job-specification/task.mdx b/website/pages/docs/job-specification/task.mdx index fac774b00928..892b245fd1b6 100644 --- a/website/pages/docs/job-specification/task.mdx +++ b/website/pages/docs/job-specification/task.mdx @@ -96,7 +96,7 @@ job "docs" { [Docker][] and [rkt][] images specify their own default users. This can only be set on Linux platforms, and clients can restrict [which drivers][user_drivers] are allowed to run tasks as - [certain users][user_blacklist]. + [certain users][user_denylist]. - `template` ([Template][]: nil) - Specifies the set of templates to render for the task. Templates can be used to inject both static and @@ -213,6 +213,6 @@ task "server" { [service_discovery]: /docs/integrations/consul-integration#service-discovery 'Nomad Service Discovery' [template]: /docs/job-specification/template 'Nomad template Job Specification' [user_drivers]: /docs/configuration/client#user-checked_drivers -[user_blacklist]: /docs/configuration/client#user-blacklist +[user_denylist]: /docs/configuration/client#user-denylist [max_kill]: /docs/configuration/client#max_kill_timeout [kill_signal]: /docs/job-specification/task#kill_signal diff --git a/website/pages/docs/upgrade/upgrade-specific.mdx b/website/pages/docs/upgrade/upgrade-specific.mdx index 5679743d7509..08dbf08654ec 100644 --- a/website/pages/docs/upgrade/upgrade-specific.mdx +++ b/website/pages/docs/upgrade/upgrade-specific.mdx @@ -44,6 +44,22 @@ the AWS fingerprinter no longer sets the `cpu.modelname` attribute. As before, `cpu_total_compute` can be used to override the discovered CPU resources available to the Nomad client. +### Inclusive language + +Starting with Nomad v0.13.0, the terms `blacklist` and `whitelist` have been +deprecated from client configuration and driver configuration. The existing +configuration values are permitted but will be removed in a future version of +Nomad. The specific configuration values replaced are: + +* Client `driver.blacklist` is replaced with `driver.denylist`. +* Client `driver.whitelist` is replaced with `driver.allowlist`. +* Client `env.blacklist` is replaced with `env.denylist`. +* Client `fingerprint.blacklist` is replaced with `fingerprint.denylist`. +* Client `fingerprint.whitelist` is replaced with `fingerprint.allowlist`. +* Client `user.blacklist` is replaced with `user.denylist`. +* Client `template.function_blacklist` is replaced with `template.function_denylist`. +* Docker driver `docker.caps.whitelist` is replaced with `docker.caps.allowlist`. + ## Nomad 0.12.0 ### `mbits` and Task Network Resource deprecation From d6d85b3a4a93946545cec54d3706b6352c8747fa Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Mon, 12 Oct 2020 09:17:50 -0400 Subject: [PATCH 2/2] fixes from code review --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 692c4d994a6f..b2dbb56e5a24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ IMPROVEMENTS: * client: Added support for Azure fingerprinting. [[GH-8979](https://github.com/hashicorp/nomad/issues/8979)] * client: Added support for fingerprinting the client node's Consul segment. [[GH-7214](https://github.com/hashicorp/nomad/issues/7214)] * client: Updated consul-template to v0.25.0 - config `function_blacklist` deprecated and replaced with `function_denylist` [[GH-8988](https://github.com/hashicorp/nomad/pull/8988)] - * config: Deprecated terms `blacklist` and `whitelist` from configuration. [GH-9019] + * config: Deprecated terms `blacklist` and `whitelist` from configuration and replaced them with `denylist` and `allowlist`. [[GH-9019](https://github.com/hashicorp/nomad/issues/9019)] * consul: Support Consul namespace (Consul Enterprise) in client configuration. [[GH-8849](https://github.com/hashicorp/nomad/pull/8849)] * csi: Relaxed validation requirements when checking volume capabilities with controller plugins, to accommodate existing plugin behaviors. [[GH-9049](https://github.com/hashicorp/nomad/issues/9049)] * driver/docker: Upgrade pause container and detect architecture [[GH-8957](https://github.com/hashicorp/nomad/pull/8957)]