At my last job, and before I knew much about Puppet, I had a configuration challenge I solved the way a lot of us have: I wrote a script. I got tired of passing lots of configuration parameters to the script, so I created a YAML file. Over time, that YAML file became a source of truth upon which all my scripts depended. If you're using Puppet, you already understand why the scripts had to go. If you've heard about Hiera, you might already know that I got to keep the YAML file.
With Hiera, you create a hierarchy of YAML or JSON files keyed to node characteristics related by Facter. That hierarchy becomes a source of truth for your parameterized classes. You get to drop conditional logic, your site manifests shrink, and you have a single place you can go to feed your Puppet modules with data. Lots of people think that sounds exciting and useful, but the formal documentation on how to use Hiera was a little slow to appear, so users were left piecing together fragments from Github repos, PuppetConf talks, and the occasional blog entry. In the past month or so, we have pushed a number of pages up to the Puppet Labs docs site that ought to make learning Hiera considerably easier.
Are You a Pouncer or a Stalker?
Some people learn by jumping in right away and putting their hands on things. That's the "pouncer" learning style. "Stalkers" are a little more circumspect, preferring to circle a problem before jumping in. The complete Hiera example is designed for pouncers. We wrote it to make it easy for you to start with the simplest of hierarchies. It starts with a simple problem: You need to configure a few ntp servers on your network and want to learn how to do that based on their fully qualified domain names. By the time you're done with the first part of the tutorial, you've got two ntp servers with unique configurations, a radically smaller site manifest, and the ability to use Hiera to feed data to your parameterized classes using simple JSON files. The second part of the example moves into territory not as many people may have heard of: Assigning classes to nodes based on Facter facts. You start out with a network running any number of VMware guests, then use Hiera to make sure each of these virtual machines has an up-to-date version of VMware tools installed on it. To show you how Hiera can work with multiple facts to achieve a configuration goal, the tutorial shows how to use the VM's operating system to make decisions about how to install the package. By the time you're done with the complete example, you'll have plenty to pick a favorite module of your own and apply what you've learned to it.
Stalkers Welcome, Too
Since stalkers like to learn by circling a problem and studying it, we've added plenty in the way of basic documentation that allows you to read all about Hiera, from writing simple data sources to testing it on the command line to using it in your Puppet manifests. Here's a quick tour:
Learn to Configure Hiera
The documentation on configuring Hiera offers everything you need to get Hiera set up and ready to provide data to your Puppet classes. It shows you:
- Where to put your configuration files
- How to define which backends you want to use
- Where to put your data sources
- How the default configuration changes, depending on the context in which you're using Hiera
Write Hiera Data Sources
Once you've got Hiera set up, you have to learn how to write Hiera data sources. These are the simple JSON or YAML files where you store the configuration data Hiera will provide to your parameterized classes. Our page on data sources shows you samples of YAML and JSON, demonstrating the data types you'll most likely use: strings, arrays and hashes. It also demonstrates how to use variable interpolation tokens in your data sources.
Use Hiera On the Command Line
Once you've got your data sources set up, you'll probably want to test them. Our page on the Hiera command line tool provides setup information and command line options that will allow you to verify your hierarchy is correctly set up. With the command line tool, you can mock in Facter facts and see how Hiera responds to lookup requests without running a live puppet agent against it.
Use Hiera with Puppet
Our Hiera docs culminate with an overview of how to use Hiera with Puppet. Here you'll get configuration information, guidance on how to configure automatic parameter lookups, how to assign classes to nodes, and how to use Hiera's lookup functions in your manifests.
And There's Also Developer Documentation
Finally, along with the recent additions to the documentation page, there's new developer documentation on Hiera as well. The
hiera_include functions have all been added to Puppet's generated references. These functions are available via Puppet's
puppet doc tool, or as HTML on the Puppet docs site.
Do You Just Like to Watch?
That's a lot to take in, and you may not even be sold on the value of Hiera. If that's the case, I recommend you head to YouTube and watch Kelsey Hightower's excellent Hiera presentation from PuppetConf 2012. He walks through setup, demonstrates how to configure ssh, and does an excellent job demonstrating the value Hiera brings to Puppet. Even if Kelsey doesn't convince you to use Hiera, you might want to think about signing up for PuppetConf 2013, where we're going to have lots more talks just like that one.