Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 38 ยท Roles and Profiles

Profiles with Hiera and Parameters

Drive profiles from Hiera data: automatic parameter lookup, hierarchy levels per environment and node, lookup() for glue values, merge behavior and the puppet lookup command.

A profile that has its settings written inside the manifest can serve only one site. The roles and profiles pattern becomes powerful when profiles take every variable setting from Hiera, Puppet's key-value data system. The profile contains the logic, Hiera contains the values, and the same profile can configure a development web server and a production one with different data.

This lesson shows how class parameters are bound automatically to Hiera keys, how a hierarchy picks the right value per node, and how to inspect the result. The product cannot run here, so Hiera files are read-only examples and the runnable blocks are stand-ins that imitate hierarchy resolution.

Automatic parameter lookup

When Puppet evaluates a class that has parameters, it looks for a value in three places, in this order:

  1. A value given explicitly in a resource-like declaration (class { 'x': param => 1 }).
  2. Hiera, under the key <class name>::<parameter name>.
  3. The default in the class definition.

So this profile:

PUPPET
class profile::webserver (
  Integer       $port   = 80,
  Array[String] $vhosts = [],
  Boolean       $tls    = false,
) {
  # ...
}

is configured by Hiera keys, usually stored in YAML:

YAML
# data/common.yaml
profile::webserver::port: 8080
profile::webserver::vhosts:
  - shop.example.com
  - api.example.com

No code changes are needed; include profile::webserver is enough. The key naming rule is strict: the full class name, two colons, the parameter name. A typo in a key does not raise an error, the default is silently used, so use the puppet lookup command to verify.

The hierarchy

Hiera's hierarchy (in hiera.yaml) is an ordered list of data sources. For each key, Hiera checks the levels from top to bottom and returns the first value found. Interpolation functions insert facts into file paths, so one config selects different files for different nodes:

YAML
# hiera.yaml (version 5)
version: 5
defaults:
  datadir: data
  data_hash: yaml_data
hierarchy:
  - name: "Per-node data"
    path: "nodes/%{trusted.certname}.yaml"
  - name: "Per-environment data"
    path: "environments/%{server_facts.environment}.yaml"
  - name: "Per-OS data"
    path: "os/%{facts.os.family}.yaml"
  - name: "Common data"
    path: "common.yaml"

Put the most specific level first. With this hierarchy, nodes/web1.example.com.yaml can override one port for a single machine, os/Debian.yaml can set a package name, and common.yaml holds defaults for everyone.

flowchart TB
  K["lookup profile::webserver::port"] --> L1["nodes/web1.example.com.yaml"]
  L1 -->|not found| L2["environments/production.yaml"]
  L2 -->|not found| L3["os/Debian.yaml"]
  L3 -->|not found| L4["common.yaml"]
  L4 -->|found 8080| V["value 8080"]

The first level that contains the key wins.

Lookup types and merging

By default the first match wins (a first lookup). For arrays and hashes you sometimes want to combine values from several levels. Declare it in the module's own data or in a lookup_options entry:

YAML
lookup_options:
  profile::base::admin_users:
    merge: unique        # arrays: concatenate and de-duplicate
  profile::webserver::headers:
    merge: hash          # hashes: merge top-level keys
Merge Behavior
first (default) The first level that has the key wins
unique Concatenate arrays from all levels, remove duplicates
hash Combine hashes; the higher level wins on key clashes
deep Like hash, but recurses into nested hashes

Use merging for lists such as "admin users" or "firewall rules" where every level adds something.

Glue values with lookup()

Sometimes a profile needs data that is not a parameter of its own class, for example a database host shared by several profiles. Read it with lookup(), and give it a default or a type:

PUPPET
$db_host = lookup('site::database_host', String, 'first', 'db.example.com')

Use this sparingly. If the value is configuration of this profile, make it a parameter instead, because parameters are visible in the class signature and documented, while lookup() calls are hidden inside the body.

Verifying data

Two commands will save you hours:

Terminal
puppet lookup profile::webserver::port --node web1.example.com --explain
puppet lookup profile::webserver::vhosts --node web1.example.com --merge unique

--explain prints which hierarchy levels were checked and which file supplied the value. Run it every time you add a key.

Stand-ins: resolution in code

The JavaScript stand-ins below implement first and unique lookups over a mock hierarchy, so you can see the effect of level order and merge strategy.

JS Stand-in: first-wins hierarchy lookup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: merge strategies unique and hash

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In the hash merge, the first (most specific) level wins on X-Frame-Options, which matches Puppet's rule that higher levels override lower ones.

Secrets do not belong here

Plain YAML data is readable by anyone with repository access. For passwords and keys use an encryption backend such as hiera-eyaml or a secrets manager, see Security Baseline Project.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What Hiera key sets the parameter $port of class profile::webserver?

    Automatic lookup uses the key <class>::<parameter>.
  2. 2. In a hierarchy the node-specific file is listed first. What does that mean?

    Hiera returns the first match going top to bottom, so higher levels override.
  3. 3. Which merge strategy concatenates arrays from every level without duplicates?

    merge: unique collects the values from all levels and removes duplicates.
  4. 4. Which command shows which file supplied a value?

    --explain prints each level checked and where the value was found.

Summary

  • Class parameters are filled from Hiera under <class>::<param> when no explicit value is given.
  • The hierarchy in hiera.yaml ranks sources from most to least specific.
  • Use merge: unique or deep when levels should add up, lookup() for glue values.
  • Check results with puppet lookup --explain; typos fail silently to the default.
  • Keep secrets out of plain YAML.

Next: Node Classification: site.pp and ENCs