Interpolation functions

In Hiera data sources, you can use interpolation functions to insert non-variable values. These aren’t the same as Puppet functions; they’re only available in Hiera interpolation tokens.

There are five interpolation functions:

• lookup - looks up a key using Hiera, and interpolates the value into a string

• hiera - a synonym for lookup

• alias - looks up a key using Hiera, and uses the value as a replacement for the enclosing string. The result has the same data type as what the aliased key has - no conversion to string takes place if the value is exactly one alias

• literal - a way to write a literal percent sign (%) without accidentally interpolating something

• scope - an alternate way to interpolate a variable. Not generally useful

The lookup and hiera function

The lookup and hiera interpolation functions look up a key and return the resulting value. The result of the lookup must be a string; any other result causes an error. The hiera interpolation functions look up a key and return the resulting value. The result of the lookup must be a string; any other result causes an error.

This is useful in the Hiera data sources. If you need to use the same value for multiple keys, you can assign the literal value to one key, then call lookup to reuse the value elsewhere. You can edit the value in one place to change it everywhere it’s used.

For example, suppose your WordPress profile needs a database server, and you’re already configuring that hostname in data because the MySQL profile needs it. You can write:

# in location/pdx.yaml:
profile::mysql::public_hostname: db-server-01.pdx.example.com

# in location/bfs.yaml:
profile::mysql::public_hostname: db-server-06.belfast.example.com

# in common.yaml:
profile::wordpress::database_server: "%{lookup('profile::mysql::public_hostname')}"

The value of profile::wordpress::database_server is always the same as profile::mysql::public_hostname. Even though you wrote the WordPress parameter in the common.yaml data, it’s location-specific, as the value it references was set in your per-location data files.

The value referenced by the lookup function can contain another call to lookup; if you accidentally make an infinite loop, Hiera detects it and fails.

The alias function

The alias function lets you reuse Hash, Array, Boolean, Integer or String values.

When you interpolate alias in a string, Hiera replaces that entire string with the aliased value, using its original data type. For example:

original:
  - 'one'
  - 'two'
aliased: "%{alias('original')}"

A lookup of original and a lookup of aliased would both return the value ['one', 'two'].

When you use the alias function, its interpolation token must be the only text in that string. For example, the following would be an error:

aliased: "%{alias('original')} - 'three'"

The literal function

The literal interpolation function lets you escape a literal percent sign (%) in Hiera data, to avoid triggering interpolation where it isn’t wanted.

This is useful when dealing with Apache config files, for example, which might include text such as %{SERVER_NAME}. For example:

server_name_string: "%{literal('%')}{SERVER_NAME}"

The value of server_name_string is %{SERVER_NAME}, and Hiera does not attempt to interpolate a variable named SERVER_NAME.

The scope function

The scope interpolation function interpolates variables.

It works identically to variable interpolation. The functions argument is the name of a variable.

The following two values would be identical:

smtpserver: "mail.%{facts.domain}"
smtpserver: "mail.%{scope('facts.domain')}"

Using interpolation functions

To use an interpolation function to insert non-variable values, write:

1. The name of the function.

2. An opening parenthesis.

3. One argument to the function, enclosed in single or double quotation marks.

4. Use the opposite of what the enclosing string uses: if it uses single quotation marks, use double quotation marks.

5. A closing parenthesis.

For example:

wordpress::database_server: "%{lookup('instances::mysql::public_hostname')}"