Getting started with Hiera
This page introduces the basic concepts and tasks to get you started with Hiera, including how to create a hiera.yaml config file and write data. It is the foundation for understanding the more advanced topics described in the rest of the Hiera documentation.
Create a hiera.yaml
config file
The Hiera
config file is called hiera.yaml
. Each environment should have its own hiera.yaml
file.
hiera.yaml
. Paste the following contents into it:
# <ENVIRONMENT>/hiera.yaml
---
version: 5
hierarchy:
- name: "Per-node data" # Human-readable name.
path: "nodes/%{trusted.certname}.yaml" # File path, relative to datadir.
# ^^^ IMPORTANT: include the file extension!
- name: "Per-OS defaults"
path: "os/%{facts.os.family}.yaml"
- name: "Common data"
path: "common.yaml"
This file is in a format called YAML, which is used extensively throughout Hiera.
For more information on YAML, see YAML Cookbook.
The hierarchy
The hiera.yaml
file configures a hierarchy: an ordered list of data
sources.
Hiera searches these data sources in the order they are written. Higher-priority sources override lower-priority ones. Most hierarchy levels use variables to locate a data source, so that different nodes get different data.
This is the core concept of Hiera: a defaults-with-overrides pattern for data lookup, using a node-specific list of data sources.
Write data: Create a test class
A test class writes the data it receives to a temporary file — on the agent when applying the catalog.
Hiera is used with Puppet code, so the first step is to create a Puppet class for testing.
Write data: Set values in common data
Set values in your common data — the level at the bottom of your hierarchy.
-
The current environment’s directory.
-
The data directory, which is a subdirectory of the environment. By default, it's
<ENVIRONMENT>/data
. -
The file path specified by the hierarchy level.
In this case, /etc/puppetlabs/code/environments/production/
+ data/
+ common.yaml
.
# /etc/puppetlabs/code/environments/production/data/common.yaml
---
profile::hiera_test::ssl: false
profile::hiera_test::backups_enabled: true
The third parameter, $site_alias
, has a default value defined in code, so
you can omit it from the data.
Write data: Set per-operating system data
The second level of the hierarchy uses the os
fact to locate its data file. This means it
can use different data files depending on the operating system of the current
node.
For this example,
suppose that your developers use MacBook laptops, which have an OS family of Darwin
. If a developer is running an
app instance on their laptop, it should not send data to your production backup
server, so set $backups_enabled
to
false
.
If you do not run Puppet on any Mac laptops, choose an OS family that is meaningful to your infrastructure.
Related topics: the os fact.
Write data: Set per-node data
The highest level of the example hierarchy uses the value
of $trusted['certname']
to locate its data
file, so you can set data by name for each individual node.
This example supposes
you have a server named jenkins-prod-03.example.com
, and configures it to use SSL and to serve
this application at the hostname ci.example.com
. To try this out, choose the name of a real server that
you can run Puppet
on.
Testing Hiera data on the command line
As you set Hiera data or rearrange your hierarchy, it is important to double-check the data a node will receive.
puppet lookup
command helps test data interactively. For
example:puppet lookup profile::hiera_test::backups_enabled --environment production --node jenkins-prod-03.example.com
This
returns the value true
.To use the puppet
lookup
command effectively:
- Run the command on a Puppet Server node, or on another node that has access to a full copy of your Puppet code and configuration.
- The node you are testing against should have contacted the
server at least once as this makes the facts for that node available to the
lookup
command (otherwise you will need to supply the facts yourself on the command line). - Make sure the command uses the global
confdir
andcodedir
, so it has access to your live data. If you’re not runningpuppet lookup
as root user, specify--codedir
and--confdir
on the command line. - If you use PuppetDB, you can use any node’s facts in a
lookup by specifying
--node <NAME>
. Hiera can automatically get that node’s real facts and use them to resolve data. - If you do not use PuppetDB, or if you want to test for a set of
facts that don't exist, provide facts in a YAML or JSON file and specify that
file as part of the command with
--facts <FILE>
. To get a file full of facts, rather than creating one from scratch, runfacter -p --json > facts.json
on a node that is similar to the node you want to examine, copy thefacts.json
file to your Puppet Server node, and edit it as needed.- Puppet Development Kit comes with predefined fact sets for a variety of platforms. You can use those if you want to test against platforms you do not have, or if you want "typical facts" for a kind of platform.
- If you are not getting the values you expect, try re-running
the command with
--explain
. The--explain
flag makes Hiera output a full explanation of which data sources it searched and what it found in them.
Related topics: The puppet lookup command, confdir, codedir.