Skip to content

Commit

Permalink
Fix up attribute persistence docs
Browse files Browse the repository at this point in the history 
Signed-off-by: William Theaker <[email protected]>
  • Loading branch information
@williamtheaker
williamtheaker committed Sep 14, 2023
1 parent ee4b28a commit 8f23552
Show file tree
Hide file tree
Showing 3 changed files with 50 additions and 38 deletions.
35 changes: 30 additions & 5 deletions content/attribute_persistence.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Check failure on line 28 in content/attribute_persistence.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'don't' instead of 'do not'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'don't' instead of 'do not'.", "location": {"path": "content/attribute_persistence.md", "range": {"start": {"line": 28, "column": 362}}}, "severity": "ERROR"}

Check failure on line 28 in content/attribute_persistence.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'won't' instead of 'will not'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'won't' instead of 'will not'.", "location": {"path": "content/attribute_persistence.md", "range": {"start": {"line": 28, "column": 553}}}, "severity": "ERROR"}

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`

Check failure on line 30 in content/attribute_persistence.md

View workflow job for this annotation

GitHub Actions / cspell-action 

Unknown word (subkeys)

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
Expand All @@ -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 >}}

Expand All @@ -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.
35 changes: 16 additions & 19 deletions content/config_rb_client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Check failure on line 41 in content/config_rb_client.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'that's' instead of 'that is'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'that's' instead of 'that is'.", "location": {"path": "content/config_rb_client.md", "range": {"start": {"line": 41, "column": 36}}}, "severity": "ERROR"}
Expand All @@ -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.
Expand Down Expand Up @@ -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`.

Check failure on line 142 in content/config_rb_client.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'can't' instead of 'cannot'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'can't' instead of 'cannot'.", "location": {"path": "content/config_rb_client.md", "range": {"start": {"line": 142, "column": 57}}}, "severity": "ERROR"}

`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`.
Expand Down Expand Up @@ -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`.
Expand Down
18 changes: 4 additions & 14 deletions content/reusable/md/node_attribute_blocklist.md
View file
Original file line number Diff line number Diff line change
@@ -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 -->

Expand Down Expand Up @@ -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.

Check failure on line 52 in content/reusable/md/node_attribute_blocklist.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'that's' instead of 'that is'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'that's' instead of 'that is'.", "location": {"path": "content/reusable/md/node_attribute_blocklist.md", "range": {"start": {"line": 52, "column": 57}}}, "severity": "ERROR"}

Check failure on line 52 in content/reusable/md/node_attribute_blocklist.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[write-good.So] Don't start a sentence with 'So '.

Raw Output:
{"message": "[write-good.So] Don't start a sentence with 'So '.", "location": {"path": "content/reusable/md/node_attribute_blocklist.md", "range": {"start": {"line": 52, "column": 126}}}, "severity": "ERROR"}

Check failure on line 52 in content/reusable/md/node_attribute_blocklist.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'won't' instead of 'will not'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'won't' instead of 'will not'.", "location": {"path": "content/reusable/md/node_attribute_blocklist.md", "range": {"start": {"line": 52, "column": 236}}}, "severity": "ERROR"}

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']]
```

0 comments on commit 8f23552

Please sign in to comment.