Basic and practical Hiera example

Hiera is a powerful key/value tool to store, hierarchically, configuration data that you can lookup and use while creating manifests. It is a Puppet project and integrated within our enterprise release, but it can be used standalone in any place where you need to abstract commonly used data from your automation, config management tooling/coding.

Some of my client visits are geared towards new folks discovering Puppet and concepts like Hiera can be a bit overwhelming to start with. With that in mind, I decided to create this post and take Puppet away from Hiera and show you the basic concepts and mechanics behind this tool.

There are many fine examples out there of how to implement Hiera but I find them a little complex for beginners and sometimes not ‘straight to the point’. Therefore, I am writing this post to simplify things a bit and hopefully spark some Hiera creativity in you.

Let’s begin.

For this exercise, we will spin up a simple Debian box using Vagrant and Virtualbox:

mkdir ~/hiera_exercise && cd ~/hiera_exercise
vagrant init debian/jessie64; vagrant up --provider virtualbox

Wait some minutes for the system to come up and ssh to the new Debian system:

vagrant ssh

Now you are in the Debian VM. Switch to root (sudo su -). Hiera needs Ruby so we need to install it:

apt-get update && apt-get install ruby -y

Now obtain the Rubygems package and run the following commands to install:

tar xvzf rubygems-2.6.4.tgz
cd rubygems-2.6.4/
ruby setup.rb

Hiera is available as a gem, so we can install it now:

gem install hiera -v 3.1.2

Since I want this write-up to be strictly about Hiera, I will use other defaults, not Puppet’s. Hiera relies on a configuration file and a data directory. The basic configuration file tells Hiera where and how to lookup stuff. The data directory contains custom files that store the configuration objects you are storing away from your tools, scripts, etc.

First, let’s create the configuration file for Hiera:

vi /etc/hiera.yaml

with this content:

  - yaml
:logger: console

  - common

   :datadir: /var/lib/hiera

Hiera’s config defaults to /etc/puppetlabs/code/hiera.yaml for obvious reasons, but you can always tell it to use a different config file. I will show you that later in the post.

The backends portion tells Hiera which formats it reads. You can very well add JSON in there and have Hiera retrieve from JSON files alongside YAML files.

Logger is for telling Hiera where to send warning or debug messages to.

Hierarchy is the name of the data source(s) that Hiera will perform its’ lookups on. Common here translates to /var/lib/hiera/common.yaml.

At this stage, our configuration is complete. Let’s make some data!

Create the /var/lib/hiera directory:

mkdir -p /var/lib/hiera

And create our common.yaml file in there:

vi /var/lib/hiera/common.yaml

Let’s add the following data:

  first: xuxo
  last: garcia

Woo-hoo! We are done…now we can test Hiera. Performing a Hiera lookup is as simple as this:

hiera -c /etc/hiera.yaml names

-c is telling Hiera to use this configuration file instead of the default one and names is the key that Hiera will lookup to find values.

Hiera should now return:

{"first"=>"xuxo", "last"=>"garcia"}

But, let’s not stop there. We can refine our search and just look for my first name:

hiera -c /etc/hiera.yaml names.first

Which returns:


At this stage, you can add as many different yaml files as you need and as many data objects as you wish to programmatically use. As a final example, you can do a shell script and use the returned value:

# Say hi

export hiera_config="/etc/hiera.yaml"

   name=$(hiera -c ${hiera_config} names.first)
   echo "$name, thanks for this Hiera intro"


Run it and paste message on Comment section! 🙂

Hiera is a very powerful and scalable tool that simplifies the writing of your Puppet manifests and helps in centralizing commonly used objects across your Infrastructure. Please visit Puppet docs for full documentation on how to use Hiera.


One thought on “Basic and practical Hiera example

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s