policyfile attribute additions (#4093)

* policyfile attribute additions

Signed-off-by: Mike Butler <michael.butler@progress.com>

* Signed-off-by: Mike Butler michael.butler@progress.com

* Signed-off-by: Mike Butler <michael.butler@progress.com>

* One more tweak for the customer regarding hoisting
Signed-off-by: Mike Butler <michael.butler@progress.com>

* Docs edits

Signed-off-by: Ian Maddaus <ian.maddaus@progress.com>

* Corrections after rebase

Signed-off-by: Ian Maddaus <ian.maddaus@progress.com>

---------

Signed-off-by: Mike Butler <michael.butler@progress.com>
Signed-off-by: Ian Maddaus <ian.maddaus@progress.com>
Co-authored-by: Ian Maddaus <ian.maddaus@progress.com>

content/policy.md

@@ -19,52 +19,32 @@ product = ["client", "server"]
 
 {{< readfile file="content/reusable/md/cookbooks_version.md" >}}
 
-{{< note >}}
-
 For more information about cookbook versioning, see [About Cookbook
 Versioning](/cookbook_versioning/)
 
-{{< /note >}}
-
 ## Data Bags (Secrets)
 
 {{< readfile file="content/reusable/md/data_bag.md" >}}
 
-{{< note >}}
-
 For more information about data bags, see [About Data
 Bags](/data_bags/)
 
-{{< /note >}}
-
 ## Environments
 
 {{< readfile file="content/reusable/md/environment.md" >}}
 
-{{< note >}}
-
 For more information about environments, see [About
 Environments](/environments/)
 
-{{< /note >}}
-
 ## Roles
 
 {{< readfile file="content/reusable/md/role.md" >}}
 
-{{< note >}}
-
 For more information about roles, see [About Roles](/roles/)
 
-{{< /note >}}
-
 ## Policyfile
 
 {{< readfile file="content/reusable/md/policyfile_summary.md" >}}
 
-{{< note >}}
-
 For more information about Policyfile, see [About
 Policyfile](/policyfile/)
-
-{{< /note >}}

content/reusable/md/chef_solo_environments.md

@@ -9,7 +9,7 @@ environment_path '/var/chef-solo/environments'
 
 Environment data looks like the following in JSON:
 
-```javascript
+```json
 {
   "name": "dev",
   "default_attributes": {

content/reusable/md/data_bag_item.md

@@ -4,7 +4,7 @@ by specifying the name of the data bag to which the item belongs and
 then the filename of the data bag item. The only structural requirement
 of a data bag item is that it must have an `id`:
 
-```javascript
+```json
 {
   /* This is a supported comment style */
   // This style is also supported

content/reusable/md/node_attribute_allowlist.md

@@ -39,7 +39,7 @@ The recommended practice is to use `allowed_automatic_attributes` to allow speci
 
 For example, automatic attribute data similar to:
 
-```javascript
+```json
 {
   "filesystem" => {
     "/dev/disk0s2" => {

content/reusable/md/node_attribute_blocklist.md

@@ -39,7 +39,7 @@ The recommended practice is to use `blocked_automatic_attributes` to block attri
 
 For example, automatic attribute data similar to:
 
-```javascript
+```json
 {
   "filesystem" => {
     "/dev/disk0s2" => {

content/reusable/md/node_ctl_attribute.md

@@ -3,7 +3,7 @@ treated as a `normal` attribute. Setting attributes at other precedence
 levels is not possible. For example, attempting to update `override`
 attributes using the `-j` option:
 
-```javascript
+```json
 {
   "name": "dev-99",
   "description": "Install some stuff",
@@ -18,7 +18,7 @@ attributes using the `-j` option:
 
 will result in a node object similar to:
 
-```javascript
+```json
 {
   "name": "maybe-dev-99",
   "normal": {

content/reusable/md/node_ctl_run_list.md

@@ -1,7 +1,7 @@
 Use this option to define a `run_list` object. For example, a JSON file
 similar to:
 
-```javascript
+```json
 "run_list": [
   "recipe[base]",
   "recipe[foo]",

content/reusable/md/node_run_list_format.md

@@ -2,19 +2,19 @@ A run-list must be in one of the following formats: fully qualified,
 cookbook, or default. Both roles and recipes must be in quotes, for
 example:
 
-```javascript
+```json
 "role[NAME]"
 ```
 
 or
 
-```javascript
+```json
 "recipe[COOKBOOK::RECIPE]"
 ```
 
 Use a comma to separate roles and recipes when adding more than one item
 the run-list:
 
-```javascript
+```json
 "recipe[COOKBOOK::RECIPE],COOKBOOK::RECIPE,role[NAME]"
 ```

content/reusable/md/policy_summary.md

@@ -1,13 +1,13 @@
 Policy maps business and operational requirements, process, and workflow
-to settings and objects stored on the Chef Infra Server:
+to the following settings and objects stored on the Chef Infra Server:
 
-- Roles define server types, such as "web server" or "database server"
-- Environments define process, such as "dev", "staging", or
-    "production"
+- Roles define server types, such as "web server" or "database server".
+- Environments define process, such as "dev", "staging", or "production".
+- Attributes define environment-specific details about a node that are included in a Policyfile.
 - Certain types of data---passwords, user account data, and other
     sensitive items---can be placed in data bags, which are located in a
     secure sub-area on the Chef Infra Server that can only be accessed
     by nodes that authenticate to the Chef Infra Server with the correct
-    SSL certificates
+    SSL certificates.
 - The cookbooks (and cookbook versions) in which organization-specific
-    configuration policies are maintained
+    configuration policies are maintained.

content/reusable/md/policyfile_lock_json.md

@@ -3,8 +3,9 @@ necessary cookbooks and emits a `Policyfile.lock.json` file that
 describes:
 
 - The versions of cookbooks in use
-- A Hash of cookbook content
+- A hash of cookbook content
 - The source for all cookbooks
+- Attributes included with the Policyfile
 
 A `Policyfile.lock.json` file is associated with a specific policy
 group, which means it is associated with one (or more) nodes that use the same

content/reusable/md/policyfile_lock_json_example.md

@@ -1,6 +1,6 @@
 A `Policyfile.lock.json` file is similar to:
 
-```javascript
+```json
 {
   "revision_id": "288ed244f8db8bff3caf58147e840bbe079f76e0",
   "name": "jenkins",
@@ -31,4 +31,15 @@ A `Policyfile.lock.json` file is similar to:
       "artifactserver": "https://supermarket.chef.io/api/v1/cookbooks/java/versions/1.24.0/download",
       "version": "1.24.0"
     }
+  "default_attributes": {
+    "audit": {
+      "reporter": [
+        "chef-server-automate",
+        "cli"
+      ]
+    }
+  },
+  "override_attributes": {
+
+  },
 ```

content/reusable/md/policyfile_rb_example.md

@@ -7,4 +7,6 @@ default_source :supermarket, 'https://mysupermarket.example'
 cookbook 'policyfile_demo', path: 'cookbooks/policyfile_demo'
 cookbook 'jenkins', '~> 8.2'
 cookbook 'mysql', github: 'sous-chefs/mysql', branch: 'master'
+default['stage']['mysql']['install_s3'] = 'https://s3-eu-west-1.amazonaws.com/example/stage/file.rpm'
+default['prod']['mysql']['install_s3'] = 'https://s3-eu-west-1.amazonaws.com/example/prod/file.rpm'
 ```

content/reusable/md/policyfile_rb_settings.md

@@ -3,7 +3,8 @@ A `Policyfile.rb` file may contain the following settings:
 `name "name"`
 
 :   Required. The name of the policy. Use a name that reflects the
-    purpose of the machines against which the policy will run.
+    purpose of the machines against which the policy will run,
+    such as "application server", "chat server", "load balancer", and so on.
 
 `run_list "ITEM", "ITEM", ...`
 
@@ -13,30 +14,43 @@ A `Policyfile.rb` file may contain the following settings:
 `default_source :SOURCE_TYPE, *args`
 
 :   The location in which any cookbooks not specified by `cookbook` are
-    located. Possible values: `chef_repo`, `chef_server`, `:supermarket`,
-    and `:artifactory`. Use more than one `default_source` to specify more
-    than one location for cookbooks.
+    located.
 
-    `default_source :supermarket` pulls cookbooks from the public Chef
-    Supermarket.
+    Possible values for `:SOURCE_TYPE` are:
 
-    `default_source :supermarket, "https://mysupermarket.example"` pulls
-    cookbooks from a named private Chef Supermarket.
+    - `:artifactory`
+    - `:chef_repo`
+    - `:chef_server`
+    - `:supermarket`
 
-    `default_source :chef_server, "https://chef-server.example/organizations/example"`
-    pulls cookbooks from the Chef Infra Server.
+    `:artifactory`
+    : Pulls cookbooks from an Artifactory server. Requires either `artifactory_api_key` to be set in `config.rb` or
+      `ARTIFACTORY_API_KEY` to be set in your environment.
 
-    `default_source :chef_repo, "path/to/repo"` pulls cookbooks from a
-    monolithic cookbook repository. This may be a path to the top-level
-    of a cookbook repository or to the `/cookbooks` directory within
-    that repository.
+      For example, `default_source :artifactory, "https://artifactory.example/api/chef/my-supermarket"`.
 
-    `default_source :artifactory, "https://artifactory.example/api/chef/my-supermarket"`
-    pulls cookbooks from an Artifactory server. Requires either
-    `artifactory_api_key` to be set in `config.rb` or
-    `ARTIFACTORY_API_KEY` to be set in your environment.
+    `:chef_repo`
+    : Pulls cookbooks from a monolithic cookbook repository. This may be a path to the top-level
+      of a cookbook repository or to the `/cookbooks` directory within that repository.
 
-    Multiple cookbook sources may be specified. For example from the
+      For example, `default_source :chef_repo, "path/to/repo"`.
+
+    `:chef_server`
+    : Pulls cookbooks from the Chef Infra Server.
+
+      For example, `default_source :chef_server, "https://chef-server.example/organizations/example"`.
+
+    `:supermarket`
+
+    : Pulls cookbooks from the public Chef Supermarket or a private Chef Supermarket.
+
+      By default `:supermarket` pulls cookbooks from the public Chef
+      Supermarket. For example, `default_source :supermarket`.
+
+      Specify the Supermarket URL to pull cookbooks from a private Supermarket. For example,
+      `default_source :supermarket, "https://supermarket-name.example"`.
+
+    You can specify multiple cookbook sources. For example from the
     public Chef Supermarket and a monolithic repository:
 
     ```ruby
@@ -206,3 +220,54 @@ A `Policyfile.rb` file may contain the following settings:
     ```ruby
     include_policy 'NAME', policy_name: 'foo', policy_group: 'prod', server: 'http://chef-server.example'
     ```
+
+`ATTRIBUTE_TYPE['attribute'] = 'value'`
+
+:   Specify one or more attributes to be included with the policy.
+    This is similar to defining attributes using roles.
+
+    Possible values for `ATTRIBUTE_TYPE` are:
+
+    - `default`
+    - `override`
+
+    `default`
+    : A `default` attribute is automatically reset at the start of every Chef
+      Infra Client run and has the lowest attribute precedence.
+
+      For example:
+
+      ```ruby
+      default['attribute'] = 'value'
+      default['attribute']['level2'] = 'another_value'
+      ```
+
+    `override`
+    : An `override` attribute is automatically reset at the start of every
+      Chef Infra Client run and has a higher attribute precedence than
+      a `default` attribute.
+
+      ```ruby
+      override['attribute'] = 'value'
+      override['attribute']['level2'] = 'another_value'
+      ```
+
+    Attribute hoisting allows you to define attributes by policy group.
+
+    Use the following syntax to define policy group-specific attributes:
+
+    ```ruby
+    ATTRIBUTE_TYPE['POLICY_GROUP']['attribute'] = 'value'
+    ```
+
+    where:
+
+    - `ATTRIBUTE_TYPE` is either `default` or `override` as described above.
+    - `POLICY_GROUP` is a user-defined policy group, such as "dev", "test" "staging", or "production".
+
+    In the following example, the value of `default['attribute']` is set to either `dev_value` or `prod_value` depending on the policy group.
+
+    ```ruby
+    default['dev']['attribute'] = 'dev_value'
+    default['prod']['attribute'] = 'prod_value'
+    ```

content/reusable/md/policyfile_rb_syntax.md

@@ -6,4 +6,5 @@ name "name"
 run_list "ITEM", "ITEM", ...
 default_source :SOURCE_TYPE, *args
 cookbook "NAME" [, "VERSION_CONSTRAINT"] [, SOURCE_OPTIONS]
+ATTRIBUTE_TYPE['attribute'] = 'value'
 ```

content/reusable/md/search_key_nested.md

@@ -12,7 +12,7 @@ card made by the specified vendor.
 
 Consider the following snippet of JSON data:
 
-```javascript
+```json
 {"network":
   [
   //snipped...

content/reusable/md/search_pattern_fuzzy_summary.md

@@ -7,7 +7,7 @@ knife search client "name:boo~"
 where `boo~` defines the fuzzy search pattern. This will return
 something similar to:
 
-```javascript
+```json
 {
   "total": 1,
   "start": 0,

layouts/shortcodes/data_bag_item.md

@@ -4,7 +4,7 @@ by specifying the name of the data bag to which the item belongs and
 then the filename of the data bag item. The only structural requirement
 of a data bag item is that it must have an `id`:
 
-```javascript
+```json
 {
   /* This is a supported comment style */
   // This style is also supported

layouts/shortcodes/node_run_list_format.md

@@ -2,19 +2,19 @@ A run-list must be in one of the following formats: fully qualified,
 cookbook, or default. Both roles and recipes must be in quotes, for
 example:
 
-```javascript
+```json
 "role[NAME]"
 ```
 
 or
 
-```javascript
+```json
 "recipe[COOKBOOK::RECIPE]"
 ```
 
 Use a comma to separate roles and recipes when adding more than one item
 the run-list:
 
-```javascript
+```json
 "recipe[COOKBOOK::RECIPE],COOKBOOK::RECIPE,role[NAME]"
 ```

layouts/shortcodes/policyfile_lock_json.md

@@ -3,8 +3,9 @@ necessary cookbooks and emits a `Policyfile.lock.json` file that
 describes:
 
 - The versions of cookbooks in use
-- A Hash of cookbook content
+- A hash of cookbook content
 - The source for all cookbooks
+- Attributes included with the Policyfile
 
 A `Policyfile.lock.json` file is associated with a specific policy
 group, which means it is associated with one (or more) nodes that use the same