{"id":20357879,"url":"https://github.com/gandi/hieracles","last_synced_at":"2025-09-12T18:34:59.737Z","repository":{"id":35095771,"uuid":"39262070","full_name":"Gandi/hieracles","owner":"Gandi","description":"Command-line tool for analysis and deep examination of Hiera paramaters in a Puppet setup","archived":false,"fork":false,"pushed_at":"2023-01-06T14:36:33.000Z","size":312,"stargazers_count":10,"open_issues_count":7,"forks_count":5,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-12T03:14:48.204Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gandi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-17T15:48:59.000Z","updated_at":"2024-08-01T14:28:48.000Z","dependencies_parsed_at":"2023-01-15T13:45:39.730Z","dependency_job_id":null,"html_url":"https://github.com/Gandi/hieracles","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/Gandi/hieracles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Fhieracles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Fhieracles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Fhieracles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Fhieracles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gandi","download_url":"https://codeload.github.com/Gandi/hieracles/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Fhieracles/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265558676,"owners_count":23787957,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T23:24:18.861Z","updated_at":"2025-07-17T01:34:34.532Z","avatar_url":"https://github.com/Gandi.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Hieracles\n================\n\n[![Gem Version](https://img.shields.io/gem/v/hieracles.svg)](http://rubygems.org/gems/hieracles)\n[![Downloads](http://img.shields.io/gem/dt/hieracles.svg)](https://rubygems.org/gems/hieracles)\n[![Build Status](https://img.shields.io/travis/Gandi/hieracles.svg)](https://travis-ci.org/Gandi/hieracles)\n[![Coverage Status](https://img.shields.io/coveralls/Gandi/hieracles.svg)](https://coveralls.io/github/Gandi/hieracles)\n[![Dependency Status](https://gemnasium.com/Gandi/hieracles.svg)](https://gemnasium.com/Gandi/hieracles)\n[![Code Climate](https://img.shields.io/codeclimate/github/Gandi/hieracles.svg)](https://codeclimate.com/github/Gandi/hieracles)\n\nHieracles 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.\n\nIt'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.\n\nHave a look at the [Changelog](CHANGELOG.md) for details about the evolution.\n\nPrerequisite\n---------------\n\nThere are many ways to setup puppet and use Hiera. This tool is designed to match a certain kind of setup, including:\n\n- an [external node classifier (ENC)][enc]\n- a yaml hiera datastore\n- classes that only contains includes and no code\n- local availability of a hierafile\n\nAs 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.\n\n\nInstall\n-----------\nAt 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.\n\nDespite this warning, you can\n\n    gem install hieracles\n\nor add in your Gemfile:\n\n    gem 'hieracles'\n\n\nConfiguration\n----------------\nAt first launch it will create a configuration file in `~/.config/hieracles/config.yml`\n\nConfiguration variables are:\n\n- basepath (alias localpath)  \n  This is where your puppet repo is cloned\n- classpath  \n  where to find classes defined in the ENC\n- modulepath  \n  where to find modules called in the classes\n- encpath  \n  where to read information about each nodes\n- hierafile  \n  where to find a hierafile customized for your local puppet installation\n- format  \n  can be plain, console, csv, yaml, rawyaml, json\n- defaultscope  \n  a hash defining scope variables that will be used if not defined by a facts file or by params passed as arguments\n\nFor an  example setup you can check in `spec/files`.\n\nIf you don't specify the basepath, your current location will be used as a base path.\n\nUsage\n-------------\n\n    Usage: hc \u003cfqdn\u003e \u003ccommand\u003e [extra_args]\n\n    Available commands:\n      info        provides the farm, datacenter, country\n                  associated to the given fqdn\n                  An extra param can be added for filtering\n                  eg. hc \u003cfqdn\u003e info timestamp\n                  eg. hc \u003cfqdn\u003e info farm\n      facts       lists facts, either provided as a fact file\n                  or grabbed from puppetdb.\n                  An extra param can be added for filtering\n                  eg. hc \u003cfqdn\u003e facts architecture\n                  eg. hc \u003cfqdn\u003e facts 'memory.*mb'\n      files       list all files containing params affecting this fqdn\n                  (in more than commons)\n      paths       list all file paths for files with params\n      modules     list modules included in the farm where the node is\n      params      list params for the node matching the fqdn\n                  An extra filter string can be added to limit the list\n                  use ruby regexp without the enclosing slashes\n                  eg. hc \u003cfqdn\u003e params postfix.*version\n                  eg. hc \u003cfqdn\u003e params '^postfix'\n                  eg. hc \u003cfqdn\u003e params 'version$'\n      allparams   same as params but including the common.yaml params (huge)\n                  Also accepts a search string\n\n    Extra args:\n      -f \u003cplain|console|csv|yaml|rawyaml|json\u003e - default console\n      -p extraparam=what,anotherparam=this \n      -c \u003cconfigfile\u003e\n      -h \u003chierafile\u003e\n      -b \u003cbasepath\u003e default ./\n      -e \u003cencdir\u003e\n      -v - displays version\n      -y \u003cfact_file\u003e - facts in yaml format\n      -j \u003cfact_file\u003e - facts in json format\n      -i - interactive mode\n      -db - query puppetdb\n      -nodb - do not query puppetdb\n\n\nAbout facts aka. scope\n------------------------\n\nLike with Hiera CLI you can use hieracles with defined top-scope variables. Those top-scope vars can be defined with:\n\n- `-p extraparam=what;anotherparam=this`\n- `-y \u003cfact_file\u003e` 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.\n- `-j \u003cfact_file\u003e` same as above, but with output of `facter -j`\n\nYou can define a default scope in your configuration file `defaultscope` in `~/.confg/hieracles/config.yml`. For example:\n\n    ---\n    classpath: farm_modules/%s/manifests/init.pp\n    hierafile: dev/hiera-local.yaml\n    encpath: enc \n    defaultscope:\n        operatingsystem: Debian\n        lsbdistcodename: Jessie\n\nIn order the scope with be built from:\n\n- the config file\n- if `-y \u003cfile\u003e` option (or `-j`) is present the `defaultscope` in the config file will be totally ignored\n- the `-p key=value` option with overide variable per variable\n\nNote that if the scope var is not defined or if the file declared in hiera config is not found, this entry is silently ignored.\n\nAn 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.\n\n\nOptionnaly connecting to a puppetDB\n--------------------------------------\n\n#### Configuration\n\nWhen adding to the configuration file:\n\n    usedb: false\n    puppetdb:\n      usessl: false\n      host: puppetdb.example.com\n      port: 8080\n\nor for a ssl setup:\n\n    usedb: false\n    puppetdb:\n      usessl: true\n      host: puppetdb.example.com\n      port: 8081\n      key: path/to/key\n      key_password: somepassword\n      cert: path/to/cert\n      ca_file: path/to/ca_file\n      verify_peer: false\n\nNote: the SSL config was not tested yet.\n\n#### Usage\n\nIf you set `usedb: false` the `hc` commands will not query the puppetdb unless you pass the `-db` options.\n\nIf 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.\n\n#### Impact\n\nWhen usedb is true, a call to puppetdb will be made for all commands to retrieve facts if they are present for the queried node.\n\n#### Extra commandline tool: ppdb\n\nWhen hieracles is configured with parameters to connect to PuppetDB, you also can use the ppdb commandline to send direct queries to the database. Check `man ppdb` for more information.\n\n\nCompletion\n-------------\nThere is a simple zsh completion file in `tools/completion`. \n\nIf you use [oh-my-zsh][omz] put it in `~/.oh-my-zsh/completions`\n\n    wget -O ~/.oh-my-zsh/completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/zsh/_hc\n    echo 'compdef _hc hc \"bundle exec hc\"' \u003e\u003e ~/.zshrc\n    echo 'autoload -U _hc' \u003e\u003e ~/.zshrc\n    \nOtherwise \n\n    mkdir ~/.zsh-completions\n    wget -O ~/.zsh-completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/zsh/_hc\n    echo 'fpath=(~/.zsh-completions $fpath)' \u003e\u003e ~/.zshrc\n    echo 'compdef _hc hc \"bundle exec hc\"' \u003e\u003e ~/.zshrc\n    echo 'autoload -U _hc' \u003e\u003e ~/.zshrc\n\nNote: `ppdb` also has a completion file https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/zsh/_ppdb\n\nDebian packaging\n--------------------\n\nA debian/ dir is included you can just use `sbuild` in here and it will build the .deb.\n\nFor new releases:\n\n- update the debian/changelog file\n\nFreeBSD packaging\n--------------------\n\nFor new releases:\n\n- update the Makefile with new version number\n- in a FreeBSD jail or machine:\n```\ncd hieracles\ngit pull\ncd ports/\nmake makesum\n# test the stuff, get that there is no warning or what\nportlint\nmake stage\nmake check-orphans\nmake package\nmake install\nmake deinstall\nmake clean\ncd ..\nshar `find rubygem-hieracles` \u003e rubygem-hieracles.shar\n```\n- on https://bugs.freebsd.org submit the new version\n\n\nTodo\n--------------\n- add json format (done)\n- add override information in yaml format (done)\n- add a command to search for node according to a filter (done)\n- add a command to find all nodes that use a given module\n- add a command that finds all nodes for which a params is defined\n- detect unused params\n- create a repl, which at launch reads all data so the queries are blazing fast\n- adapt to other ENCs\n- adapt to PuppetDB storage\n\nOther hiera tools\n-------------------\n\n- https://github.com/binford2k/hiera_explain\n\nAuthors\n-----------\nHieracles original code is written by [@mose](https://github.com/mose).\n\nLicense\n-----------\nHieracles is available under MIT license. See [LICENSE](./LICENSE) file for more details\n\nCopyright\n------------\ncopyright (c) 2015 Gandi http://gandi.net\n\n\n[puppet]:    https://github.com/puppetlabs/puppet\n[hiera]:     https://github.com/puppetlabs/hiera\n[gandi]:     https://gandi.net\n[enc]:       https://docs.puppetlabs.com/guides/external_nodes.html\n[omz]:       https://github.com/robbyrussell/oh-my-zsh\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgandi%2Fhieracles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgandi%2Fhieracles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgandi%2Fhieracles/lists"}