Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix up attribute persistence docs #4182

Merged
merged 3 commits into from
Oct 6, 2023
Merged

Fix up attribute persistence docs #4182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8f23552
Fix up attribute persistence docs
williamtheaker Sep 14, 2023
c30be5a
Merge branch 'main' into wt.attribute_blocklist
johnmccrae Oct 4, 2023
ad3d627
Merge branch 'main' into wt.attribute_blocklist
IanMadd Oct 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 30 additions & 5 deletions content/attribute_persistence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
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 @@

## 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 @@
- 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 @@
{{< 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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,19 +26,19 @@
: 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"}

```ruby
knife[:authentication_protocol_version] = '1.3'
Expand All @@ -51,22 +51,22 @@
{{< /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 @@ -139,13 +139,13 @@
: The Chef Infra Client mode in which the Data Collector will be enabled. Possible values: `:solo`, `:client`, or `:both`. The `:solo` value is used for Chef Infra Client operating in Chef Solo Mode or Chef Solo Legacy Mode. Default value: `both`.

`data_collector.raise_on_failure`
: 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 @@
: 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
Open in desktop
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 @@ -51,12 +49,4 @@
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']]
```
Loading