octocatalog-diff 0.6.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a89d4a61710f5fd7a044241c3dd99d0d50ec2737
-  data.tar.gz: 362d9371778130cc5eda6978ce9563ac6a1d93e1
+  metadata.gz: 94e2cf0a922da25cff91452ca8e2a3631cc1d97c
+  data.tar.gz: 6fbf668920f43516ccae0cd58095187e9d78f8d9
 SHA512:
-  metadata.gz: 5fcf1c9e9373f21fc8c14cb3cca8163659e6b0be55a4c449e500d95f35172d29f546de3deba0028d2702e53310a77b9182a06dadace338ec15afa237ddb1fc90
-  data.tar.gz: cad1f341cf55e43336f1e1945035491f949f9d81d6cfa13359e5b9c8ae50b6caccf3e7c8c7822e86e05d09fdddff45c7135d2949b5cffe085ff9301cb10ae785
+  metadata.gz: 616ac7fe5586015dd0afa7511074db94358ae09150e183392ab68aba81d1ade9750594ec3d4d7a62ad333b088ef758aa094bfa4392457f800a41dbf3d1a78b51
+  data.tar.gz: afaa669b726b5f983be6fefd0ded47e14fc649c25e459a2d286a7b28d378908c1081309f788ce9d45e7674b590295b4562a93ac7b3c5d27538c30cd10431f1f5

data/.version

@@ -1 +1 @@
-0.6.1
+1.0.0

data/README.md

@@ -8,7 +8,9 @@ At GitHub, we manage thousands of nodes with a Puppet code base containing 500,0
 
 `octocatalog-diff` is written in Ruby and is distributed as a gem. It runs on Mac OS and Unix/Linux platforms.
 
-It is under active development at this time. We suspect that with the initial release, some people who try it out could be using configurations of Puppet that we haven't experienced within our environment. We are eager to identify and fix as many of these as we can to expand the compatibility of this tool as much as possible.
+We consider the 1.x release of `octocatalog-diff` to be stable and production-quality. We continue to maintain and enhance `octocatalog-diff` to meet GitHub's internal needs and to incorporate suggestions from the community. Please consult the [change log](/doc/CHANGELOG.md) for details.
+
+If you've been using version 0.6.1 or earlier, please read about [What's new in octocatalog-diff 1.0](/doc/versions/v1.md) for a summary of new capabilities and breaking changes.
 
 ## How?
 
@@ -58,6 +60,7 @@ The example above reflects the changes in the Puppet catalog from switching an u
 - [Similar tools](/doc/similar.md)
 - [Contributing](/.github/CONTRIBUTING.md)
 - [Developer documentation](/doc/dev)
+- [API documentation](/doc/dev/api.md)
 
 ## What's in a name?
 
@@ -79,4 +82,4 @@ It requires 3rd party ruby gems found [here](/vendor/cache). It also includes po
 
 ## Authors
 
-`octocatalog-diff` was designed and authored by [Kevin Paulisse](https://github.com/kpaulisse) and is now maintained, reviewed, and tested by the Site Reliability Engineering team at GitHub.
+`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.

data/bin/octocatalog-diff

@@ -20,56 +20,16 @@ end
 
 config_test = ARGV.include?('--config-test')
 
-paths = [
-  ENV['OCTOCATALOG_DIFF_CONFIG_FILE'],
-  File.join(Dir.pwd, '.octocatalog-diff.cfg.rb'),
-  File.join(ENV['HOME'], '.octocatalog-diff.cfg.rb'),
-  '/opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb',
-  '/usr/local/etc/octocatalog-diff.cfg.rb',
-  '/etc/octocatalog-diff.cfg.rb'
-]
-
-cfgfile = nil
-
-paths.each do |path|
-  next if path.nil?
-  puts "Looking for config in: #{path}" if config_test
-  next unless File.file?(path)
-  begin
-    cfgfile = path
-    puts "Loading config: #{path}" if config_test
-    require path
-  rescue => exc
-    STDERR.puts "#{exc.class} error with #{path}: #{exc.message}\n#{exc.backtrace}"
-    exit 1
-  end
-  break
-end
-
-options = {}
-
-if cfgfile
-  begin
-    options = OctocatalogDiff::Config.config
-  rescue => exc
-    STDERR.puts "#{exc.class} error with #{cfgfile}: #{exc.message}\n#{exc.backtrace}"
-    exit 1
-  end
-  unless options.is_a?(Hash)
-    STDERR.puts "Configuration must be Hash not #{options.class}!"
-    exit 1
-  end
-  if config_test
-    options.each do |key, val|
-      puts ":#{key} => (#{val.class}) #{val.inspect}"
-    end
-    exit 0
-  end
-elsif config_test
-  STDERR.puts 'No configuration files found'
-  exit 1
+logger = Logger.new(STDERR)
+logger.level = Logger::INFO
+logger.level = Logger::DEBUG if config_test
+
+options = OctocatalogDiff::API::V1.config(logger: logger, test: config_test)
+if config_test
+  logger.info 'Exiting now because --config-test was specified'
+  exit(0)
 end
 
 argv = ARGV.dup
-exit_code = OctocatalogDiff::CatalogDiff::Cli.cli(argv, Logger.new(STDERR), options)
+exit_code = OctocatalogDiff::Cli.cli(argv, Logger.new(STDERR), options)
 exit(exit_code)

data/doc/CHANGELOG.md

@@ -8,6 +8,20 @@
 </tr>
 </thead><tbody>
 <tr valign=top>
+<td>1.0.0</td>
+<td>2017-02-06</td>
+<td>
+This is the first release of the 1.0 series. For more information please see <a href="./versions/v1.md">What's new in octocatalog-diff 1.0</a>.
+<br>
+<br>
+The most significant change in version 1.0 is the addition of the <a href="./dev/api.md">V1 API</a>, which permits developers to build catalogs (<code>--catalog-only</code>) and compare/diff catalogs using octocatalog-diff. Under the hood, we've rearranged the code to support these APIs, which should improve the reliability and allow faster development cycles.
+
+<h4>Breaking Changes</h4>
+
+The format of the output from <code>--output-format json</code> has changed. In version 0.x of the software, each difference was represented by an array. In version 1.x, each difference is represented by a hash with meaningful English keys. We have added an option <code>--output-format legacy_json</code> for anyone who may depend on the old format.
+</td>
+</tr>
+<tr valign=top>
 <td>0.6.1</td>
 <td>2017-01-07</td>
 <td>

data/doc/advanced-filter.md

@@ -9,7 +9,65 @@ Please note that there are other options to ignore specified diffs, including:
 
 Here is the list of available filters and an explanation of each:
 
-- [YAML](#YAML) - Ignore whitespace/comment differences if YAML parses to the same object
+- [Absent File](/doc/advanced-filter.md#absent-file) - Ignore parameter changes of a file that is declared to be absent
+- [YAML](/doc/advanced-filter.md#yaml) - Ignore whitespace/comment differences if YAML parses to the same object
+
+## Absent File
+
+#### Usage
+
+```
+--filters AbsentFile
+```
+
+#### Description
+
+When the `AbsentFile` filter is enabled, if any file is `ensure => absent` in the *new* catalog, then changes to any other parameters will be suppressed.
+
+Consider that a file resource is declared as follows in two catalogs:
+
+```
+# Old catalog
+file { '/etc/some-file':
+  ensure  => present,
+  owner   => 'root',
+  group   => 'nobody',
+  content => 'my content here',
+}
+
+# New catalog
+file { '/etc/some-file':
+  ensure => absent,
+  owner  => 'bob',
+}
+```
+
+Since the practical effect of the new catalog will be to remove the file, it doesn't matter that the owner of the (non-existent) file has changed from 'root' to 'bob', or that the content and group have changed from a string to undefined. Consider the default output without the filter:
+
+```
+  File[/etc/some-file] =>
+   parameters =>
+     ensure =>
+      - present
+      + absent
+     group =>
+      - nobody
+     owner =>
+      - root
+      + bob
+     content =>
+      - my content here
+```
+
+Wouldn't it be nice if the meaningless information didn't appear, and all you saw was the transition you actually care about, from present to absent? With `--filters AbsentFile` it does just this:
+
+```
+  File[/etc/some-file] =>
+   parameters =>
+     ensure =>
+      - present
+      + absent
+```
 
 ## YAML
 

data/doc/advanced-override-enc.md

@@ -0,0 +1,54 @@
+# Overriding ENC parameters
+
+One powerful feature of `octocatalog-diff` allows you to override ENC parameters when compiling the catalogs, to predict the effect of an ENC parameter change on the catalog. This is useful to simulate a change in agent node configuration without actually setting up an agent to do so.
+
+## Usage
+
+To override an ENC parameter in both catalogs:
+
+```
+--enc-override parameters::some_class::some_param=value
+```
+
+To override an ENC parameter in the "to" catalog:
+
+```
+--to-enc-override parameters::some_class::some_param=value
+```
+
+To override an ENC parameter in the "from" catalog:
+
+```
+--from-enc-override parameters::some_class::some_param=value
+```
+
+You may use as many of these arguments as you wish to adjust as many ENC parameters as you wish.
+
+## Limitations
+
+As presently implemented, this only works on ENCs that supply their results as YAML.
+
+Is your ENC doing something different? Please [let us know](https://github.com/github/octocatalog-diff/issues/new) so we can enhance octocatalog-diff to handle it!
+
+## Examples
+
+Simulate a change to a top-level parameter named "role" only in the "to" catalog:
+
+```
+octocatalog-diff -n some-node.example.com -f master -t master \
+  --to-enc-override parameters::role=some_new_role
+```
+
+Simulate a change in a class parameter between the catalogs:
+
+```
+octocatalog-diff -n some-node.example.com -f master -t master \
+  --from-enc-override parameters::my_class::my_value=value_in_old \
+  --to-enc-override parameters::my_class::my_value=value_in_new
+```
+
+Note that each of the examples specified the from branch and to branch to be `master`. There is no requirement that you do this, but you can generally obtain the most accurate test results by changing only one variable at a time.
+
+## Advanced usage
+
+The format for declaring overrides with data types is the same as [overriding facts](/doc/advanced-override-facts.md#advanced-usage).

data/doc/advanced-pe-enc.md

@@ -39,7 +39,7 @@ Please see [Authentication token](https://docs.puppet.com/pe/latest/nc_forming_r
 
 The referenced document contains links to generate a token with the `puppet-access` command.
 
-Note that if you wish to hard-code an authentication token in your [configuration file](/doc/configuration.md), the internal variable key is `:pe_enc_token` and the content is a string containing the entire token. (The `--pe-enc-token-file` option simply reads the provided file and stores the content in the `:pe_enc_token` key. See [source](/lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_token_file.rb).)
+Note that if you wish to hard-code an authentication token in your [configuration file](/doc/configuration.md), the internal variable key is `:pe_enc_token` and the content is a string containing the entire token. (The `--pe-enc-token-file` option simply reads the provided file and stores the content in the `:pe_enc_token` key. See [source](/lib/octocatalog-diff/cli/options/pe_enc_token_file.rb).)
 
 ### SSL client keypair
 

data/doc/advanced.md

@@ -18,11 +18,12 @@ See also:
 - [Building catalogs instead of diffing catalogs](/doc/advanced-catalog-only.md)
 - [Enabling storeconfigs for exported resources in PuppetDB](/doc/advanced-storeconfigs.md)
 - [Fetching catalogs from Puppet Master / PuppetServer](/doc/advanced-puppet-master.md)
+- [Overriding ENC parameters](/doc/advanced-override-enc.md)
 - [Overriding facts](/doc/advanced-override-facts.md)
 - [Puppet Enterprise node classification service](/doc/advanced-pe-enc.md)
 - [Using `octocatalog-diff` without git](/doc/advanced-using-without-git.md)
 - [Catalog validation](/doc/advanced-catalog-validation.md)
-- [Environment setup](/doc/advanced-environment.md)
+- [Environment setup](/doc/advanced-environments.md)
 
 ### Controlling output
 

data/doc/dev/api.md

@@ -0,0 +1,5 @@
+# octocatalog-diff API documentation
+
+The octocatalog-diff API allows developers to construct and work with certain octocatalog-diff internals in their own projects.
+
+The current API version is [API v1](/doc/dev/api/v1.md), which is available as of octocatalog-diff version 1.0.

data/doc/dev/api/v1.md

@@ -0,0 +1,41 @@
+# octocatalog-diff v1 API documentation
+
+## API calls
+
+#### catalog
+
+`catalog` allows you to build a catalog using the octocatalog-diff compiler or to obtain a catalog from a Puppet server.
+
+[Read more about the `catalog` call](/doc/dev/api/v1/calls/catalog.md)
+
+#### catalog-diff
+
+`catalog-diff` allows you compare two catalogs and obtain the differences between them. Catalogs can be built if necessary.
+
+[Read more about the `catalog-diff` call](/doc/dev/api/v1/calls/catalog-diff.md)
+
+#### config
+
+`config` allows you read and parse an [octocatalog-diff configuration file](/doc/configuration.md).
+
+[Read more about the `config` call](/doc/dev/api/v1/calls/config.md)
+
+## Objects
+
+#### OctocatalogDiff::API::V1::Catalog
+
+The `OctocatalogDiff::API::V1::Catalog` object represents a compiled catalog and supports several methods to get information about the catalog.
+
+[Read more about the `OctocatalogDiff::API::V1::Catalog` object](/doc/dev/api/v1/objects/catalog.md)
+
+#### OctocatalogDiff::API::V1::Diff
+
+The `OctocatalogDiff::API::V1::Diff` object represents a difference between two catalogs and supports several methods to get information about the difference.
+
+[Read more about the `OctocatalogDiff::API::V1::Diff` object](/doc/dev/api/v1/objects/diff.md)
+
+#### OctocatalogDiff::API::V1::Override
+
+The `OctocatalogDiff::API::V1::Override` object represents a user-supplied fact or ENC parameter that will be used when compiling a catalog.
+
+[Read more about the `OctocatalogDiff::API::V1::Override` object](/doc/dev/api/v1/objects/override.md)

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

@@ -0,0 +1,209 @@
+# octocatalog-diff v1 API documentation: catalog-diff
+
+## Overview
+
+`catalog-diff` allows you compare two catalogs and obtain the differences between them. Catalogs can be built if necessary.
+
+This is analogous to using the default arguments with the octocatalog-diff command-line script.
+
+```
+catalog_diff_result = OctocatalogDiff::API::V1.catalog_diff(<Hash>)
+#=> {
+  diffs: Array<OctocatalogDiff::API::V1::Diff>,
+  from: OctocatalogDiff::API::V1::Catalog,
+  to: OctocatalogDiff::API::V1::Catalog
+}
+```
+
+Return values:
+- [`OctocatalogDiff::API::V1::Diff`](/doc/dev/api/v1/objects/diff.md)
+- [`OctocatalogDiff::API::V1::Catalog`](/doc/dev/api/v1/objects/catalog.md)
+
+For an example, see [catalog-diff-local-files.rb](/examples/api/v1/catalog-diff-local-files.rb).
+
+## Parameters
+
+The `catalog_diff` method takes one argument, which is a Hash containing parameters.
+
+The list of parameters here is not exhaustive. The `.catalog_diff` method accepts most parameters described in [Configuration](/doc/configuration.md), [Advanced options](/doc/advanced.md), and [Command line options reference](/doc/optionsref.md).
+
+It is also possible to use the parameters from [OctocatalogDiff::API::V1.config](/doc/dev/api/v1/calls/config.md) for the catalog-diff calculation. Simply combine the hash returned by `.config` with any additional keys, and pass the merged hash to the `.catalog_diff` method.
+
+### Global parameters
+
+#### `:logger` (Logger, Optional)
+
+Debugging and informational messages will be logged to this object as the catalogs are built and differences are computed.
+
+If no Logger object is passed, these messages will be silently discarded.
+
+#### `:node` (String, Required)
+
+The node name whose catalogs are to be compiled and differences obtained obtained. This should be the fully qualified domain name that matches the node's name as seen in Puppet.
+
+### Computed catalog parameters
+
+#### `:basedir` (String, Optional)
+
+Directory that contains a git repository with the Puppet code. Use in conjunction with `:to_branch` and `:from_branch` to specify the branch names that should be checked out.
+
+If your Puppet code is not in a git repository, or you already have the branches checked out via some other process, use `:bootstrapped_to_dir` and `:bootstrapped_from_dir` instead.
+
+#### `:bootstrap_script` (String, Optional)
+
+Path to a script to run after checking out the selected branch of Puppet code from the git repository. See [Bootstrapping your Puppet checkout](/doc/advanced-bootstrap.md) for details.
+
+#### `:bootstrapped_to_dir` / `:bootstrapped_from_dir` (String, Optional)
+
+Directories that is already prepared ("bootstrapped") and can have Puppet run against its contents to compile the catalog. `:bootstrapped_to_dir` is used for the "to" catalog, while `:bootstrapped_from_dir` is used for the "from" catalog.
+
+Often this means that you have done the following to this directory:
+
+- Checked out the necessary branch of Puppet code from your version control system
+- Installed any third party modules (e.g. with librarian-puppet or r10k)
+
+You may mix and match `:bootstrapped_XXX_dir` and `:basedir` + `:XXX_branch`. For example, you may specify `:bootstrapped_from_dir`, `:basedir`, and `:to_branch`, which will compile the "from" catalog in the bootstrapped "from" directory you specified, and the "to" catalog from the "to_branch" branch of the git repository found in the "basedir".
+
+#### `:enc` / `:to_enc` / `:from_enc` (String, Optional)
+
+File path to your External Node Classifier.
+
+See [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md) for details on using octocatalog-diff with an External Node Classifier.
+
+In most cases, you will use the `:enc` option to set the ENC for both the "to" and "from" catalogs. In the case that you are comparing two different ENCs, you may use `:to_enc` and/or `:from_enc` as needed.
+
+#### `:fact_file` / `:to_fact_file` / `:from_fact_file` (String, Optional)
+
+Path to the file that contains the facts for the node whose catalog you are going to compile.
+
+Generally, must either specify the fact file, or [configure octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md) to retrieve node facts.
+
+In most cases, you will use the `:fact_file` option to set the fact file for both the "to" and "from" catalogs. In the case that you are comparing the results from two different sets of facts, you may use `:to_fact_file` and/or `:from_fact_file` as needed.
+
+#### `:hiera_config` (String, Optional)
+
+Path to the Hiera configuration file (generally named `hiera.yaml`) for your Puppet installation. Please see [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md) for details on Hiera configuration.
+
+#### `:hiera_path` (String, Optional)
+
+Directory within your Puppet installation where Hiera data is stored. Please see [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md) for details on Hiera configuration.
+
+If your Puppet setup is modeled after the [Puppet control repository template](https://github.com/puppetlabs/control-repo), the correct setting for `:hiera_path` is `'hieradata'`.
+
+#### `:puppet_binary` / `:to_puppet_binary` / `:from_puppet_binary` (String, Required)
+
+Path to the Puppet binary on your system.
+
+Please refer to [Configuring octocatalog-diff to use Puppet](/doc/configuration-puppet.md) for details of connecting octocatalog-diff to your Puppet installation.
+
+In most cases, you will use the `:puppet_binary` option to set the Puppet binary for both the "to" and "from" catalogs. In the case that you are comparing the catalogs produced by two different versions of Puppet, you may use `:to_puppet_binary` and/or `:from_puppet_binary` as needed.
+
+#### `:puppetdb_url` (String, Optional)
+
+URL to PuppetDB. See [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md) for instructions on this setting, and other settings that may be needed in your environment.
+
+#### `:to_branch` / `:from_branch` (String, Optional)
+
+Branch name in git repository to use for Puppet code. Each option must be used in conjunction with `:basedir` so that code can be located.
+
+If you have specified `:bootstrapped_from_dir` or `:from_catalog`, then `:from_branch` will be ignored.
+
+If you have specified `:bootstrapped_to_dir` or `:to_catalog`, then `:from_branch` will be ignored.
+
+#### `:to_catalog` / `:from_catalog` (String, Optional)
+
+If you have already compiled a catalog, set `:to_catalog` and/or `:from_catalog` to the full path to the catalog file.
+
+If you specify a `:XXX_catalog` setting, this will cause `:bootstrapped_XXX_dir` and `:XXX_branch` parameters to be ignored.
+
+### Controlling diffs
+
+#### `:ignore` (Array&lt;Hash&gt;, Optional)
+
+Populating the `:ignore` array filters out matching differences from the overall result using the built-in logic. Please refer to [Ignoring certain changes from the command line](/doc/advanced-ignores.md) for details.
+
+The expected data structure for ignoring a type (e.g. `File` or `Exec`) or title is to construct a hash with a regular expression, like this.
+
+  ```
+  # Simple definition, ignores File[/etc/foo]
+  [ { type: Regexp.new('\AFile\z'), title: Regexp.new('\A/etc/foo\z') } ]
+
+  # More complicated definition, ignores files in 'tmp' or '.tmp' directories wherever they exist
+  [ { type: Regexp.new('\AFile\z'), title: Regexp.new('/\.?tmp/') } ]
+
+  # Ignore all anchors
+  [ { type: Regexp.new('\AAnchor\z') } ]
+
+  # Ignore all resources of any type that contain 'foo' in the title
+  [ { title: Regexp.new('foo') } ]
+  ```
+
+To ignore based on attributes, it is important to understand that each catalog resource is structured as a hash, sometimes with depth greater than 1. An example of Puppet code and the corresponding catalog structure is shown here:
+
+  ```
+  # Puppet code
+  file { '/etc/hostname':
+    owner   => 'root',
+    notify  => [ Service['postfix'], Exec['update hostname'] ],
+    content => $::fqdn,
+  }
+
+  # In the catalog (somewhat abbreviated for brevity)...
+  {
+    "type": "File",
+    "title": "/etc/hostname",
+    "parameters": {
+      "owner": "root",
+      "notify": [
+        "Service[postfix]",
+        "Exec[update hostname]"
+      ],
+      "content": "foo-bar.example.com"
+    }
+  }
+  ```
+
+In this case, "owner", "notify", and "content" are nested under "parameters". Internally in octocatalog-diff, this nesting is represented by the "\f" character. (We chose a character that you should have no reason to put in your resource titles or key names.) Thus, the following examples work:
+
+  ```
+  # Ignore all changes to the `owner` attribute of a file.
+  [ { 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" } ]
+  ```
+
+#### `:validate_references` (Array&lt;String&gt;, 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.
+
+You must set this parameter to an **Array** that contains one or more of the following values:
+
+  - `before`
+  - `notify`
+  - `require`
+  - `subscribe`
+
+## Exceptions
+
+The following exceptions may occur during the compilation of a catalog within the catalog-diff operation:
+
+- `OctocatalogDiff::Errors::BootstrapError`
+
+  Bootstrapping failed.
+
+- `OctocatalogDiff::Errors::CatalogError`
+
+  Catalog failed to compile. Please note that whenever possible, a `OctocatalogDiff::API::V1::Catalog` object is still constructed for a failed catalog, with `#valid?` returning false.
+
+- `OctocatalogDiff::Errors::GitCheckoutError`
+
+  Git checkout failed.
+
+- `OctocatalogDiff::Errors::PuppetVersionError`
+
+  The version of Puppet could not be determined, generally because the Puppet binary was not found, or does not respond as expected to `puppet version`.
+
+- `OctocatalogDiff::Errors::ReferenceValidationError`
+
+  See [Catalog validation](/doc/advanced-catalog-validation.md).