{"id":15022588,"url":"https://github.com/puppetlabs/hiera","last_synced_at":"2025-04-29T14:38:41.756Z","repository":{"id":667588,"uuid":"1845241","full_name":"puppetlabs/hiera","owner":"puppetlabs","description":"Lightweight Pluggable Hierarchical Database","archived":false,"fork":false,"pushed_at":"2025-02-04T16:39:33.000Z","size":877,"stargazers_count":300,"open_issues_count":0,"forks_count":190,"subscribers_count":181,"default_branch":"main","last_synced_at":"2025-04-17T09:50:46.085Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://puppet.com/docs/hiera/","language":"Ruby","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-06-04T00:48:22.000Z","updated_at":"2025-02-27T15:49:44.000Z","dependencies_parsed_at":"2025-02-12T01:42:10.782Z","dependency_job_id":"636deddd-7110-4666-81be-8f933ba11ca9","html_url":"https://github.com/puppetlabs/hiera","commit_stats":{"total_commits":590,"total_committers":108,"mean_commits":5.462962962962963,"dds":0.8932203389830509,"last_synced_commit":"dfc0b758290bcd285bb325f45d0bac573d1e74c5"},"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fhiera","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fhiera/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fhiera/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fhiera/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/hiera/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250379563,"owners_count":21420834,"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-09-24T19:58:09.070Z","updated_at":"2025-04-29T14:38:41.733Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hiera\n\n[![Build Status](https://travis-ci.org/puppetlabs/hiera.png?branch=master)](https://travis-ci.org/puppetlabs/hiera)\n\nA simple pluggable Hierarchical Database.\n\n**This project is deprecated in favor of Hiera version 5 which is implementation in Puppet.**\n\n**Tutorials:** Check the docs directory for tutorials.\n\n## Why?\n\nHierarchical data is a good fit for the representation of infrastructure information.\nConsider the example of a typical company with 2 datacenters and on-site development,\nstaging etc.\n\nAll machines need:\n\n - ntp servers\n - sysadmin contacts\n\nBy thinking about the data in a hierarchical manner you can resolve these to the most\ncorrect answer easily:\n\n\u003cpre\u003e\n     /------------- DC1 -------------\\             /------------- DC2 -------------\\\n    | ntpserver: ntp1.dc1.example.com |           | ntpserver: ntp1.dc2.example.com |\n    | sysadmin: dc1noc@example.com    |           |                                 |\n    | classes: users::dc1             |           | classes: users::dc2             |\n     \\-------------------------------/             \\-------------------------------/\n                                \\                      /\n                                  \\                  /\n                           /------------- COMMON -------------\\\n                          | ntpserver: 1.pool.ntp.org          |\n                          | sysadmin: \"sysadmin@%{domain}\"     |\n                          | classes: users::common             |\n                           \\----------------------------------/\n\u003c/pre\u003e\n\nIn this simple example machines in DC1 and DC2 have their own NTP servers, additionaly\nDC1 has its own sysadmin contact - perhaps because its a remote DR site - while DC2\nand all the other environments would revert to the common contact that would have the\nmachines domain fact expanded into the result.\n\nThe _classes_ variable can be searched using the array method which would build up a\nlist of classes to include on a node based on the hierarchy.  Machines in DC1 would have\nthe classes _users::common_ and _users::dc1_.\n\nThe other environment like development and staging would all use the public NTP infrastructure.\n\nThis is the data model that extlookup() have promoted in Puppet, Hiera has taken this\ndata model and extracted it into a standalone project that is pluggable and have a few\nrefinements over extlookup.\n\n## Enhancements over Extlookup\n\nExtlookup had just one backend, Hiera can be extended with your own backends and represent\na few enhancements over the base Extlookup approach thanks to this.\n\n### Multiple backends are queried\n\nIf you have a YAML and Puppet backend loaded and your users provide module defaults in the\nPuppet backend you can use your YAML data to override the Puppet data.  If the YAML doesnt\nprovide an answer the Puppet backend will get an opportunity to provide an answer.\n\n### More scope based variable expansion\n\nExtlookup could parse data like %{foo} into a scope lookup for the variable foo.  Hiera\nretains this ability and any Arrays or Hashes will be recursively searched for all strings\nthat will then be parsed.\n\nThe datadir and defaults are now also subject to variable parsing based on scope.\n\n### No CSV support by default\n\nWe have not at present provided a backward compatible CSV backend.  A converter to\nYAML or JSON should be written. When the CSV backend was first chosen for Puppet the\nPuppet language only supports strings and arrays of strings which mapped well to CSV.\nPuppet has become (a bit) better wrt data and can now handle hashes and arrays of hashes\nso it's a good time to retire the old data format.\n\n### Array Searches\n\nHiera can search through all the tiers in a hierarchy and merge the result into a single\narray.  This is used in the hiera-puppet project to replace External Node Classifiers by\ncreating a Hiera compatible include function.\n\n### Qualified Key Lookup\nYou can use a qualified key to lookup a value that is contained inside a hash or array:\n\n\u003cpre\u003e\n$ hiera user\n{\"name\"=\u003e\"kim\", \"home\"=\u003e\"/home/kim\"}\n$ hiera user.name\nkim\n\u003c/pre\u003e\n\n\u003cpre\u003e\n$ hiera ssh_users\n[\"root\", \"jeff\", \"gary\", \"hunter\"]\n$ hiera ssh_users.0\nroot\n\u003c/pre\u003e\n\n### Use quotes to disable qualified key behavior\nIn case you have dotted keys and thus want to avoid using the qualified key semantics, you\ncan put segments of a dotted key, or the whole key, within quotes.\n\nGiven the following data:\n\n\u003cpre\u003e\n# yaml\na:\n  b.c:\n    d: 'Data for a =\u003e b.c =\u003e d'\n\u003c/pre\u003e\n\nit is possible to do a lookup of the data like this:\n\n\u003cpre\u003e\n$ hiera 'a.\"b.c\".d'\nData for a =\u003e b.c =\u003e d\n\u003c/pre\u003e\n\nQuoting works in interpolation expressions as well.\n\nInterpolating from global scope:\n\n\u003cpre\u003e\n# yaml\nother.key: 'scope data: %{a.\"b.c\".d}'\n\u003c/pre\u003e\n\nor using an interpolation method:\n\n\u003cpre\u003e\n# yaml\na:\n  b.c:\n    d: 'Data for a =\u003e b.c =\u003e d'\nother.key: 'hiera data %{hiera(\"a.''b.c''.d\")}'\n\u003c/pre\u003e\n\nNote that two single quotes are used to escape a single quote inside a single quoted string\n(that's YAML syntax, not Hiera) and that the quoted key must be quoted in turn.\n\n## Future Enhancements\n\n * More backends should be created\n * A webservice that exposes the data\n * Tools to help maintain the data files.  Ideally this would be Foreman and Dashboard\n   with their own backends\n\n## Installation\n\nHiera is available as a Gem called _hiera_ and out of the box it comes with just a single\nYAML backend.\n\nHiera is also available as a native package via apt (http://apt.puppetlabs.com) and yum (http://yum.puppetlabs.com). Instructions for adding these repositories can be found at http://docs.puppetlabs.com/guides/installation.html#debian-and-ubuntu and http://docs.puppetlabs.com/guides/installation.html#enterprise-linux respectively.\n\nAt present JSON (github/ripienaar/hiera-json) and Puppet (hiera-puppet) backends are availble.\n\n## Configuration\n\nYou can configure Hiera using a YAML file or by providing it Hash data in your code.  There\nisn't a default config path - the CLI script will probably assume _/etc/hiera.yaml_ though.\nThe default data directory for file based storage is _/var/lib/hiera_.\n\nA sample configuration file can be seen here:\n\n\u003cpre\u003e\n---\n:backends:\n  - yaml\n  - puppet\n\n:logger: console\n\n:hierarchy:\n  - \"sites/%{location}\"\n  - common\n\n:yaml:\n   :datadir: /etc/puppetlabs/code/hieradata\n\n:puppet:\n   :datasource: data\n\u003c/pre\u003e\n\nThis configuration will require YAML files in  _/etc/puppetlabs/code/hieradata_ these need to contain\nHash data, sample files matching the hierarchy described in the _Why?_ section are below:\n\n_/etc/puppetlabs/code/hieradata/sites/dc1.yaml_:\n\u003cpre\u003e\n---\nntpserver: ntp1.dc1.example.com\nsysadmin: dc1noc@example.com\n\u003c/pre\u003e\n\n_/etc/puppetlabs/code/hieradata/sites/dc2.yaml_:\n\u003cpre\u003e\n---\nntpserver: ntp1.dc2.example.com\n\u003c/pre\u003e\n\n_/etc/puppetlabs/code/hieradata/common.yaml_:\n\u003cpre\u003e\n---\nsysadmin: \"sysadmin@%{domain}\"\nntpserver: 1.pool.ntp.org\n\u003c/pre\u003e\n\n## Querying from CLI\n\nYou can query your data from the CLI.  By default the CLI expects a config file in _/etc/hiera.yaml_\nbut you can pass _--config_ to override that.\n\nThis example searches Hiera for node data.  Scope is loaded from a Puppet created YAML facts\nstore as found on your Puppet Masters.\n\nIf no data is found and the facts had a location=dc1 fact the default would be _sites/dc1_\n\n\u003cpre\u003e\n$ hiera acme_version 'sites/%{location}' --yaml /opt/puppetlabs/puppet/cache/yaml/facts/example.com.yaml\n\u003c/pre\u003e\n\nYou can also supply extra facts on the CLI, assuming Puppet facts did not have a location fact:\n\n\u003cpre\u003e\n$ hiera acme_version 'sites/%{location}' location=dc1 --yaml /opt/puppetlabs/puppet/cache/yaml/facts/example.com.yaml\n\u003c/pre\u003e\n\nOr if you use MCollective you can fetch the scope from a remote node's facts:\n\n\u003cpre\u003e\n$ hiera acme_version 'sites/%{location}' -m box.example.com\n\u003c/pre\u003e\n\nYou can also do array merge searches on the CLI:\n\n\u003cpre\u003e\n$ hiera -a classes location=dc1\n[\"users::common\", \"users::dc1\"]\n\u003c/pre\u003e\n\n## Querying from code\n\nThis is the same query programatically as in the above CLI example:\n\n\u003cpre\u003e\nrequire 'rubygems'\nrequire 'hiera'\nrequire 'puppet'\n\n# load the facts for example.com\nscope = YAML.load_file(\"/opt/puppetlabs/puppet/cache/yaml/facts/example.com.yaml\")\n\n# create a new instance based on config file\nhiera = Hiera.new(:config =\u003e \"/etc/puppetlabs/code/hiera.yaml\")\n\n# resolve the 'acme_version' variable based on scope\n#\n# given a fact location=dc1 in the facts file this will default to a branch sites/dc1\n# and allow hierarchical overrides based on the hierarchy defined in the config file\nputs \"ACME Software Version: %s\" % [ hiera.lookup(\"acme_version\", \"sites/%{location}\", scope) ]\n\u003c/pre\u003e\n\n## Extending\n\nThere exist 2 backends at present in addition to the bundled YAML one.\n\n### JSON\n\nThis can be found on github under _ripienaar/hiera-json_.  This is a good example\nof file based backends as Hiera provides a number of helpers to make writing these\ntrivial.\n\n### Puppet\n\nThis is much more complex and queries the data from the running Puppet state, it's found\non GitHub under _ripienaar/hiera-puppet_.\n\nThis is a good example to learn how to map your internal program state into what Hiera\nwants as I needed to do with the Puppet Scope.\n\nIt includes a Puppet Parser Function to query the data from within Puppet.\n\nWhen used in Puppet you'd expect Hiera to log using the Puppet infrastructure, this\nplugin includes a Puppet Logger plugin for Hiera that uses the normal Puppet logging\nmethods for all logging.\n\n## License\n\nSee LICENSE file.\n\n## Support\n\nPlease log tickets and issues at our [JIRA tracker](http://tickets.puppetlabs.com).  A [mailing\nlist](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is\navailable for asking questions and getting help from others. In addition there\nis an active #puppet channel on Freenode.\n\nWe use semantic version numbers for our releases, and recommend that users stay\nas up-to-date as possible by upgrading to patch releases and minor releases as\nthey become available.\n\nBugfixes and ongoing development will occur in minor releases for the current\nmajor version. Security fixes will be backported to a previous major version on\na best-effort basis, until the previous major version is no longer maintained.\n\n\nFor example: If a security vulnerability is discovered in Hiera 1.3.0, we\nwould fix it in the 1 series, most likely as 1.3.1. Maintainers would then make\na best effort to backport that fix onto the latest Hiera release they carry.\n\nLong-term support, including security patches and bug fixes, is available for\ncommercial customers. Please see the following page for more details:\n\n[Puppet Enterprise Support Lifecycle](http://puppetlabs.com/misc/puppet-enterprise-lifecycle)\n\n## MAINTAINERS\n\n* Thomas Hallgren\n* Henrik Lindberg\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fhiera","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fhiera","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fhiera/lists"}