octocatalog-diff 0.6.1 → 1.0.0

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

@@ -0,0 +1,115 @@
+# octocatalog-diff v1 API documentation: catalog
+
+## Overview
+
+`catalog` returns an `OctocatalogDiff::Catalog` object built with the octocatalog-diff compiler, obtained from a Puppet server, or read in from a file. This is analogous to using the `--catalog-only` option with the octocatalog-diff command-line script.
+
+```
+catalog_obj = OctocatalogDiff::API::V1.catalog(<Hash>)
+#=> OctocatalogDiff::API::V1::Catalog
+```
+
+The return value is an [`OctocatalogDiff::API::V1::Catalog`](/doc/dev/api/v1/objects/catalog.md) object.
+
+For an example, see [catalog-builder-local-files.rb](/examples/api/v1/catalog-builder-local-files.rb).
+
+## Parameters
+
+The `catalog` method takes one argument, which is a Hash containing parameters.
+
+The list of parameters here is not exhaustive. The `.catalog` method accepts most parameters described in [Configuration](/doc/configuration.md), [Building catalogs instead of diffing catalogs](/doc/advanced-catalog-only.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 compilation. Simply combine the hash returned by `.config` with any additional keys, and pass the merged hash to the `.catalog` method.
+
+### Global parameters
+
+#### `:logger` (Logger, Optional)
+
+Debugging and informational messages will be logged to this object as the catalog is built.
+
+If no Logger object is passed, these messages will be silently discarded.
+
+#### `:node` (String, Required)
+
+The node name whose catalog is to be compiled or 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` to specify the branch name that should be checked out.
+
+If your Puppet code is not in a git repository, or you already have the branch checked out via some other process, use `:bootstrapped_to_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` (String, Optional)
+
+Directory that is already prepared ("bootstrapped") and can have Puppet run against its contents to compile the 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)
+
+#### `: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.
+
+#### `: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.
+
+#### `: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` (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.
+
+#### `: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` (String, Optional)
+
+Branch name in git repository to use for Puppet code. This option must be used in conjunction with `:basedir` so that code can be located.
+
+## Exceptions
+
+The following exceptions may occur during the compilation of a catalog:
+
+- `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).

data/doc/dev/api/v1/calls/config.md

@@ -0,0 +1,37 @@
+# octocatalog-diff v1 API documentation: config
+
+## Overview
+
+`config` reads and parses an [octocatalog-diff configuration file](/doc/configuration.md).
+
+```
+options = OctocatalogDiff::API::V1.config(
+  filename: "String",
+  logger: Logger,
+  test: <true|false>
+)
+```
+
+## Options
+
+- **`:filename`** (String, optional): Full path to configuration file to read. If not provided, the configuration file will be searched as described in [Configuration](/doc/configuration.md).
+
+- **`:logger`** (Logger, optional): Logger object. If provided, debug messages and fatal errors will be logged to this object.
+
+- **`:test`** (Boolean, optional): Test mode, defaults to false. If true, the value of the configuration settings will be logged to the logger (with priority DEBUG) and an exception will be raised if the configuration file cannot be located.
+
+## Return value
+
+If the configuration file is located and valid, the return value is a Hash consisting of the options defined in the configuration file.
+
+If the configuration file cannot be found, the return value is an empty Hash (`{}`). Except, with `:test => true`, an exception will be raised.
+
+## Exceptions
+
+- `OctocatalogDiff::Errors::ConfigurationFileContentError`
+
+  Raised if the configuration file could not be evaluated. A more specific error message will help identify the cause. Possible causes include the file not being valid ruby, the file not containing the expected structure or methods, or the method returning something other than a Hash.
+
+- `OctocatalogDiff::Errors::ConfigurationFileNotFoundError`
+
+  Raised if the configuration file could not be found, *and* `:test => true` was supplied. (Note, if no configuration file is found, but `:test => false`, no error is raised, and `{}` is returned.)

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

@@ -0,0 +1,127 @@
+# octocatalog-diff v1 API documentation: OctocatalogDiff::API::V1::Catalog
+
+## Overview
+
+`OctocatalogDiff::API::V1::Catalog` is an object that represents a compiled catalog.
+
+It wraps the [`OctocatalogDiff::Catalog`](/lib/octocatalog-diff/catalog.rb) object.
+
+This object is the return value from the [`catalog`](/doc/dev/api/v1/calls/catalog.md) API call, and the `to` and `from` catalogs computed by the [`catalog-diff`](/doc/dev/api/v1/calls/catalog-diff.md) API call.
+
+## Methods
+
+#### `#builder` (String)
+
+Returns the name of the class the built the catalog.
+
+```
+catalog.builder #=> 'OctocatalogDiff::Catalog::JSON'
+```
+
+#### `#compilation_dir` (String)
+
+Returns the temporary directory in which the catalog was compiled.
+
+```
+catalog.compilation_dir #=> '/var/folders/dw/5ftmkqk972j_kw2fdjyzdqdw0000gn/T/d20170108-95774-1r4ohjd'
+```
+
+This is only applicable for catalogs compiled by `OctocatalogDiff::Catalog::Computed`. This method will return `nil` for catalogs generated by other backends.
+
+#### `#error_message` (String)
+
+Returns the error message for a failed catalog. (If the catalog is valid, this returns `nil`.)
+
+```
+good_catalog.valid?         #=> true
+good_catalog.error_message  #=> nil
+
+bad_catalog.valid?          #=> false
+bad_catalog.error_message   #=> 'Failed to compile catalog for node ...'
+```
+
+#### `#puppet_version` (String)
+
+Returns the Puppet version used to compile the catalog.
+
+```
+catalog.puppet_version  #=> '3.8.7'
+```
+
+This is only applicable for catalogs compiled by `OctocatalogDiff::Catalog::Computed`. This method will return `nil` for catalogs generated by other backends.
+
+#### `#resource(<Hash>)` (Hash)
+
+Returns the hash representation of the object identified by the type and title supplied.
+
+This method requires 1 argument, which is a hash containing `:type` and `:title` keys.
+
+```
+catalog.resource(type: 'File', title: '/etc/foo')
+#=> {"title"=>"/etc/foo", "type"=>"File",
+    "parameters"=>{"content"=>"This is the file", "owner"=>"root"},
+    "file"=>"/etc/puppetlabs/code/environments/production/manifests/site.pp", "line"=>25}
+```
+
+Returns `nil` if the type+title resource was not present in the catalog.
+
+##### Notes
+
+1. The first call to this method will build a hash table (`O(N)` operation) from the resource array. Thereafter, each call to this method will look up the value in that hash table (`O(1)` operation). To perform lookups of known types and titles, it is faster to use this method than to use `#resources` with array operations when performing multiple lookups.
+
+2. The structure of the returned hash is dependent on the representation of the resource in the Puppet catalog. It is therefore possible that different versions of Puppet could cause different data structures. It is the author's experience that Puppet 3.8.7 and Puppet 4.x produce similar (if not indistinguishable) resource representations.
+
+3. This method will also locate a resource that was named using an alias.
+
+  ```
+  # Puppet code
+  file { '/etc/foo':
+    alias => 'foo file for the win',
+    ...
+  }
+
+  # octocatalog-diff API
+  catalog.resource(type: 'File', title: 'foo file for the win')
+  #=> {"title"=>"/etc/foo", "type"=>"File", ...}
+  ```
+
+#### `#resources` (Array&lt;Hash&gt;)
+
+Returns an array of catalog resources in a successful catalog. (If the catalog is not valid, this returns `nil`.)
+
+```
+bad_catalog.valid?      #=> false
+bad_catalog.resources   #=> nil
+
+good_catalog.valid?     #=> true
+good_catalog.resources
+#=> [
+  { "title"=>"/etc/foo", "type"=>"File", ... },
+  { "title"=>"/bin/true", "type"=>"Exec", ... }
+]
+```
+
+The structure of the returned hash is dependent on the representation of the resource in the Puppet catalog. It is therefore possible that different versions of Puppet could cause different data structures. It is the author's experience that Puppet 3.8.7 and Puppet 4.x produce similar (if not indistinguishable) resource representations.
+
+#### `#to_json` (String)
+
+Returns the JSON representation of a successful catalog. (If the catalog is not valid, this returns `nil`.)
+
+```
+bad_catalog.valid?     #=> false
+bad_catalog.to_json    #=> nil
+
+good_catalog.valid?    #=> true
+good_catalog.to_json   #=> '{ "document_type": "Catalog", ... }'
+```
+
+#### `#valid?` (Boolean)
+
+Returns `true` if the catalog is valid, and `false` if the catalog is not valid.
+
+## Other methods
+
+These methods are available for debugging or development purposes but are not guaranteed to remain consistent between versions:
+
+- `#to_h` (Hash): Returns hash representation of parsed JSON catalog
+- `#raw` (OctocatalogDiff::Catalog): Returns underlying internal catalog object

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

@@ -0,0 +1,261 @@
+# octocatalog-diff v1 API documentation: OctocatalogDiff::API::V1::Diff
+
+## Overview
+
+`OctocatalogDiff::API::V1::Diff` is an object that represents a single difference between two catalogs.
+
+The return value from the `diffs` computed by the [`catalog-diff`](/doc/dev/api/v1/calls/catalog-diff.md) API call is an Array of these `OctocatalogDiff::API::V1::Diff` objects.
+
+## Methods
+
+#### `#addition?` (Boolean)
+
+Returns true if this diff is an addition (resource exists in new catalog but not old catalog).
+
+#### `#change?` (Boolean)
+
+Returns true if this diff is a change (resource exists in both catalogs but is different between them).
+
+#### `#diff_type` (String)
+
+Returns the type of difference, which is one of the following characters:
+
+- `+` for addition (resource exists in new catalog but not old catalog)
+- `-` for removal (resource exists in old catalog but not new catalog)
+- `~` or `!` for change (resource exists in both catalogs but is different between them)
+
+See also: `#addition?`, `#change?`, `#removal?`
+
+Note: Internally `~` and `!` represent different types of changes, but when presenting the output, these can generally be considered equivalent.
+
+#### `#new_file` (String)
+
+Returns the filename of the Puppet manifest giving rise to the resource as it exists in the new catalog.
+
+Note that this is a pass-through of information provided in the Puppet catalog, and is not calculated by octocatalog-diff. If the Puppet catalog does not contain this information, this method will return `nil`.
+
+Note also that if the diff represents removal of a resource, this will return `nil`, because the resource does not exist in the new catalog.
+
+#### `#new_line` (String)
+
+Returns the line number within the Puppet manifest giving rise to the resource as it exists in the new catalog. (See `#new_file` for the filename of the Puppet manifest.)
+
+Note that this is a pass-through of information provided in the Puppet catalog, and is not calculated by octocatalog-diff. If the Puppet catalog does not contain this information, this method will return `nil`.
+
+Note also that if the diff represents removal of a resource, this will return `nil`, because the resource does not exist in the new catalog.
+
+#### `#new_location` (Hash)
+
+Returns a hash containing `:file` (equal to `#new_file`) and `:line` (equal to `#new_line`) when either is defined. Returns `nil` if both are undefined.
+
+#### `#new_value` (Object)
+
+Returns the value of the resource from the new catalog.
+
+- If a resource was added, this returns the data structure associated with the resource in the Puppet catalog. For example, if the resource was created as follows in the Puppet catalog, the `new_value` is as indicated.
+
+  ```
+  # Resource in New Catalog
+  {
+    "type": "File",
+    "title": "/etc/foo",
+    "parameters": {
+      "owner": "root",
+      "content": "hello new world"
+    }
+  }
+
+  # Demonstrates new_value
+  diff.new_value #=> { 'parameters' => { 'owner' => 'root', 'content' => 'hello new world' } }
+  ```
+
+- If a resource was removed, this returns `nil` because there was no value of this resource in the new catalog.
+
+- If a resource was changed, this returns the portion of the data structure that is indicated by the `.structure` method. For example, if the resource existed as follows in both the old and new Puppet catalogs, the `new_value` is as indicated.
+
+  ```
+  # Resource in Old Catalog
+  {
+    "type": "File",
+    "title": "/etc/foo",
+    "parameters": {
+      "owner": "root",
+      "content": "This is the old file"
+    }
+  }
+
+  # Resource in New Catalog
+  {
+    "type": "File",
+    "title": "/etc/foo",
+    "parameters": {
+      "owner": "root",
+      "content": "This is the NEW FILE!!!!!"
+    }
+  }
+
+  # Demonstrates structure and old_value
+  diff.structure #=> ['parameters', 'content']
+  diff.old_value #=> 'This is the NEW FILE!!!!!'
+  ```
+
+#### `#old_file` (String)
+
+Returns the filename of the Puppet manifest giving rise to the resource as it exists in the old catalog.
+
+Note that this is a pass-through of information provided in the Puppet catalog, and is not calculated by octocatalog-diff. If the Puppet catalog does not contain this information, this method will return `nil`.
+
+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)
+
+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.)
+
+Note that this is a pass-through of information provided in the Puppet catalog, and is not calculated by octocatalog-diff. If the Puppet catalog does not contain this information, this method will return `nil`.
+
+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_location` (Hash)
+
+Returns a hash containing `:file` (equal to `#old_file`) and `:line` (equal to `#old_line`) when either is defined. Returns `nil` if both are undefined.
+
+#### `#old_value` (Object)
+
+Returns the value of the resource from the old catalog.
+
+- If a resource was added, this returns `nil` because there was no value of this resource in the old catalog.
+
+- If a resource was removed, this returns the data structure associated with the resource in the Puppet catalog. For example, if the resource existed as follows in the Puppet catalog, the `old_value` is as indicated.
+
+  ```
+  # Resource in Old Catalog
+  {
+    "type": "File",
+    "title": "/etc/foo",
+    "parameters": {
+      "owner": "root",
+      "content": "hello old world"
+    }
+  }
+
+  # Demonstrates old_value
+  diff.old_value #=> { 'parameters' => { 'owner' => 'root', 'content' => 'hello old world' } }
+  ```
+
+- If a resource was changed, this returns the portion of the data structure that is indicated by the `.structure` method. For example, if the resource existed as follows in both the old and new Puppet catalogs, the `old_value` is as indicated.
+
+  ```
+  # Resource in Old Catalog
+  {
+    "type": "File",
+    "title": "/etc/foo",
+    "parameters": {
+      "owner": "root",
+      "content": "This is the old file"
+    }
+  }
+
+  # Resource in New Catalog
+  {
+    "type": "File",
+    "title": "/etc/foo",
+    "parameters": {
+      "owner": "root",
+      "content": "This is the NEW FILE!!!!!"
+    }
+  }
+
+  # Demonstrates structure and old_value
+  diff.structure #=> ['parameters', 'content']
+  diff.old_value #=> 'This is the old file'
+  ```
+
+#### `#removal?` (Boolean)
+
+Returns true if this diff is a removal (resource exists in old catalog but not new catalog).
+
+#### `#structure` (Array)
+
+Returns the structure that has been changed, as an array.
+
+When a resource was added or removed, the result is an empty array. That's because all of the parameters and other metadata from the resource exist entirely in one catalog but not the other.
+
+When a resource has changed, one diff is created for each parameter that changed. For example, both the old and new catalogs contain the file resource `/etc/foo` but just the content has changed:
+
+```
+# Old
+file { '/etc/foo':
+  owner   => 'root',
+  content => 'This is the old file',
+}
+
+# New
+file { '/etc/foo':
+  owner   => 'root',
+  content => 'This is the NEW FILE!!!!!',
+}
+```
+
+Internally, the Puppet catalog for this resource will look like this in the catalogs (this has been abbreviated a bit for clarity):
+
+```
+# Old
+{
+  "type": "File",
+  "title": "/etc/foo",
+  "exported": false,
+  "parameters": {
+    "owner": "root",
+    "content": "This is the old file"
+  }
+}
+
+# New
+{
+  "type": "File",
+  "title": "/etc/foo",
+  "exported": false,
+  "parameters": {
+    "owner": "root",
+    "content": "This is the NEW FILE!!!!!"
+  }
+}
+```
+
+One diff will be generated to represent the change to the content of the file (which in the catalog is nested in the 'parameters' hash). The diff will be structured as follows:
+
+```
+diff.type #=> 'File'
+diff.title #=> '/etc/foo'
+diff.structure #=> ['parameters', 'content']
+```
+
+#### `#title` (String)
+
+Returns the title of the resource from the Puppet catalog.
+
+For example, a diff involving `File['/etc/passwd']` would have:
+
+- `diff.title #=> '/etc/passwd'`
+- `diff.type #=> 'File'`
+
+#### `#type` (String)
+
+Returns the type of the resource from the Puppet catalog.
+
+For example, a diff involving `File['/etc/passwd']` would have:
+
+- `diff.title #=> '/etc/passwd'`
+- `diff.type #=> 'File'`
+
+Note that the type will be capitalized because Puppet capitalizes this in catalogs.
+
+## Other methods
+
+These methods are available for debugging or development purposes but are not guaranteed to remain consistent between versions:
+
+- `#inspect` (String): Returns inspection of object
+- `#raw` (Array): Returns internal array data structure of the "diff"
+- `#to_h` (Hash): Returns object as a hash, where keys are above described methods
+- `#to_h_with_string_keys` (Hash): Returns object as a hash, where keys are above described methods; keys are strings, not symbols
+- `#[]` (Object): Retrieve indexed array elements from raw internal array object