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.

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.

If you do not already use the roles and profiles method, create a module named profile. Profiles are wrapper classes that use multiple component modules to configure a layered technology stack. See the related topic links for more information.

Use Puppet Development Kit (PDK) to create a class called hiera_test.pp in your profile module.

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.

Locate the data file, by replacing %{facts.os.family} with the value you are targeting:

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.

To locate the data file, replace %{trusted.certname}with the node name you’re targeting:

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 need to supply the facts yourself on the command line).

Make sure the command uses the global confdir and codedir, so it has access to your live data. If you’re not running puppet 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, run facter -p --json > facts.json on a node that is similar to the node you want to examine, copy the facts.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.