When you write a puppet module, you might not want to put all the data in to the module because all the module developers might want access to that data. So, It is a good practice to separate the data from the code. This can be achieved using Hiera.

Note: This tutorial is based on puppet enterprise.

Puppet Hiera Tutorial

In this puppet hiera tutorial you will learn the basics of hiera and how to use it in puppet modules.

Hiera is a key value lookup tool which holds all the data that has to be dynamically placed in a module. You can store usernames, passwrod, DNS server details, ldap server details etc. Moreover, you can encrypt the data in hiera for security. Hiera resides in the puppet server for global access unless the client is operating in masterless setup. In that case, it resides in the client itself.

Hiera Configuration File

Hiera comes bundles with puppet enterprise, so you don’t have to install it separately but you might want to change its configuration to suit your needs.

The hiera configuration file resides in “/etc/puppetlabs/code” directory. It is yaml file named “hiera.yml”

A normal configuration file looks like the following.

# managed by puppet
 - yaml
 :logger: console
 - "%{environment}"
 - network
 - first
 - common
 :datadir: /etc/puppet/hieradata

:backends – Hiera supports yaml, json and puppet class backends.

:datadir – The location where you place your hieradata. In the above code snippet, you can see a interpolated string “%{::environment}”. This is to dynamically select an environment in case you have different environments specified in the puppet server. By doing do, you can access the environment specific hiera data.

If you use both yaml and json data directories, you need to specify both as shown in the above code snippet.

:hierarchy This represents the folder and file hierarchy inside the “:datadir” i.e, hieradata folder. You can use interpolation to dynamically pass the file name.

Creating Hiera Data files

Hiera data files could be yaml or json files as mentioned above. All the data files will reside inside the “hieradata” folder in respective environments.

You can keep all the default values under common.yaml file in hieradata folder.

A sample YAML based configuration file is shown below. You can have all the value in key value fashion. You also nest data elements if necessary.

My example is as below

root@vrk:~# cat /etc/puppet/hieradata/first.yaml
     type: ssh-rsa
     key: 'AAB3NzaC1yc2EAAAABJQAAAQEAiWk4fcozVRfzDKGVW9V/hijFF3jsHpKKVpd2hnX9lhYsjSlvz1JQssJL28dAvA=='
sudo_vrk1: 'puppet:///files/etc/sudoers.lxprod'
default: 'puppet:///files/etc/sudoers.lampservers'

Accessing Hiera Data using CLI

Once you have the hiera data ready in the puppet server, you can check the values using hiera CLI.

To access the value , just use the hiera command with the key as shown below.

hiera ldaps_ervers

If you have used interpolation in the “:datadir” configuration, You should add the parameters as shown below.

 hiera ldap_servers ::environment=production

If you want access the value for a key from a yaml file which is high hierarchy, you need to specify that in the lookup. Otherwise it will return the value from the common.yaml file.

Accessing Hiera Data From Modules

Accessing data hiera data from module is relatively easy. Use the following syntax in your module to access the data directly.

$ldapservers = hiera("ldap_servers")

$ldapserver is just a puppet variable. You can substitute hiera without assigning it to a variable.

If you want to get all the ldap_servers value in the hierarchy in an array, you can use the following syntax.

$ldapservers = hiera_array("ldap_servers")

Hiera Arguments

While accessing hiera data through modules, you cat set a default value to use if hiera returns nil. It has the following syntax.

$ldapservers = hiera_array("ldap_servers","")

One more example :


root@vrk:/etc/puppet/environments/production/modules/service/manifests# cat hiera-test.pp
class service::hiera-test {
file { '/var/tmp/test-options1.txt':
      owner       => root,
      group       => root,
      mode        => 644,
    source => hiera("sudo_$hostname","puppet:///files/etc/sudoers.lamp")

here $hostname data will come form facter. if the required data not available in any .yaml file it will return nil then it will take side value “puppet:///files/etc/sudoers.lamp” as default value.

Example for user creation with ssh key and used create_resource function

root@vrk:/etc/puppet/environments/production/modules/users/manifests# cat vkk.pp
class users::vkk {

 $user = “vkk”
  $uid  = “7730”
  $gid  = “100”

    name           => “$user”,
    ensure         => present,
    uid            => “$uid”,
    gid            => “$gid”,
    comment        => ‘created by puppet’,
    shell          => ‘/bin/bash’,
    home           => “/home/$user”,
    purge_ssh_keys => true,
    password       => ‘$1$ndjyqT1S$rR/kwWjcem7t6VdNyWIC3.’,
    managehome     => true,

 $k1 = hiera_hash(“ssh_keys::$user”)
 $other_ssh_options = {
     ‘ensure’  => present,
     ‘user’    => “$user”,
     ‘require’ => User[“$user”],
  create_resources( ssh_authorized_key, $k1, $other_ssh_options )


References :