Hieracles

Hieracles is a command-line tool for analysis and deep examination of Hiera paramaters in a Puppet setup. It's used internally at Gandi and its first incarnation is strongly tied to Gandi puppet architecture. But Hieracles tends to become, in time, a generic Hiera overlay visualisation tool.

Prerequisite

There are many ways to setup puppet and use hiera. This tool is designed to match a certain kind of setup, including:

an external node classifier (ENC)
a yaml hiera datastore
classes that only contains includes and no code
local availability of a hierafile

As the development is going on, more generic options will be provided, but for now, we mainly make it robust to fit the context we have.

Install

At this stage, it's to early to even think about installing anything. The internal code from Gandi is still in progress of transition towards total freedom and generic usage.

Despite this warning, you can

gem install hieracles

or add in your Gemfile:

gem 'hieracles'

Configuration

At first launch it will create a configuration file in ~/.config/hieracles/config.yml

Configuration variables are:

classpath
modulepath
basepath
encpath
hierafile
format
defaultscope

For an example setup you can check in spec/files.

Usage

Usage: hc <fqdn> <command> [extra_args]

Available commands:
  info        provides the farm, datacenter, country
              associated to the given fqdn
  files       list all files containing params affecting this fqdn
              (in more than commons)
  paths       list all file paths for files with params
  modules     list modules included in the farm where the node is
  params      list params for the node matching the fqdn
              An extra filter string can be added to limit the list
              use ruby regexp without the enclosing slashes
              eg. hc <fqdn> params postfix.*version
              eg. hc <fqdn> params '^postfix'
              eg. hc <fqdn> params 'version$'
  allparams   same as params but including the common.yaml params (huge)
              Also accepts a search string

Extra args:
  -f <plain|console|csv|yaml|rawyaml|json> - default console
  -p extraparam=what;anotherparam=this 
  -c <configfile>
  -h <hierafile>
  -b <basepath> default ./
  -e <encdir>
  -v - displays version
  -y <fact_file> - facts in yaml format
  -j <fact_file> - facts in json format

About facts aka. scope

(work in progress)

Like with Hiera CLI you can use hieracles with defined top-scope variables. Those top-scope vars can be defined with:

-p extraparam=what;anotherparam=this
-y <fact_file> which takes the fact file from a yaml source created by facter -y on your node for example, but it can be written manually for experimentation purposes.
-j <fact_file> same as above, but with output of facter -j

You can define a default scope in your configuration file defaultscope in ~/.confg/hieracles/config.yml. For example:

---
colors: true
classpath: farm_modules/s/manifests/init.pp
hierafile: dev/hiera-local.yaml
encpath: enc 
defaultscope:
    operatingsystem: Debian
    lsbdistcodename: Jessie

In order the scope with be built from:

the config file
if -y <file> option (or -j) is present the defaultscope in the config file will be totally ignored
the -p key=value option with overide variable per variable

Completion

There is a simple zsh completion file in tools/completion.

If you use oh-my-zsh put it in ~/.oh-my-zsh/completions

wget -O ~/.oh-my-zsh/completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/_hc
echo 'compdef _hc hc "bundle exec hc"' >> ~/.zshrc

Otherwise

mkdir ~/.zsh-completions
wget -O ~/.zsh-completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/_hc
echo 'fpath=(~/.zsh-completions $fpath)' >> ~/.zshrc
echo 'compdef _hc hc "bundle exec hc"' >> ~/.zshrc

Debian packaging

On a Jessie

apt-get install gem2deb ruby-coveralls ruby-all-dev ruby-rspec ruby-rspec-expectations

Then build

gem2deb -p hieracles hieracles

and install

dpkg -i hieracles_0.0.6-1_all.deb

Todo

add json format (done)
add override information in yaml format (done)
add a command to search for node according to a filter (done)
add a command to find all nodes that use a given module
add a command that finds all nodes for which a params is defined
detect unused params
create a repl, which at launch reads all data so the queries are blazing fast
adapt to other ENCs
adapt to puppetdb storage