Deciding to use either automatic class parameter lookup or the lookup function

For the third consideration in the previous best practice, there's another decision to make around how data arrives into the profile class from your business data hierarchy:

• In these profiles, we have used the automatic class parameter lookup (https://puppet.com/docs/puppet/5.3/hiera_automatic.html) to request data from our business data hierarchy. Using the interface of the profile's parameters is a reliable and well-known way to look for the profile's configuration settings, and allows better integration with external tools, such as Puppet Strings (https://github.com/puppetlabs/puppet-strings), the YARD-based (https://yardoc.org) documentation extraction and presentation tool.
• When we wrote the code for the profile class, we also could have omitted all the parameters and instead used the lookup function:

$jenkins_port = lookup('profile::jenkins::jenkins_port', {value_type => String, default_value => '9091'})
$java_dist    = lookup('profile::jenkins::java_dist',    {value_type => String, default_value => 'jdk'})
$java_version = lookup('profile::jenkins::java_version', {value_type => String, default_value => 'latest'})
# ...

This approach is an alternative if you aren't comfortable with the automagic nature of an automatic class parameter lookup. I have certainly found it more comfortable to make an explicit data lookup, and then deal with the returned value there and then in the more robust Puppet DSL. I found earlier versions of Hiera notoriously cryptic when trying to track down bugs (https://puppet.com/blog/debugging-hiera), and this approach really helps. You can check data types and make further validations directly. By having the full lookup key written out in the profile, we can globally grep for it across our entire Puppet DSL codebase, and thus make a definitive link between Puppet manifests and the business data servicing them:

grep -nr 'profile::web::apache::vhost*' .

You can then use the new Puppet lookup (https://puppet.com/docs/puppet/5.3/man/lookup.html) command (previously, the hiera command line invocation). Since it's the CLI equivalent of the lookup function, you can be sure during debugging that you are getting exactly the business data value you require:

Puppet lookup ' profile::web::apache::vhost *' .

Actually, I also have certain issues with YAML as a language itself (see, for example, https://arp242.net/weblog/yaml_probably_not_so_great_after_all.html), and being able to rely on the robustness of the more explicit Puppet DSL compensates for what I feel are YAML's native weaknesses during debugging.

Take a close look at this blog post: https://puppet.com/blog/debugging-hiera-redux, which is an update to debugging Hiera with the latest commands, and of course ensure you are at the very least using a YAML parser.

Also, bear in mind that Hiera really does have its limitations, especially for larger and more diverse infrastructures (https://www.craigdunn.org/2015/09/solving-real-world-problems-with-jerakia).

So, moving on, let's now look at the higher level of abstraction in the pattern: roles.