octocatalog-diff 1.5.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 42b664636f99089e0838f35914f5cd0a89a60fe6
-  data.tar.gz: a6e77f9e6f1d50c6f9ea8219b580891574dbc31e
+SHA256:
+  metadata.gz: b99c2e5da4209a2779ec55c745b43a274c0983f00bc5ec41452bf19636818f9a
+  data.tar.gz: 1ebb9bc86ff2ab9dab9e6529a2f862ddc15447c859d7e1e2120ef8e177220c58
 SHA512:
-  metadata.gz: 223c4d52d3d7e424d28c42fb52e5185fe1dac46d9ea2dea9be7eebbace60b7d13ae376367abc29e58341f3a82f2c84cf640e540c389badf0c9e4811065b9e2a4
-  data.tar.gz: 0a821cf5bd95a83df9309de24141e21d3fadc21cb4d74b2344edcdb194c501bdb8c13bcd0db808d32ec07359fba5df6a559bdfc5c45077f7681e0d130d187b9c
+  metadata.gz: b9c7f405b7d219817088a1f29126335270245d5d1f8084a07e26b50b817adfb5b6019ed92edac55250ce611253cc418fee9a53a0cf9f065b73e3b89be1523809
+  data.tar.gz: 0054faec251c287be47947f73314fbcd30d5d3b4af240488fe97665247e5af7100561b908027a84dd9994853036a05330d82ab8da12ab2519437c5ec9a5101bc

data/.version

@@ -1 +1 @@
-1.5.1
+2.0.0

data/README.md

@@ -1,4 +1,4 @@
-# octocatalog-diff
+# octocatalog-diff ![CI](https://github.com/github/octocatalog-diff/workflows/CI/badge.svg)
 
 #### Compile Puppet catalogs from 2 branches, versions, etc., and compare them <img src="/doc/images/octocatolog-diff-logo.png" align="right" height=126 width=240>
 
@@ -23,7 +23,7 @@ There are some [limitations](doc/limitations.md) to a catalog-based approach, me
 `octocatalog-diff` is currently able to get catalogs by the following methods:
 - Compile catalog via the command line with a Puppet agent on your machine (as GitHub uses the tool internally)
 - Obtain catalog over the network from PuppetDB
-- Obtain catalog over the network using the API to query a Puppet Master / PuppetServer (Puppet 3.x and 4.x supported)
+- Obtain catalog over the network using the API to query a Puppet Master / PuppetServer (Puppet 3.x through 6.x supported)
 - Read catalog from a JSON file
 
 ## Example
@@ -81,6 +81,6 @@ If you have a problem or suggestion, please [open an issue](https://github.com/g
 
 It requires 3rd party ruby gems found [here](/vendor/cache). It also includes portions of other open source projects [here](/lib/octocatalog-diff/external/pson), [here](/spec/octocatalog-diff/fixtures/repos/default/modules/stdlib), [here](/spec/octocatalog-diff/support/httparty) and [here](/spec/octocatalog-diff/tests/external/pson). All 3rd party code and required gems are licensed either as MIT or Apache 2.0.
 
-## Authors
+## Authors / Owners
 
-`octocatalog-diff` was designed and authored by [Kevin Paulisse](https://github.com/kpaulisse) and is now maintained, reviewed, and tested by Kevin and the rest of the Site Reliability Engineering team at GitHub.
+`octocatalog-diff` was originally designed and authored by [Kevin Paulisse](https://github.com/kpaulisse). It is now maintained by the Site Reliability Engineering team at GitHub.

data/doc/CHANGELOG.md

@@ -8,6 +8,55 @@
 </tr>
 </thead><tbody>
 
+<tr valign=top>
+<td>2.0.0</td>
+<td>2020-01-12</td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/226">#226</a>: (Enhancement) Add Puppet 6 support</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/228">#228</a>: (Enhancement) Add Puppetserver catalog v4 API support</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/229">#229</a>: (Enhancement) Add support for PE package inventory facts</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/230">#230</a>: (Enhancement) Add set quality comparison to ignore filter</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>1.6.0</td>
+<td>2019-10-31</td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/216">#216</a>: (Enhancement) Hide sensitive parameters</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/204">#204</a>: (Enhancement) Add glob support for modulepath</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/206">#206</a>: (Bug Fix) Fix multi-node list with parallel mode</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/215">#215</a>: (Bug Fix) Add Support for Hashdiff 1.0.0</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>1.5.4</td>
+<td>2018-12-11</td>
+<td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/190">#190</a>: (Enhancement) Additional filtered out cases for compilation directory</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/195">#195</a>: (Enhancement) Parallel catalog-diff when multiple hostnames are passed</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/198">#198</a>: (Bug Fix) Portability fixes</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/200">#200</a>: (Bug Fix) Support name parameter when validating references</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>1.5.3</td>
+<td>2018-03-05</td>
+<td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/176">#176</a>: (Enhancement) Normalize file resource titles in reference checks</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>1.5.2</td>
+<td>2017-12-19</td>
+<td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/169">#169</a>: (Enhancement) Puppet Enterprise RBAC token to authenticate to PuppetDB</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/170">#170</a>: (Enhancement) Filter to treat an object the same as a single array containing that object</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/165">#165</a>: (Bug Fix) Override of fact file via CLI now has precedence over value set in configuration file</li>
+</td>
+</tr>
+
 <tr valign=top>
 <td>1.5.1</td>
 <td>2017-11-16</td>

data/doc/advanced-filter.md

@@ -11,6 +11,7 @@ Here is the list of available filters and an explanation of each:
 
 - [Absent File](/doc/advanced-filter.md#absent-file) - Ignore parameter changes of a file that is declared to be absent
 - [JSON](/doc/advanced-filter.md#json) - Ignore whitespace differences if JSON parses to the same object
+- [SingleItemArray](/doc/advanced-filter.md#SingleItemArray) - Ignore differences between object and array containing only that object
 - [YAML](/doc/advanced-filter.md#yaml) - Ignore whitespace/comment differences if YAML parses to the same object
 
 ## Absent File
@@ -84,6 +85,28 @@ If a file resource has extension `.json` and a difference in its content is obse
 
 This allows you to ignore changes in whitespace, comments, etc., that are not meaningful to a machine parsing the file. Note that changes to files may still trigger Puppet to restart services even though these changes are not displayed in the octocatalog-diff output.
 
+## Single Item Array
+
+#### Usage
+
+```
+--filters SingleItemArray
+```
+
+#### Description
+
+When enabling the future parser or upgrading between certain versions of Puppet, the internal structure of the catalog for certain parameters can change as shown in the following example:
+
+```
+Old: { "notify": "Service[foo]" }
+New: { "notify": [ "Service[foo]" ] }
+```
+
+This filter will suppress differences for the value of a parameter when:
+
+- The value in one catalog is an object, AND
+- The value in the other catalog is an array containing *only* that same object
+
 ## YAML
 
 #### Usage

data/doc/advanced-ignores.md

@@ -222,3 +222,13 @@ File[/tmp/foo] =>
 In this case, the very important line was removed from the catalog, and you want to know about this. Ignoring `File[/tmp/foo]::parameters::content` would have suppressed this (because all changes to that attribute are ignored). Also ignoring `File[/tmp/foo]::parameters::content=~>This is the line in the new catalog that I do not care about$` would have also suppressed this (because the regular expression was matched for *one* of the lines). However, the two examples with `=&>` in this section would *not* have suppressed this change, because it is no longer the case that *all* changes in the file matched the regular expression.
 
 :warning: All lines are stripped of leading and trailing spaces before the regular expression match is tried. This stripping of whitespace is done *only* for this comparison stage, and does not affect the display of any results.
+
+#### Ignoring attributes which have identical elements but in arbitrary order
+
+You can ignore attributes where both the values in both the old and new catalogs are arrays and the arrays
+contain identical elements but in arbitrary order. Basically, you can ignore a parameter where the values
+have set equality.
+
+To ignore any parameters named `foo` with values having set equality, you would use:
+
+      --ignore 'My::Custom::Resource[*]::parameters::foo=s>='

data/doc/advanced-puppet-master.md

@@ -8,7 +8,11 @@ Please note the following caveats:
 
 0. You will need to deploy your Puppet code to an environment on your Puppet Master prior to running `octocatalog-diff` for that environment. `octocatalog-diff` does not deploy code for you.
 
-0. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below.
+0. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below. If you are using Puppet Enterprise and use
+the Puppet Master v4 API you may also use a Puppet Enterprise RBAC token. The user owning the token will need the "Puppet Server Compile catalogs for remote nodes" permission.
+See the [PE RBAC Token Authorization](#pe-rbac-token-authorization) section below.
+
+0. If you are using the v2 or v3 PuppetServer APIs with Octocatalog-Diff to compile catalogs, then those catalogs and facts will be automatically stored in PuppetDB. However, when using the v4 PuppetServer API with Octocatalog-Diff, facts and catalogs are *not* automatically stored in PuppetDB - persistence is optional and may be enabled with the appropriate Octocatalog-Diff CLI flag. If your environment depends on the accuracy of exported resources or facts in PuppetDB, you may wish to upgrade and use the V4 API, to avoid unintentional side-effects.
 
 ## Command line options
 
@@ -18,11 +22,15 @@ The following command line options are used to retrieve a catalog from a Puppet
 | ------ | ----------- |
 | `-f ENVIRONMENT` | Environment name to use for the "from" catalog |
 | `-t ENVIRONMENT` | Environment name to use for the "to" catalog |
-| `--puppet-master HOSTNAME:PORT | The hostname and port number of the Puppet Master. (By default the port used by Puppet Master is 8140.) |
-| `--puppet-master-api-version VERSION | The API version used by the Puppet Master. API versions 2 and 3 are supported. Puppet Master 3.x uses API version 2, and the PuppetServer for Puppet 4.x uses API version 3. By default, API version 3 is used, so you only need to set this option if you are using Puppet Master 3.x. |
+| `--puppet-master HOSTNAME:PORT` | The hostname and port number of the Puppet Master. (By default the port used by Puppet Master is 8140.) |
+| `--puppet-master-api-version VERSION` | The API version used by the Puppet Master. API versions 2, 3,and 4 are supported. Puppet Master 3.x uses API version 2, and the PuppetServer for Puppet 4.x uses API version 3. PuppetServer 6.3.0 introduced the optional use of the v4 API but still fully supports the v3 API. By default, API version 3 is used, so you only need to set this option if you are using Puppet Master 3.x or wish to use the newer v4 API with PuppetServer 6. |
 | `--puppet-master-ssl-ca PATH` | Path to the CA certificate (public portion of certificate only) for your Puppet Master. This file will be on your Puppet Master and all Puppet agents. You can find it by running `puppet config print cacert` on any Puppet-managed host. |
-| `--puppet-master-ssl-client-cert PATH` | Path to the client certificate. Please see the section below on certificate authentication. |
-| `--puppet-master-ssl-client-key PATH` | Path to the client private key. Please see the section below on certificate authentication. |
+| `--puppet-master-ssl-client-cert PATH` | Path to the client certificate. Please see the section below on certificate authentication. This can be omitted if using PE RBAC token based auth with the v4 API. |
+| `--puppet-master-ssl-client-key PATH` | Path to the client private key. Please see the section below on certificate authentication. This can be omitted if using PE RBAC token based auth with the v4 API. |
+| `--puppet-master-token STRING` | A PE RBAC token used to authenticate a v4 catalog compile, in lieu of using certificate authentication. Please see the section below on token authentication. |
+| `--puppet-master-token-file PATH` | A path to a file containing a PE RBAC token used to authenticate a v4 catalog compile, in lieu of using certificate authentication. If this and `--puppet-master-token` are both specified, `--puppet-master-token` will be used instead. Please see the section below on token authentication. |
+| `--puppet-master-update-catalog` | When using the v4 API, instruct the PuppetServer to update the catalog generated from the compile in its PuppetDB instance. When using v2 and v3 APIs the catalog is always updated and this option is ignored. |
+| `--puppet-master-update-facts` | When using the v4 API, instruct the PuppetServer to update the facts used during the compile in its PuppetDB instance. When using v2 and v3 APIs the facts are always updated and this option is ignored. |
 
 If you wish to use a different Puppet Master to compile the "to" and "from" catalogs, you may prefix any of the `--puppet-master...` options with `to` or `from`. For example, perhaps you are testing an upgrade from Puppet 3.x to 4.x. You could use:
 
@@ -48,3 +56,13 @@ allow $1
 ```
 
 Please follow the instructions for the version of Puppet Master, PuppetServer, or Puppet Enterprise that you are using in order to generate and authorize the certificates.
+
+## PE RBAC Token authorization
+
+In newer versions of Puppet Enterprise you can authenticate using a valid PE RBAC token with appropriate permissions as long as it is authorized in the PuppetServer `auth.conf` file.
+
+By default this permission is enabled and controlled by the `puppet_enterprise::master::tk_authz::allow_rbac_catalog_compile` Hiera setting.
+
+The user the token was issued to must have the `puppetserver:compile_catalogs:*` permission.
+
+Note: A Puppet catalog may contain unencrypted secrets, even ones marked as `Sensitive`. In order to perform its job, Octocatalog-Diff needs access to the catalog. By granting a user the above RBAC permission you are granting them the ability to retrieve and view the complete catalog resulting from a compile, including any included secrets.

data/doc/configuration-puppetdb.md

@@ -36,6 +36,7 @@ The following settings can be used in a [configuration file](/doc/configuration.
 | `settings[:puppetdb_ssl_client_key]` | TEXT of the private key of the client SSL keypair used to authenticate to PuppetDB. Note: This variable is not set to a file path, which means you will likely want to use means you will likely want to use `File.read(...)` if you are configuring this to be read from a file. |
 | `settings[:puppetdb_ssl_client_pem]` | Concatenation of the text of `puppetdb_ssl_client_key` and `puppetdb_ssl_client_cert` as previously described. This is a good alternative if your certificate chain is complex and it's easier just to put everything in a single place. Note: this option is second in precedence; if `settings[:puppetdb_ssl_client_cert]` and `settings[:puppetdb_ssl_client_key]` are both set, this will be ignored. |
 | `settings[:puppetdb_ssl_client_password]` | Plain text string containing the password to unlock the private key. For keys generated by the Puppet Master CA, this is not required and should be left undefined. |
+| `settings[:puppetdb_token]` | TEXT containing the PE RBAC token used to authenticate to PuppetDB. Note: This variable is not set to a file path, which means you will likely want to use `File.read(...)` if you are configuring this to be read from a file. |
 
 ## Supplying necessary information via the command line
 
@@ -48,6 +49,8 @@ The following arguments can be used on the command line.
 | --puppetdb-ssl-client-cert FILENAME | Path to the certificate of the client SSL keypair. |
 | --puppetdb-ssl-client-key FILENAME | Path to the private key of the client SSL keypair. |
 | --puppetdb-ssl-client-password PASSWORD_STRING | Plain text string containing the password to unlock the private key. For keys generated by the Puppet Master CA, this is not required. |
+| --puppetdb-token STRING | String containing the PE RBAC token used to authenticate to PuppetDB. |
+| --puppetdb-token-file FILENAME | Path to the PE RBAC token file used to authenticate to PuppetDB. |
 
 ## Supplying necessary information via the environment
 
@@ -64,3 +67,11 @@ SSL support is enabled via any of the `--puppetdb-ssl-...` command line options
 - The CA certificate should be the public certificate of the CA that signed your PuppetDB server's certificate. This file can be found in `/etc/puppetlabs/puppetdb/ssl/ca.pem` on a PuppetDB server. Since this is a public certificate, it is safe (and recommended) to distribute this file to any clients that may connect to this PuppetDB instance.
 
 - The client keypair (key, certificate, and optionally password) should be generated individually for each client. You should NOT copy SSL keypairs from your PuppetDB server (or anywhere else) to your clients. If you are using `octocatalog-diff` on a system that is managed by Puppet, you may wish to use the same SSL credentials that the system uses to authenticate to Puppet. With recent versions of the Puppet agent, those certificates are found in `/etc/puppetlabs/puppet/ssl`.
+
+# Puppet Enterprise PuppetDB Package Inventory
+
+Puppet Enterprise customers have an optional package inventory feature which can be enabled. When this feature is enabled an inventory of all system packages
+is performed and uploaded as a fact which is then processed and stored independently of the normal Facter data in PuppetDB. Most environments won't need
+to replicate the package inventory facts for testing with Octocatalog-Diff but if you want the package inventory data (if present) to be included
+in the facts retrieved from PuppetDB by Octocatalog-Diff you should specify the `--puppetdb-package-inventory` flag. When enabled, this flag will instruct
+Octocatalog-Diff to retrieve any package data found for a node from PuppetDB and include it in the facts used during the Octocatalog-Diff compile.

data/doc/dev/api/v1/calls/catalog-diff.md

@@ -167,12 +167,16 @@ In this case, "owner", "notify", and "content" are nested under "parameters". In
 
   ```
   # Ignore all changes to the `owner` attribute of a file.
-  [ { type: Regexp.new('\AFile\z'), attr: Regexp.new("\Aparameters\fowner\z" } ]
+  [ { type: Regexp.new('\AFile\z'), attr: Regexp.new("\\Aparameters\fowner\\z" } ]
 
   # Ignore changes to `owner` or `group` for a file or an exec.
-  [ { type: Regexp.new('\A(File|Exec)\z'), attr: Regexp.new("\Aparameters\f(owner|group)\z" } ]
+  [ { type: Regexp.new('\A(File|Exec)\z'), attr: Regexp.new("\\Aparameters\f(owner|group)\\z" } ]
   ```
 
+When using regular expressions, `\f` (form feed character) is used to separate the structure (e.g. `parameters\fowner` refers to the `parameters` hash, `owner` key).
+
+:bulb: Note that `\A` in Ruby matches the beginning of the string and `\z` matches the end, but these are not actual characters. Therefore, if you are using `\A` or `\z` in double quotes (`"`), be sure to heed the examples above and write your expression like: `Regexp.new("\\Aparameters\fowner\\z")`.
+
 #### `:validate_references` (Array<String>, Optional)
 
 Invoke the [catalog validation](/doc/advanced-catalog-validation.md) feature to ensure resources targeted by `before`, `notify`, `require`, and/or `subscribe` exist in the catalog. If this parameter is not defined, no reference validation occurs.

data/doc/dev/api/v1/objects/diff.md

@@ -94,9 +94,9 @@ Returns the value of the resource from the new catalog.
     }
   }
 
-  # Demonstrates structure and old_value
+  # Demonstrates structure and new_value
   diff.structure #=> ['parameters', 'content']
-  diff.old_value #=> 'This is the NEW FILE!!!!!'
+  diff.new_value #=> 'This is the NEW FILE!!!!!'
   ```
 
 #### `#old_file` (String)
@@ -107,7 +107,7 @@ Note that this is a pass-through of information provided in the Puppet catalog,
 
 Note also that if the diff represents addition of a resource, this will return `nil`, because the resource does not exist in the old catalog.
 
-#### `#old_file` (String)
+#### `#old_line` (String)
 
 Returns the line number within the Puppet manifest giving rise to the resource as it exists in the old catalog. (See `#old_file` for the filename of the Puppet manifest.)
 

data/doc/dev/releasing.md

@@ -9,7 +9,7 @@ The project maintainers are responsible for bumping the version number, regenera
 To test the new version of `octocatalog-diff` in the GitHub Puppet repository, check out `github/puppet` and:
 
 - Start a new branch based off master
-- Run `script/update-octocatalog-diff -r <ocd_branch_name>`
+- Run `script/update-octocatalog-diff <ocd_branch_name>`
 - Confirm and commit the result
 - Make sure all CI jobs pass
 - Run the `puppet-catalog-diff` CI job and make sure it passes and shows expected results

data/doc/limitations.md

@@ -2,23 +2,23 @@
 
 Testing of Puppet catalogs is faster than running the agent, but you need to be careful of the following limitations:
 
-0. Facts are not taken from a live agent run
+1. Facts are not taken from a live agent run
 
-  octocatalog-diff by default uses the facts reported from a node's more recent Puppet run. If you have made changes to custom facts, catalog testing will **NOT** be an adequate test of whether your custom facts worked. (You can still use octocatalog-diff to help predict changes to nodes based on changes to facts, by overriding facts on the command line.)
+    octocatalog-diff by default uses the facts reported from a node's more recent Puppet run. If you have made changes to custom facts, catalog testing will **NOT** be an adequate test of whether your custom facts worked. (You can still use octocatalog-diff to help predict changes to nodes based on changes to facts, by overriding facts on the command line.)
 
-0. Agents handle depenency ordering and implementation details
+1. Agents handle depenency ordering and implementation details
 
-  The catalog defines the state of the system, but it's up to the agent to determine how to bring the system to a point that matches the catalog. The agent is responsible for order of operations and actually making the change.
+    The catalog defines the state of the system, but it's up to the agent to determine how to bring the system to a point that matches the catalog. The agent is responsible for order of operations and actually making the change.
 
-  Two specific situations that catalog testing does **NOT** detect are:
+    Two specific situations that catalog testing does **NOT** detect are:
 
-  - Dependency loops (e.g., you have made A require B, B require C, and C require A).
+    - Dependency loops (e.g., you have made A require B, B require C, and C require A).
 
-  - Operations not supported by the provider. For example, assume that in your current Puppet manifests, you set the size of a file system to 100 GB. You change this in your new branch to 50 GB. octocatalog-diff will dutifully report this change to you. However, the agent will fail to make the change, because it is not possible to shrink a file system from 100 GB to 50 GB.
+    - Operations not supported by the provider. For example, assume that in your current Puppet manifests, you set the size of a file system to 100 GB. You change this in your new branch to 50 GB. octocatalog-diff will dutifully report this change to you. However, the agent will fail to make the change, because it is not possible to shrink a file system from 100 GB to 50 GB.
 
-0. Changes in underlying providers may not be noticed
+1. Changes in underlying providers may not be noticed
 
-  Consider that you are using a Puppet module that creates a file system. The current implementation of that module checks to see if *any* file system is present on the device, and creates a new file system there if no file system was present. You upgrade the module, and the new version checks to see if *the specified* file system is present on the device, and reformats the device with the specified file system (regardless of whether there was no file system or if there was an existing file system of a different type). There would be no catalog changes (hence octocatalog-diff would report nothing) because the catalog simply instructs the agent to create a file system of the specified type at the defined location. However, the actual implementation of those instructions has changed dramatically.
+    Consider that you are using a Puppet module that creates a file system. The current implementation of that module checks to see if *any* file system is present on the device, and creates a new file system there if no file system was present. You upgrade the module, and the new version checks to see if *the specified* file system is present on the device, and reformats the device with the specified file system (regardless of whether there was no file system or if there was an existing file system of a different type). There would be no catalog changes (hence octocatalog-diff would report nothing) because the catalog simply instructs the agent to create a file system of the specified type at the defined location. However, the actual implementation of those instructions has changed dramatically.
 
 In general catalog testing is great for:
 

data/doc/optionsref.md

@@ -9,7 +9,8 @@
 
 ```
 Usage: octocatalog-diff [command line options]
-    -n, --hostname HOSTNAME          Use PuppetDB facts from last run of hostname
+    -n HOSTNAME1[,HOSTNAME2[,...]],  Use PuppetDB facts from last run of a hostname or a comma separated list of multiple hostnames
+        --hostname
         --basedir DIRNAME            Use an alternate base directory (git checkout of puppet repository)
     -f, --from FROM_BRANCH           Branch you are coming from
     -t, --to TO_BRANCH               Branch you are going to
@@ -36,6 +37,8 @@ Usage: octocatalog-diff [command line options]
         --fact-file STRING           Override fact globally
         --to-fact-file STRING        Override fact for the to branch
         --from-fact-file STRING      Override fact for the from branch
+        --[no-]puppetdb-package-inventory
+                                     Include Puppet Enterprise package inventory data, if found
         --save-catalog STRING        Save intermediate catalogs into files globally
         --to-save-catalog STRING     Save intermediate catalogs into files for the to branch
         --from-save-catalog STRING   Save intermediate catalogs into files for the from branch
@@ -86,7 +89,20 @@ Usage: octocatalog-diff [command line options]
         --puppet-binary STRING       Full path to puppet binary globally
         --to-puppet-binary STRING    Full path to puppet binary for the to branch
         --from-puppet-binary STRING  Full path to puppet binary for the from branch
+        --puppet-master-token-file STRING
+                                     File containing PE RBAC token to authenticate to the Puppetserver API v4 globally
+        --to-puppet-master-token-file STRING
+                                     File containing PE RBAC token to authenticate to the Puppetserver API v4 for the to branch
+        --from-puppet-master-token-file STRING
+                                     File containing PE RBAC token to authenticate to the Puppetserver API v4 for the from branch
         --facts-terminus STRING      Facts terminus: one of yaml, facter
+        --puppet-master-token STRING PE RBAC token to authenticate to the Puppetserver API v4 globally
+        --to-puppet-master-token STRING
+                                     PE RBAC token to authenticate to the Puppetserver API v4 for the to branch
+        --from-puppet-master-token STRING
+                                     PE RBAC token to authenticate to the Puppetserver API v4 for the from branch
+        --puppetdb-token TOKEN       Token to access the PuppetDB API
+        --puppetdb-token-file PATH   Path containing token for PuppetDB API, relative or absolute
         --puppetdb-url URL           PuppetDB base URL
         --puppetdb-ssl-ca FILENAME   CA certificate that signed the PuppetDB certificate
         --puppetdb-ssl-client-cert FILENAME
@@ -108,11 +124,23 @@ Usage: octocatalog-diff [command line options]
         --to-puppet-master STRING    Hostname or Hostname:PortNumber for Puppet Master for the to branch
         --from-puppet-master STRING  Hostname or Hostname:PortNumber for Puppet Master for the from branch
         --puppet-master-api-version STRING
-                                     Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x) globally
+                                     Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) globally
         --to-puppet-master-api-version STRING
-                                     Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x) for the to branch
+                                     Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) for the to branch
         --from-puppet-master-api-version STRING
-                                     Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x) for the from branch
+                                     Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) for the from branch
+        --[no-]puppet-master-update-catalog
+                                     Update catalog in PuppetDB when using Puppetmaster API version 4 globally
+        --[no-]to-puppet-master-update-catalog
+                                     Update catalog in PuppetDB when using Puppetmaster API version 4 for the to branch
+        --[no-]from-puppet-master-update-catalog
+                                     Update catalog in PuppetDB when using Puppetmaster API version 4 for the from branch
+        --[no-]puppet-master-update-facts
+                                     Update facts in PuppetDB when using Puppetmaster API version 4 globally
+        --[no-]to-puppet-master-update-facts
+                                     Update facts in PuppetDB when using Puppetmaster API version 4 for the to branch
+        --[no-]from-puppet-master-update-facts
+                                     Update facts in PuppetDB when using Puppetmaster API version 4 for the from branch
         --puppet-master-ssl-ca STRING
                                      Full path to CA certificate that signed the Puppet Master certificate globally
         --to-puppet-master-ssl-ca STRING
@@ -716,7 +744,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
       <pre><code>--from-puppet-master-api-version STRING</code></pre>
     </td>
     <td valign=top>
-      Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x) for the from branch
+      Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) for the from branch
     </td>
     <td valign=top>
       Specify the API version to use for the Puppet Master. This makes it possible to authenticate to a
@@ -778,6 +806,32 @@ This timeout is specified in seconds. (<a href="../lib/octocatalog-diff/cli/opti
     </td>
   </tr>
 
+  <tr>
+    <td valign=top>
+      <pre><code>--from-puppet-master-token STRING</code></pre>
+    </td>
+    <td valign=top>
+      PE RBAC token to authenticate to the Puppetserver API v4 for the from branch
+    </td>
+    <td valign=top>
+      Specify a PE RBAC token used to authenticate to Puppetserver for v4
+catalog API calls. (<a href="../lib/octocatalog-diff/cli/options/puppet_master_token.rb">puppet_master_token.rb</a>)
+    </td>
+  </tr>
+
+  <tr>
+    <td valign=top>
+      <pre><code>--from-puppet-master-token-file STRING</code></pre>
+    </td>
+    <td valign=top>
+      File containing PE RBAC token to authenticate to the Puppetserver API v4 for the from branch
+    </td>
+    <td valign=top>
+      Specify a path to a file containing a PE RBAC token used to authenticate to the
+Puppetserver for a v4 catalog API call. (<a href="../lib/octocatalog-diff/cli/options/puppet_master_token_file.rb">puppet_master_token_file.rb</a>)
+    </td>
+  </tr>
+
   <tr>
     <td valign=top>
       <pre><code>--from-puppetdb
@@ -854,14 +908,17 @@ Puppet control repo template, the value of this should be 'hieradata', which is
 
   <tr>
     <td valign=top>
-      <pre><code>-n HOSTNAME
---hostname HOSTNAME</code></pre>
+      <pre><code>-n HOSTNAME1[,HOSTNAME2[,...]]
+--hostname HOSTNAME1[,HOSTNAME2[,...]]</code></pre>
     </td>
     <td valign=top>
-      Use PuppetDB facts from last run of hostname
+      Use PuppetDB facts from last run of a hostname or a comma separated list of multiple hostnames
     </td>
     <td valign=top>
-      Set hostname, which is used to look up facts in PuppetDB, and in the header of diff display. (<a href="../lib/octocatalog-diff/cli/options/hostname.rb">hostname.rb</a>)
+      Set hostname, which is used to look up facts in PuppetDB, and in the header of diff display.
+This option can recieve a single hostname, or a comma separated list of
+multiple hostnames, which are split into an Array. Multiple hostnames do not
+work with the `catalog-only` or `bootstrap-then-exit` options. (<a href="../lib/octocatalog-diff/cli/options/hostname.rb">hostname.rb</a>)
     </td>
   </tr>
 
@@ -1233,7 +1290,7 @@ to work correctly. (<a href="../lib/octocatalog-diff/cli/options/preserve_enviro
       <pre><code>--puppet-master-api-version STRING</code></pre>
     </td>
     <td valign=top>
-      Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x) globally
+      Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) globally
     </td>
     <td valign=top>
       Specify the API version to use for the Puppet Master. This makes it possible to authenticate to a
@@ -1295,6 +1352,32 @@ This timeout is specified in seconds. (<a href="../lib/octocatalog-diff/cli/opti
     </td>
   </tr>
 
+  <tr>
+    <td valign=top>
+      <pre><code>--puppet-master-token STRING</code></pre>
+    </td>
+    <td valign=top>
+      PE RBAC token to authenticate to the Puppetserver API v4 globally
+    </td>
+    <td valign=top>
+      Specify a PE RBAC token used to authenticate to Puppetserver for v4
+catalog API calls. (<a href="../lib/octocatalog-diff/cli/options/puppet_master_token.rb">puppet_master_token.rb</a>)
+    </td>
+  </tr>
+
+  <tr>
+    <td valign=top>
+      <pre><code>--puppet-master-token-file STRING</code></pre>
+    </td>
+    <td valign=top>
+      File containing PE RBAC token to authenticate to the Puppetserver API v4 globally
+    </td>
+    <td valign=top>
+      Specify a path to a file containing a PE RBAC token used to authenticate to the
+Puppetserver for a v4 catalog API call. (<a href="../lib/octocatalog-diff/cli/options/puppet_master_token_file.rb">puppet_master_token_file.rb</a>)
+    </td>
+  </tr>
+
   <tr>
     <td valign=top>
       <pre><code>--puppetdb-api-version N</code></pre>
@@ -1308,6 +1391,23 @@ the default. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_api_version.
     </td>
   </tr>
 
+  <tr>
+    <td valign=top>
+      <pre><code>--puppetdb-package-inventory
+--no-puppetdb-package-inventory </code></pre>
+    </td>
+    <td valign=top>
+      Include Puppet Enterprise package inventory data, if found
+    </td>
+    <td valign=top>
+      When pulling facts from PuppetDB in a Puppet Enterprise environment, also include
+the Puppet Enterprise Package Inventory data in the fact results, if available.
+Generally you should not need to specify this, but including the package inventory
+data will produce a more accurate set of input facts for environments using
+package inventory. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_package_inventory.rb">puppetdb_package_inventory.rb</a>)
+    </td>
+  </tr>
+
   <tr>
     <td valign=top>
       <pre><code>--puppetdb-ssl-ca FILENAME</code></pre>
@@ -1374,6 +1474,36 @@ the text of the password won't appear in the process list. (<a href="../lib/octo
     </td>
   </tr>
 
+  <tr>
+    <td valign=top>
+      <pre><code>--puppetdb-token TOKEN</code></pre>
+    </td>
+    <td valign=top>
+      Token to access the PuppetDB API
+    </td>
+    <td valign=top>
+      Specify the PE RBAC token to access the PuppetDB API. Refer to
+https://puppet.com/docs/pe/latest/rbac/rbac_token_auth_intro.html#generate-a-token-using-puppet-access
+for details on generating and obtaining a token. Use this option to specify the text
+of the token. (Use --puppetdb-token-file to read the content of the token from a file.) (<a href="../lib/octocatalog-diff/cli/options/puppetdb_token.rb">puppetdb_token.rb</a>)
+    </td>
+  </tr>
+
+  <tr>
+    <td valign=top>
+      <pre><code>--puppetdb-token-file PATH</code></pre>
+    </td>
+    <td valign=top>
+      Path containing token for PuppetDB API, relative or absolute
+    </td>
+    <td valign=top>
+      Specify the PE RBAC token to access the PuppetDB API. Refer to
+https://puppet.com/docs/pe/latest/rbac/rbac_token_auth_intro.html#generate-a-token-using-puppet-access
+for details on generating and obtaining a token. Use this option to specify the text
+in a file, to read the content of the token from the file. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_token_file.rb">puppetdb_token_file.rb</a>)
+    </td>
+  </tr>
+
   <tr>
     <td valign=top>
       <pre><code>--puppetdb-url URL</code></pre>
@@ -1651,7 +1781,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
       <pre><code>--to-puppet-master-api-version STRING</code></pre>
     </td>
     <td valign=top>
-      Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x) for the to branch
+      Puppet Master API version (2 for Puppet 3.x, 3 for Puppet 4.x, 4 for Puppet Server >= 6.3.0) for the to branch
     </td>
     <td valign=top>
       Specify the API version to use for the Puppet Master. This makes it possible to authenticate to a
@@ -1713,6 +1843,32 @@ This timeout is specified in seconds. (<a href="../lib/octocatalog-diff/cli/opti
     </td>
   </tr>
 
+  <tr>
+    <td valign=top>
+      <pre><code>--to-puppet-master-token STRING</code></pre>
+    </td>
+    <td valign=top>
+      PE RBAC token to authenticate to the Puppetserver API v4 for the to branch
+    </td>
+    <td valign=top>
+      Specify a PE RBAC token used to authenticate to Puppetserver for v4
+catalog API calls. (<a href="../lib/octocatalog-diff/cli/options/puppet_master_token.rb">puppet_master_token.rb</a>)
+    </td>
+  </tr>
+
+  <tr>
+    <td valign=top>
+      <pre><code>--to-puppet-master-token-file STRING</code></pre>
+    </td>
+    <td valign=top>
+      File containing PE RBAC token to authenticate to the Puppetserver API v4 for the to branch
+    </td>
+    <td valign=top>
+      Specify a path to a file containing a PE RBAC token used to authenticate to the
+Puppetserver for a v4 catalog API call. (<a href="../lib/octocatalog-diff/cli/options/puppet_master_token_file.rb">puppet_master_token_file.rb</a>)
+    </td>
+  </tr>
+
   <tr>
     <td valign=top>
       <pre><code>--to-save-catalog STRING</code></pre>