Fix up attribute persistence docs (#4182)

Signed-off-by: William Theaker <[email protected]>
Co-authored-by: John McCrae <[email protected]>
Co-authored-by: Ian Maddaus <[email protected]>

content/attribute_persistence.md

@@ -11,7 +11,7 @@ gh_repo = "chef-web-docs"
     parent = "chef_infra/cookbook_reference/attributes"
 +++
 
-All attributes except for normal attributes are reset at the beginning
+All attributes, except for normal attributes, are reset at the beginning
 of a Chef Infra Client run. Attributes set using `chef-client -j` with a
 JSON file have normal precedence and are persisted between Chef Infra
 Client runs. Chef Infra Client rebuilds these attributes using automatic
@@ -25,13 +25,21 @@ Client run.
 
 ## Limiting Attribute Persistence
 
-Some organizations find it helpful to control attribute data stored to the Chef Infra Server to limit the disk and CPU resources used when processing unused attributes. For example, your organization may find the data from the Ohai `Package` plugin useful when writing cookbooks, but you do not see the need in saving ~100k of package information for each Chef Infra Client run. By limiting the data that is saved to the Chef Infra Server, it will still be available on the node within cookbooks, but will not be saved to the Chef Infra Server where it is available in searches.
+Some organizations find it helpful to control attribute data stored by the Chef Infra Server, whether to limit the disk and CPU resources used when processing unused attributes or to keep secrets like API keys from being submitted to the server. For example, your organization may find the data from the Ohai `Package` plugin useful when writing cookbooks, but do not see the need in saving ~100kB of package information for each Chef Infra Client run. Attribute data will still be available on the node within cookbooks, but any information you limit will not be saved to the Chef Infra Server for use in searches.
+
+Allowing or blocking the saving of specific keys can be set in the [client.rb](/config_rb_client/) file. Each setting is an array of keys specifying each attribute to be filtered out or allowed. Use a "/" to separate subkeys, for example `network/interfaces`
+
+For attributes containing slashes (`/`) within the attribute value, such as the `filesystem` attribute, use a nested array. For example:
+
+```ruby
+blocked_automatic_attributes [['filesystem', '/dev/diskos2']]
+```
 
 {{< note >}}
 
-In Chef Infra Client 16.3 the node Blacklist and Whitelist features were renamed to Blocklist and Allowlist. For backwards compatibility the old configuration values will continue to work, but this document will describe the Blocklist and Allowlist names. See each section below for the appropriate legacy configuration values if you are running legacy clients in your organization.
+In Chef Infra Client 16.3, the node Blacklist and Whitelist features were renamed to Blocklist and Allowlist. For backwards compatibility the old configuration values will continue to work, but this document will describe the Blocklist and Allowlist names. See each section below for the appropriate legacy configuration values if you are running legacy clients in your organization.
 
-Legacy config mapping:
+Legacy attribute config mapping:
 
 - automatic_attribute_blacklist -> blocked_automatic_attributes
 - default_attribute_blacklist -> blocked_default_attributes
@@ -41,7 +49,6 @@ Legacy config mapping:
 - default_attribute_whitelist -> allowed_default_attributes
 - normal_attribute_whitelist -> allowed_normal_attributes
 - override_attribute_whitelist -> allowed_override_attributes
-- enforce_path_sanity -> enforce_default_paths
 
 {{< /note >}}
 
@@ -62,3 +69,21 @@ Legacy config mapping:
 {{< readfile file="content/reusable/md/node_attribute_allowlist_warning.md" >}}
 
 {{< /warning >}}
+
+Attributes are allowlisted by attribute type, with each attribute type being allowlisted independently. Each attribute type---`automatic`, `default`, `normal`, and `override`---may define allowlists by using the following settings in the client.rb file:
+
+`allowed_automatic_attributes`
+
+: An array that allows saving specific `automatic` attributes. For example: `['network/interfaces/eth0']`. Default value: `nil`, all attributes are saved. If the array is empty, no attributes are saved.
+
+`allowed_default_attributes`
+
+: An array that allows saving specific `default` attributes. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the array is empty, no attributes are saved.
+
+`allowed_normal_attributes`
+
+: An array that allows saving specific `normal` attributes. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the array is empty, no attributes are saved.
+
+`allowed_override_attributes`
+
+: An array that allows specific `override` attributes, preventing blocklisted attributes from being saved. For example: `['map - autohome/size']`. Default value: `nil`, all attributes are saved. If the array is empty, no attributes are saved.

content/config_rb_client.md

@@ -26,16 +26,16 @@ This configuration file has the following settings:
 : A 3rd-party formatter. (See [nyan-cat](https://github.com/andreacampi/nyan-cat-chef-formatter) for an example of a 3rd-party formatter.) Each formatter requires its own entry.
 
 `allowed_automatic_attributes`
-: A hash that allows `default` attributes, preventing non-allowed attributes from being saved.
+: An array that allows `automatic` attributes, preventing non-allowed attributes from being saved.
 
 `allowed_default_attributes`
-: A hash that allows `default` attributes, preventing non-allowed attributes from being saved.
+: An array that allows `default` attributes, preventing non-allowed attributes from being saved.
 
 `allowed_normal_attributes`
-: A hash that allows `normal` attributes, preventing non-allowed attributes from being saved.
+: An array that allows `normal` attributes, preventing non-allowed attributes from being saved.
 
 `allowed_override_attributes`
-: A hash that allows `override` attributes, preventing non-allowed attributes from being saved.
+: An array that allows `override` attributes, preventing non-allowed attributes from being saved.
 
 `authentication_protocol_version`
 : Sets the authentication protocol that is used to communicate with Chef Infra Server. For example, specify protocol version 1.3 to enable support for SHA-256 algorithms:
@@ -51,22 +51,22 @@ This configuration file has the following settings:
     {{< /note >}}
 
 `automatic_attribute_blacklist`
-: A hash that blocks `automatic` attributes, preventing blocked attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_automatic_attributes`.
+: An array that blocks `automatic` attributes, preventing blocked attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_automatic_attributes`.
 
 `automatic_attribute_whitelist`
-: A hash that allows `automatic` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_automatic_attributes`.
+: An array that allows `automatic` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_automatic_attributes`.
 
 `blocked_automatic_attributes`
-: A hash that blocks `automatic` attributes, preventing blocked attributes from being saved.
+: An array that blocks `automatic` attributes, preventing blocked attributes from being saved.
 
 `blocked_default_attributes`
-: A hash that blocks `default` attributes, preventing block attributes from being saved.
+: An array that blocks `default` attributes, preventing block attributes from being saved.
 
 `blocked_normal_attributes`
-: A hash that allows `automatic` attributes, preventing non-allowed attributes from being saved.
+: An array allows `normal` attributes, preventing non-allowed attributes from being saved.
 
 `blocked_override_attributes`
-: A hash that blocks `override` attributes, preventing blocked attributes from being saved.
+: An array blocks `override` attributes, preventing blocked attributes from being saved.
 
 `cache_path`
 : The home directory for the user that runs Chef Infra Client as a non-root user.
@@ -142,10 +142,10 @@ This configuration file has the following settings:
 : When enabled, Chef Infra Client raises an error if it cannot successfully POST to the data collector server. Default value: `false`.
 
 `default_attribute_blacklist`
-: A hash that blocks `default` attributes, preventing block attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_default_attributes`.
+: normal that blocks `default` attributes, preventing block attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_default_attributes`.
 
 `default_attribute_whitelist`
-: A hash that allows `default` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_default_attributes`.
+: normal that allows `default` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_default_attributes`.
 
 `diff_disabled`
 : Cause Chef Infra Client to create a diff when changes are made to a file. Default value: `false`.
@@ -310,19 +310,16 @@ This configuration file has the following settings:
 : The location in which nodes are stored during a Chef Infra Client run in local mode. Default value: `/var/chef/node`.
 
 `normal_attribute_blacklist`
-: A hash that blocks `normal` attributes, preventing blocked attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_normal_attributes`.
+: An array that blocks `normal` attributes, preventing blocked attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_normal_attributes`.
 
 `override_attribute_blacklist`
-: A hash that blocks `override` attributes, preventing blocked attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_override_attributes`.
+: An array that blocks `override` attributes, preventing blocked attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `blocked_override_attributes`.
 
 `normal_attribute_whitelist`
-: A hash that allows `normal` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_normal_attributes`.
-
-`override_normal_attributes`
-: A hash that allows `override` attributes, preventing non-allowed attributes from being saved.
+: An array that allows `normal` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_normal_attributes`.
 
 `override_attribute_whitelist`
-: A hash that allows `override` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_override_attributes`.
+: An array that allows `override` attributes, preventing non-allowed attributes from being saved. **Deprecated. EOL Chef Infra Client 18 (April 2022)**: Use `allowed_override_attributes`.
 
 `pid_file`
 : The location in which a process identification number (pid) is saved. An executable, when started as a daemon, writes the pid to the specified file. Default value: `/tmp/name-of-executable.pid`.

content/reusable/md/node_attribute_blocklist.md

@@ -1,22 +1,20 @@
-Attributes that should not be saved by a node may be blocklisted in the [client.rb](/config_rb_client/) file. The blocklist is a Hash of keys that specify each attribute to be filtered out.
-
 Attributes are blocklisted by attribute type, with each attribute type being blocklisted independently. Each attribute type---`automatic`, `default`, `normal`, and `override`---may define blocklists by using the following settings in the client.rb file:
 
 `blocked_automatic_attributes`
 
-: A hash that blocklists `automatic` attributes, preventing blocklisted attributes from being saved. For example: `['network/interfaces/eth0']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
+: An array that blocklists `automatic` attributes, preventing blocklisted attributes from being saved. For example: `['packages']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
 
 `blocked_default_attributes`
 
-: A hash that blocklists `default` attributes, preventing blocklisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
+: An array that blocklists `default` attributes, preventing blocklisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
 
 `blocked_normal_attributes`
 
-: A hash that blocklists `normal` attributes, preventing blocklisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
+: An array that blocklists `normal` attributes, preventing blocklisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
 
 `blocked_override_attributes`
 
-: A hash that blocklists `override` attributes, preventing blocklisted attributes from being saved. For example: `['map - autohome/size']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
+: An array that blocklists `override` attributes, preventing blocklisted attributes from being saved. For example: `['map - autohome/size']`. Default value: `nil`, all attributes are saved. If the array is empty, all attributes are saved.
 
 <!-- markdownlint-disable-file MD002 -->
 
@@ -52,11 +50,3 @@ blocked_automatic_attributes ['filesystem']
 ```
 
 When a blocklist is defined, any attribute of that type that is not specified in that attribute blocklist **will** be saved. So based on the previous blocklist for automatic attributes, the `filesystem` and `map - autohome` attributes will not be saved, but the `network` attributes will.
-
-For attributes that contain slashes (`/`) within the attribute value, such as the `filesystem` attribute `'/dev/diskos2'`, use an array. For
-
-example:
-
-```ruby
-blocked_automatic_attributes [['filesystem', '/dev/diskos2']]
-```