Hiera 3: Writing Data Sources

Included in Puppet Enterprise 2015.3. A newer version is available; see the version menu above for details.

Note: We’ve released a major update to Hiera called Hiera 5.

It’s built into Puppet 4.9 and higher, and includes features like per-environment hierarchies, module data, simplified custom backends, improved debugging with puppet lookup --explain, and more.

As part of this update, we’ve moved Hiera’s documentation into the Puppet reference manual. Once you’ve upgraded to Puppet 4.9 or higher, see the following pages for more info about the new Hiera:

Hiera can use several different data backends, including two built-in backends and various optional backends. Each backend uses a different document format for its data sources.

This page describes the built-in yaml and json backends, as well as the puppet backend included with Hiera’s Puppet integration. For optional backends, see the backend’s documentation.

YAML

Summary

The yaml backend looks for data sources on disk, in the directory specified in its :datadir setting. It expects each data source to be a text file containing valid YAML data, with a file extension of .yaml. No other file extension (e.g. .yml) is allowed.

Data Format

See yaml.org and the “YAML for Ruby” cookbook for a complete description of valid YAML.

The root object of each YAML data source must be a YAML mapping (hash). Hiera will treat its top level keys as the pieces of data available in the data source. The value for each key can be any of the data types below.

Hiera’s data types map to the native YAML data types as follows:

Hiera YAML
Hash Mapping
Array Sequence
String Quoted scalar or non-boolean unquoted scalar
Number Integer or float
Boolean Boolean (note: includes on and off, yes and no in addition to true and false)

Any string may include any number of interpolation tokens.

Important note: The “psych” YAML parser, which is used by many Ruby versions, requires that any strings containing a % be quoted.

Example

---
# array
apache-packages:
    - apache2
    - apache2-common
    - apache2-utils

# string
apache-service: apache2

# interpolated facter variable
hosts_entry: "sandbox.%{::fqdn}"

# hash
sshd_settings:
    root_allowed: "no"
    password_allowed: "yes"

# alternate hash notation
sshd_settings: {root_allowed: "no", password_allowed: "yes"}

# to return "true" or "false"
sshd_settings: {root_allowed: no, password_allowed: yes}

JSON

Summary

The json backend looks for data sources on disk, in the directory specified in its :datadir setting. It expects each data source to be a text file containing valid JSON data, with a file extension of .json. No other file extension is allowed.

Data Format

See the JSON spec for a complete description of valid JSON.

The root object of each JSON data source must be a JSON object (hash). Hiera will treat its top level keys as the pieces of data available in the data source. The value for each key can be any of the data types below.

Hiera’s data types map to the native JSON data types as follows:

Hiera JSON
Hash Object
Array Array
String String
Number Number
Boolean true / false

Any string may include any number of interpolation tokens.

Example

{
    "apache-packages" : [
    "apache2",
    "apache2-common",
    "apache2-utils"
    ],

    "hosts_entry" :  "sandbox.%{fqdn}",

    "sshd_settings" : {
                        "root_allowed" : "no",
                        "password_allowed" : "no"
                      }
}

↑ Back to top