Class: Hiera
- Inherits:
-
Object
- Object
- Hiera
- Defined in:
- lib/hiera.rb,
lib/hiera/util.rb,
lib/hiera/error.rb,
lib/hiera/backend.rb,
lib/hiera/version.rb,
lib/hiera/filecache.rb,
lib/hiera/noop_logger.rb,
lib/hiera/puppet_logger.rb,
lib/hiera/console_logger.rb,
lib/hiera/backend/json_backend.rb,
lib/hiera/backend/yaml_backend.rb
Defined Under Namespace
Modules: Backend, Console_logger, Noop_logger, Puppet_logger, Util Classes: Config, Error, FallbackLogger, Filecache, Interpolate, InterpolationInvalidValue, InterpolationLoop, InvalidConfigurationError, RecursiveGuard
Constant Summary collapse
- QUOTED_KEY =
Matches a key that is quoted using a matching pair of either single or double quotes.
/^(?:"([^"]+)"|'([^']+)')$/
- QUOTES =
/[",]/
- VERSION =
"3.2.0"
Class Attribute Summary collapse
-
.logger ⇒ Object
Returns the value of attribute logger.
Instance Attribute Summary collapse
-
#config ⇒ Object
readonly
Returns the value of attribute config.
-
#options ⇒ Object
readonly
Returns the value of attribute options.
Class Method Summary collapse
- .debug(msg) ⇒ Object
-
.version ⇒ String
version is a public API method intended to always provide a fast and lightweight way to determine the version of hiera.
- .version=(version) ⇒ Object
- .warn(msg) ⇒ Object
Instance Method Summary collapse
-
#initialize(options = {}) ⇒ Hiera
constructor
If the config option is a string its assumed to be a filename, else a hash of what would have been in the YAML config file.
-
#lookup(key, default, scope, order_override = nil, resolution_type = :priority) ⇒ Object
Calls the backends to do the actual lookup.
Constructor Details
#initialize(options = {}) ⇒ Hiera
If the config option is a string its assumed to be a filename, else a hash of what would have been in the YAML config file
42 43 44 45 46 47 48 49 50 51 52 |
# File 'lib/hiera.rb', line 42 def initialize(={}) config = [:config] if config.nil? # Look in codedir first, then confdir config = File.join(Util.code_dir, 'hiera.yaml') config = File.join(Util.config_dir, 'hiera.yaml') unless File.exist?(config) end @config = Config.load(config) Config.load_backends end |
Class Attribute Details
.logger ⇒ Object
Returns the value of attribute logger.
16 17 18 |
# File 'lib/hiera.rb', line 16 def logger @logger end |
Instance Attribute Details
#config ⇒ Object (readonly)
Returns the value of attribute config.
38 39 40 |
# File 'lib/hiera.rb', line 38 def config @config end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
38 39 40 |
# File 'lib/hiera.rb', line 38 def @options end |
Class Method Details
.debug(msg) ⇒ Object
35 |
# File 'lib/hiera.rb', line 35 def debug(msg); @logger.debug(msg); end |
.version ⇒ String
version is a public API method intended to always provide a fast and lightweight way to determine the version of hiera.
The intent is that software external to hiera be able to determine the hiera version with no side-effects. The expected use is:
require 'hiera/version'
version = Hiera.version
This function has the following ordering precedence. This precedence list is designed to facilitate automated packaging tasks by simply writing to the VERSION file in the same directory as this source file.
1. If a version has been explicitly assigned using the Hiera.version=
method, return that version.
2. If there is a VERSION file, read the contents, trim any
trailing whitespace, and return that version string.
3. Return the value of the Hiera::VERSION constant hard-coded into
the source code.
If there is no VERSION file, the method must return the version string of the nearest parent version that is an officially released version. That is to say, if a branch named 3.1.x contains 25 patches on top of the most recent official release of 3.1.1, then the version method must return the string “3.1.1” if no “VERSION” file is present.
By design the version identifier is not intended to vary during the life a process. There is no guarantee provided that writing to the VERSION file while a Hiera process is running will cause the version string to be updated. On the contrary, the contents of the VERSION are cached to reduce filesystem accesses.
The VERSION file is intended to be used by package maintainers who may be applying patches or otherwise changing the software version in a manner that warrants a different software version identifier. The VERSION file is intended to be managed and owned by the release process and packaging related tasks, and as such should not reside in version control. The VERSION constant is intended to be version controlled in history.
Ideally, this behavior will allow package maintainers to precisely specify the version of the software they’re packaging as in the following example:
$ git describe --match "1.2.*" > lib/hiera/VERSION
$ ruby -r hiera/version -e 'puts Hiera.version'
1.2.1-9-g9fda440
62 63 64 65 66 67 68 69 |
# File 'lib/hiera/version.rb', line 62 def self.version version_file = File.join(File.dirname(__FILE__), 'VERSION') return @hiera_version if @hiera_version if version = read_version_file(version_file) @hiera_version = version end @hiera_version ||= VERSION end |
.version=(version) ⇒ Object
71 72 73 |
# File 'lib/hiera/version.rb', line 71 def self.version=(version) @hiera_version = version end |
.warn(msg) ⇒ Object
34 |
# File 'lib/hiera.rb', line 34 def warn(msg); @logger.warn(msg); end |
Instance Method Details
#lookup(key, default, scope, order_override = nil, resolution_type = :priority) ⇒ Object
Calls the backends to do the actual lookup.
The scope can be anything that responds to ‘[]`, if you have input data like a Puppet Scope that does not you can wrap that data in a class that has a `[]` method that fetches the data from your source. See hiera-puppet for an example of this.
The order-override will insert as first in the hierarchy a data source of your choice.
Possible values for the resolution_type parameter:
-
:priority - This is the default. First found value is returned and no merge is performed
-
:array - An array merge lookup assembles a value from every matching level of the hierarchy. It retrieves all
of the (string or array) values for a given key, then flattens them into a single array of unique values. If _priority_ lookup can be thought of as a “default with overrides” pattern, _array_ merge lookup can be though of as “default with additions.”
-
:hash - A hash merge lookup assembles a value from every matching level of the hierarchy. It retrieves all of
the (hash) values for a given key, then merges the hashes into a single hash. Hash merge lookups will fail with an error if any of the values found in the data sources are strings or arrays. It only works when every value found is a hash. The actual merge behavior is determined by looking up the keys `:merge_behavior` and `:deep_merge_options` in the Hiera config. `:merge_behavior` can be set to `:deep`, :deeper` or `:native` (explained in detail below).
-
_{ deep merge options }_ - Configured values for ‘:merge_behavior` and `:deep_merge_options`will be completely
ignored. Instead the _resolution_type_ will be a `:hash` merge where the `:merge_behavior` will be the value keyed by `:behavior` in the given hash and the `:deep_merge_options` will be the remaining top level entries of that same hash.
Valid behaviors for the :hash resolution type:
-
native - Performs a simple hash-merge by overwriting keys of lower lookup priority.
-
deeper - In a deeper hash merge, Hiera recursively merges keys and values in each source hash. For each key,
if the value is: - only present in one source hash, it goes into the final hash. - a string/number/boolean and exists in two or more source hashes, the highest priority value goes into the final hash. - an array and exists in two or more source hashes, the values from each source are merged into a single array and de-duplicated (but not automatically flattened, as in an array merge lookup). - a hash and exists in two or more source hashes, the values from each source are recursively merged, as though they were source hashes. - mismatched between two or more source hashes, we haven’t validated the behavior. It should act as described in the deep_merge gem documentation.
-
deep - In a deep hash merge, Hiera behaves the same as for deeper, except that when a string/number/boolean
exists in two or more source hashes, the lowest priority value goes into the final hash. This is considered largely useless and should be avoided. Use _deeper_ instead.
The merge can be given as a hash with the mandatory key ‘:strategy` to denote the actual strategy. This is useful for the `:deeper` and `:deep` strategy since they can use additional options to control the behavior. The options can be passed as top level keys in the `merge` parameter when it is a given as a hash. Recognized options are:
- 'knockout_prefix' Set to string value to signify prefix which deletes elements from existing element. Defaults is _undef_
- 'sort_merged_arrays' Set to _true_ to sort all arrays that are merged together. Default is _false_
- 'merge_hash_arrays' Set to _true_ to merge hashes within arrays. Default is _false_
115 116 117 |
# File 'lib/hiera.rb', line 115 def lookup(key, default, scope, order_override=nil, resolution_type=:priority) Backend.lookup(key, default, scope, order_override, resolution_type) end |