The most basic usage of octocatalog-diff is to compare catalogs built from two different git branches, for a node of your choosing.
You should be aware of these defaults, all of which are configurable.
octocatalog-diff will default to compiling catalogs based on the assumption that your Puppet code resides in a git repository. If your Puppet code does not reside in a git repository, head over to the advanced instructions for workarounds.
octocatalog-diff will compile the catalog produced from the
origin/masterbranch of your repository as the "from" catalog, and the catalog produced from your current working directory as the "to" catalog. You can override these defaults with the
-t BRANCHarguments, for the "from" and "to" branches, respectively.
octocatalog-diff will assume you are not using hiera or an external node classifier, unless you configure it accordingly, or use the appropriate command line arguments to point it at your hiera configuration and/or ENC script.
You are required to provide the following information, either as a command line argument, in the configuration, or in some cases, via the environment:
The node name whose catalogs you wish to compile. Use
-n HOSTNAMEon the command line.
Facts, which can either be retrieved from PuppetDB or via the
--fact-filecommand line option. See the usage examples below.
From git repository with facts from PuppetDB
export PUPPETDB_URL="http://puppetdb.yourdomain.com:8080" cd Puppet_Checkout_Directory git checkout master git pull octocatalog-diff -n SomeNodeName.yourdomain.com
Using a fact file
You can retrieve the fact file from your Puppet Master (3.x) typically in
/var/lib/puppet/yaml/facts/<node>.yaml, or your Puppet Server (4.x) typically in
/opt/puppetlabs/server/data/puppetserver/yaml/facts/<node>.yaml. We recommend using PuppetDB as a more convenient fact source, but you can copy the fact file for a node from your Puppet server onto the machine running octocatalog-diff for testing purposes.
# Copy the fact file for SomeNodeName.yourdomain.com into /tmp/SomeNodeName.yourdomain.com.yaml cd Puppet_Checkout_Directory git checkout master git pull octocatalog-diff -n SomeNodeName.yourdomain.com --fact-file /tmp/SomeNodeName.yourdomain.com.yaml
This example demonstrates how to point octocatalog-diff at your Hiera configuration file. The Hiera configuration file for your site might be found in
/etc/puppet/hiera.yaml (for Puppet 3.x) or
/etc/puppetlabs/puppet/hiera.yaml (for Puppet 4.x).
Note that you will either need to configure the PuppetDB URL or specify a
--fact-file for this to work.
# Copy the fact file for SomeNodeName.yourdomain.com into /tmp/SomeNodeName.yourdomain.com.yaml # (or) # Set the PUPPETDB_URL variable as shown in the first example # # Also copy hiera.yaml from your Puppet master into the /tmp directory cd Puppet_Checkout_Directory git checkout master git pull octocatalog-diff -n SomeNodeName.yourdomain.com --hiera-config /tmp/hiera.yaml
Depending on your hiera configuration, you may also need to supply the
--hiera-path-strip option (or set that option in your configuration). Consult the configuring octocatalog-diff to use Hiera document for details on this option.
If you're ready to learn about additional command line flags to customize your experience, head to Advanced usage.
If you experience problems running octocatalog-diff even with these most basic arguments, please see Troubleshooting.
If you are not using git to manage your Puppet source code, you will need to see the Advanced usage instructions to get your directories manually bootstrapped for use, or use one of the other supported methods to build catalogs.