README.md in hieracles-0.2.0 vs README.md in hieracles-0.2.1
- old
+ new
@@ -2,12 +2,12 @@
================
[](http://rubygems.org/gems/hieracles)
[](https://rubygems.org/gems/hieracles)
[](https://travis-ci.org/Gandi/hieracles)
-[](https://codeclimate.com/github/Gandi/hieracles/coverage)
-[](https://gemnasium.com/Gandi/hieracles)
+[](https://coveralls.io/github/Gandi/hieracles?branch=master)
+[](https://gemnasium.com/Gandi/hieracles)
[](https://codeclimate.com/github/Gandi/hieracles)
Hieracles is a command-line tool for analysis and deep examination of [Hiera][hiera] parameters in a [Puppet][puppet] setup. It can be used to quickly visualize, from a local puppet (typically on a developers environment), all the Hiera params related to a specific node.
It's used internally at [Gandi][gandi] and its first incarnation is strongly tied to Gandi puppet architecture. But Hieracles tends to become, in time, a generic Hiera overlay visualization tool.
@@ -53,11 +53,11 @@
- modulepath
where to find modules called in the classes
- encpath
where to read information about each nodes
- hierafile
- where to find a hierafile customised for your local puppet installation
+ where to find a hierafile customized for your local puppet installation
- format
can be plain, console, csv, yaml, rawyaml, json
- defaultscope
a hash defining scope variables that will be used if not defined by a facts file or by params passed as arguments
@@ -71,10 +71,18 @@
Usage: hc <fqdn> <command> [extra_args]
Available commands:
info provides the farm, datacenter, country
associated to the given fqdn
+ An extra param can be added for filtering
+ eg. hc <fqdn> info timestamp
+ eg. hc <fqdn> info farm
+ facts lists facts, either provided as a fact file
+ or grabbed from puppetdb.
+ An extra param can be added for filtering
+ eg. hc <fqdn> facts architecture
+ eg. hc <fqdn> facts 'memory.*mb'
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
@@ -95,17 +103,17 @@
-e <encdir>
-v - displays version
-y <fact_file> - facts in yaml format
-j <fact_file> - facts in json format
-i - interactive mode
+ -db - query puppetdb
+ -nodb - do not query puppetdb
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`
@@ -129,28 +137,66 @@
Note that if the scope var is not defined or if the file declared in hiera config is not found, this entry is silently ignored.
An option, `-i` enables the `interactive mode` in which you are prompted to fill up for undefined scope variables encountered in the hiera config file. This behavior can be made systematic by enabling `interactive: true` in hieracles configuration file.
+Optionnaly connecting to a puppetDB
+--------------------------------------
+
+#### Configuration
+
+When adding to the configuration file:
+
+ usedb: false
+ puppetdb:
+ usessl: false
+ host: puppetdb.example.com
+ port: 8080
+
+or for a ssl setup:
+
+ usedb: false
+ puppetdb:
+ usessl: true
+ host: puppetdb.example.com
+ port: 8081
+ key: path/to/key
+ key_password: somepassword
+ cert: path/to/cert
+ ca_file: path/to/ca_file
+ verify_peer: false
+
+#### Usage
+
+If you set `usedb: false` the `hc` commands will not query the puppetdb unless you pass the `-db` options.
+
+If you set `usedb: true` the `hc` command will query the puppetdb by default and display extra informations for the queried node. This default behavior can be changed by passing the `-nodb` option on the commandline.
+
+#### Impact
+
+When usedb is true, a call to puppetdb will be made for all commands to retrieve facts if they are present for the queried node.
+
+
Completion
-------------
There is a simple zsh completion file in `tools/completion`.
If you use [oh-my-zsh][omz] put it in `~/.oh-my-zsh/completions`
- wget -O ~/.oh-my-zsh/completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/_hc
+ wget -O ~/.oh-my-zsh/completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/zsh/_hc
echo 'compdef _hc hc "bundle exec hc"' >> ~/.zshrc
echo 'autoload -U _hc' >> ~/.zshrc
Otherwise
mkdir ~/.zsh-completions
- wget -O ~/.zsh-completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/_hc
+ wget -O ~/.zsh-completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/zsh/_hc
echo 'fpath=(~/.zsh-completions $fpath)' >> ~/.zshrc
echo 'compdef _hc hc "bundle exec hc"' >> ~/.zshrc
echo 'autoload -U _hc' >> ~/.zshrc
+Note: `ppdb` also has a completion file https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/zsh/_ppdb
Debian packaging
--------------------
A debian/ dir is included you can just use `sbuild` in here and it will build the .deb.
@@ -193,10 +239,10 @@
- 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
+- adapt to PuppetDB storage
Authors
-----------
Hieracles original code is written by [@mose](https://github.com/mose).