Merge branch '1.x'

README.md

@@ -1,10 +1,11 @@
-What?
-=====
+# Hiera
 
 A simple pluggable Hierarchical Database.
 
-Why?
-====
+-
+**Tutorials:** Check the docs directory for tutorials.
+
+## Why?
 
 Hierarchical data is a good fit for the representation of infrastructure information.
 Consider the example of a typical company with 2 datacenters and on-site development,
@@ -48,50 +49,47 @@ This is the data model that extlookup() have promoted in Puppet, Hiera has taken
 data model and extracted it into a standalone project that is pluggable and have a few
 refinements over extlookup.
 
-Enhancements over Extlookup?
-============================
+## Enhancements over Extlookup
 
 Extlookup had just one backend, Hiera can be extended with your own backends and represent
 a few enhancements over the base Extlookup approach thanks to this.
 
-Multiple backends are queried
------------------------------
+### Multiple backends are queried
+
 If you have a YAML and Puppet backend loaded and your users provide module defaults in the
 Puppet backend you can use your YAML data to override the Puppet data.  If the YAML doesnt
 provide an answer the Puppet backend will get an oppertunity to provide an answer.
 
-More scope based variable expansion
------------------------------------
+### More scope based variable expansion
+
 Extlookup could parse data like %{foo} into a scope lookup for the variable foo.  Hiera
 retains this ability and any Arrays or Hashes will be recursively searched for all strings
 that will then be parsed.
 
 The datadir and defaults are now also subject to variable parsing based on scope.
 
-No CSV support by default
--------------------------
+### No CSV support by default
+
 We have not at present provided a backward compatible CSV backend.  A converter to
 YAML or JSON should be written. When the CSV backend was first chosen for Puppet the
 Puppet language only supports strings and arrays of strings which mapped well to CSV.
 Puppet has become (a bit) better wrt data and can now handle hashes and arrays of hashes
 so it's a good time to retire the old data format.
 
-Array Searches
---------------
+### Array Searches
+
 Hiera can search through all the tiers in a hierarchy and merge the result into a single
 array.  This is used in the hiera-puppet project to replace External Node Classifiers by
 creating a Hiera compatible include function.
 
-Future Enhancements?
-====================
+## Future Enhancements
 
  * More backends should be created
  * A webservice that exposes the data
  * Tools to help maintain the data files.  Ideally this would be Foreman and Dashboard
    with their own backends
 
-Installation?
-=============
+## Installation
 
 Hiera is available as a Gem called _hiera_ and out of the box it comes with just a single
 YAML backend.
@@ -100,8 +98,7 @@ Hiera is also available as a native package via apt (http://apt.puppetlabs.com)
 
 At present JSON (github/ripienaar/hiera-json) and Puppet (hiera-puppet) backends are availble.
 
-Configuration?
-==============
+## Configuration
 
 You can configure Hiera using a YAML file or by providing it Hash data in your code.  There
 isn't a default config path - the CLI script will probably assume _/etc/hiera.yaml_ though.
@@ -151,8 +148,7 @@ sysadmin: "sysadmin@%{domain}"
 ntpserver: 1.pool.ntp.org
 </pre>
 
-Querying from CLI?
-==================
+## Querying from CLI
 
 You can query your data from the CLI.  By default the CLI expects a config file in _/etc/hiera.yaml_
 but you can pass _--config_ to override that.
@@ -185,8 +181,7 @@ $ hiera -a classes location=dc1
 ["users::common", "users::dc1"]
 </pre>
 
-Querying from code?
-===================
+## Querying from code
 
 This is the same query programatically as in the above CLI example:
 
@@ -208,19 +203,18 @@ hiera = Hiera.new(:config => "/etc/puppet/hiera.yaml")
 puts "ACME Software Version: %s" % [ hiera.lookup("acme_version", "sites/%{location}", scope) ]
 </pre>
 
-Extending?
-==========
+## Extending
 
 There exist 2 backends at present in addition to the bundled YAML one.
 
-JSON
-----
+### JSON
+
 This can be found on github under _ripienaar/hiera-json_.  This is a good example
 of file based backends as Hiera provides a number of helpers to make writing these
 trivial.
 
-Puppet
--------
+### Puppet
+
 This is much more complex and queries the data from the running Puppet state, it's found
 on GitHub under _ripienaar/hiera-puppet_.
 
@@ -233,12 +227,11 @@ When used in Puppet you'd expect Hiera to log using the Puppet infrastructure, t
 plugin includes a Puppet Logger plugin for Hiera that uses the normal Puppet logging
 methods for all logging.
 
-License
--------
+## License
 
 See LICENSE file.
 
-Support
--------
+## Support
+
 Please log tickets and issues at our [Projects site](http://projects.puppetlabs.com)
 

docs/tutorials/getting_started.md

@@ -0,0 +1,113 @@
+# Getting Started
+
+Hiera is a simple hierarchal database which provides an easy to use interface
+for looking up data using a key.
+
+    $ hiera puppetlabs_home_page
+    http://puppetlabs.com
+
+## Installation
+
+We are going to install Hiera using Rubygems, so now is a good time to make
+sure you meet the prerequisites.
+
+### Prerequisites
+
+ * Ruby 1.8.5+
+ * Rubygems 1.3.0+
+
+### Installing Hiera via Rubygems
+
+    $ gem install hiera
+    Successfully installed hiera-0.3.0
+    1 gem installed
+    Installing ri documentation for hiera-0.3.0...
+    Installing RDoc documentation for hiera-0.3.0...
+
+Make sure we can run the hiera command:
+
+    $ hiera -v
+    0.3.0
+
+-
+
+**Note:** Some Linux distributions such as Debian squeeze do not put the gem bin
+directory (`/var/lib/gems/1.8/bin`) in your PATH by default. You may have
+to call hiera using the full path:
+
+    $ /var/lib/gems/1.8/bin/hiera -v
+    0.3.0
+
+## Configuration
+
+Before using Hiera we need to create a configuration file. By default Hiera
+attempts to load `hiera.yaml` from the `/etc/` directory. Lets create that
+file now:
+
+    $ vim /etc/hiera.yaml
+    ---
+    :backends:
+      - yaml
+
+    :hierarchy:
+      - global
+
+    :yaml:
+      :datadir: /var/lib/hiera/data
+
+-
+
+**Note:** If Hiera cannot locate `/etc/hiera.yaml` you will receive the follow
+error when trying to lookup a value:
+
+    $ hiera key
+    Failed to start Hiera: RuntimeError: Config file /etc/hiera.yaml not found
+
+You can specify a different configuration file using the `--config` option:
+
+    $ hiera --config ~/hiera.yaml key
+
+## Adding data
+
+With configuration out of the way, lets add some data. The yaml backend
+expects to find data files under the `datadir` we configured earlier.
+
+Create the `/var/lib/hiera/data` data directory:
+
+    $ mkdir -p /var/lib/hiera/data
+
+For each source in the `hierarchy`, the yaml backend will search for a
+corresponding YAML file under the `datadir`.
+
+For example, our `hierarchy` consists of a single source named `global`. The
+yaml backend will look for `/var/lib/hiera/data/global.yaml`, and if missing
+skips it and move on to the next source in the hierarchy.
+
+Lets add some data to the `global` source:
+
+    $ vim /var/lib/hiera/data/global.yaml
+    ---
+    driftfile: '/etc/ntp/drift'
+    ntpservers:
+      - '0.north-america.pool.ntp.org'
+      - '1.north-america.pool.ntp.org'
+
+## Looking up data
+
+Now that we have our configuration setup and some data, lets lookup the
+'driftfile' key:
+
+    $ /var/lib/gems/1.8/bin/hiera driftfile
+    /etc/ntp/drift
+
+We get extacaly what we expected, '/etc/ntp/drift'.
+
+Running the lookup command with the `--debug` flag, we can see the details
+of how Hiera lookups data:
+
+    $ /var/lib/gems/1.8/bin/hiera driftfile --debug
+    DEBUG: Thu Jun 28 09:54:04 -0400 2012: Hiera YAML backend starting
+    DEBUG: Thu Jun 28 09:54:04 -0400 2012: Looking up driftfile in YAML backend
+    DEBUG: Thu Jun 28 09:54:04 -0400 2012: Looking for data source global
+    /etc/ntp/drift
+

docs/tutorials/hierarchies_sources_and_scope.md

@@ -0,0 +1,123 @@
+# Hierarchies, Sources, and Scope
+
+The key to mastering Hiera is understanding the following concepts:
+
+ * Hierarchies
+ * Sources
+ * Scope
+
+## Hierarchies
+
+At the very core of Hiera are the data hierarchies, which are made up of
+sources. Hierarchies are specified in Hiera configuration file `hiera.yaml` via the
+`:hierarchy:` array.
+
+    :hierarchy:
+      - "%{certname}"
+      - "%{environment}"
+      - default
+
+There are three sources in the above hierarchy, `%{certname}`, `%{environment}`,
+and `default`. The first two sources, `%{certname}` and `%{environment}`,
+represent dynamic sources which will be resolved at runtime. The third source
+`default` is static.
+
+
+When looking up a key Hiera iterates through each source in the hierarchy
+starting with the first one in the list. In our case `%{certname}`. There is
+no limit to the number of sources you can have. But lets not go crazy; try and
+keep your hierarchy below 5 - 6 levels deep. Any more than this you should
+start thinking about custom facts or how your data is organized.
+
+### Order is important
+
+Hiera uses the priority resolution type by default. This means Hiera stops at
+the first source in the hierarchy that provides a non `nil` answer. The
+behavior is a slightly different for the array and hash resolution types. Every
+scope in the hierarchy will be searched, but data is appended not overridden!
+
+## Sources
+
+Each level of the hierarchy is represented by a source which comes in two
+flavors, static and dynamic.
+
+### Static sources
+
+A source is considered static when it appears in the hierarchy as a simple
+string.
+
+    :hierarchy:
+      - default
+
+-
+You should consider using a static source when you want a certain level in
+the hierarchy to apply to all nodes.
+
+### Dynamic sources
+
+A source is considered dynamic when it appears in the hierarchy as a string
+enclosed between `%{}` like this:
+
+    :hierarchy:
+      - %{certname}
+
+Dynamic sources are interpolated by Hiera at runtime.
+
+-
+You should consider using a dynamic source when you want to provide different
+data based on Facter Facts.
+
+## Scope
+
+A scope is a collection of key/value pairs:
+
+    certname: agent.puppetlabs.com
+    environment: production
+    operatingsystem: Debian
+
+If you are thinking scopes look a lot like Facter Facts you are on to
+something. Hiera was designed around Facter Facts being the primary input
+for scope.
+
+### Source interpolation
+
+Hiera uses the scope when interpolating sources in the hierarchy.
+
+<img src='https://github.com/kelseyhightower/hiera/raw/maint/1.0rc/add_getting_started_tutorial/docs/images/hiera_hierarchy_resolution.png' />
+
+Scopes can be empty, and when they are, dynamic sources are excluded from the
+hierarchy at run time.
+
+<img src='https://github.com/kelseyhightower/hiera/raw/maint/1.0rc/add_getting_started_tutorial/docs/images/hiera_hierarchy_resolution_empty_scope.png' />
+
+### Feeding Hiera your scope
+
+You can provide Hiera a scope via the command line using the `--yaml` or
+`--json` options.
+
+For example:
+
+If we had the following scope:
+
+    $ cat /tmp/scope.yaml
+    ---
+    certname: agent.example.com
+    environment: production
+
+
+
+You can feed it to Hiera like this:
+
+    $ hiera --yaml /tmp/scope.yaml driftfile
+    /etc/ntp/drift
+
+-
+**Note:** If you run into the follow error, you need to make sure Puppet is installed:
+
+    Could not load YAML scope: LoadError: no such file to load -- puppet
+
+The reason for this is that the scope yaml file could have been produced by
+Puppet, and contained serialized objects. Since it would be desirable to use 
+Hiera without Puppet, this restrict will be removed in the future.
+
+

ext/debian/changelog → ext/debian/changelog.erb

@@ -1,3 +1,9 @@
+hiera (<%= @debversion %>) lucid maverick natty lenny squeeze precise wheezy sid unstable; urgency=low
+
+  * update to version <%= @debversion %>
+
+ -- Puppet Labs Release  <info@puppetlabs.com>  <%= Time.now.strftime("%a, %d %b %Y %H:%M:%S %z")  %>
+
 hiera (0.99+1.0.0rc2-1puppet1) unstable; urgency=low
 
   * Release of 1.0.0rc2