puppet 8.6.0 → 8.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5e8f5c4d200e15de603485e2c1671afa9f7eb96b1a4decb477ffe9a0fc1376d
-  data.tar.gz: 58ee771b93b07d954d4441d8aa4d2766754a3fb3bb2ef19959ca9c7b80b83c80
+  metadata.gz: f89da386754e99d82576c50391217640d9d740f5aa41df6d0a091aafd35377b1
+  data.tar.gz: bfb37d9f9f20cc9607976f782622fb16ff6146cdef2642ad5cd46e55b31d7f40
 SHA512:
-  metadata.gz: ed5e88705b2031fac369d900a5c8da036a04ed694837eb750b24d48093be1b247e49f9584b924dae71400f3f0dac6ebf18e350509fdd5a6d325aeccba290e54f
-  data.tar.gz: bcc63456d3ee6d2c356fd26b80c1ffb173cbb045d909e2bd7cc2f4ac0275ad5b20b2333485fe3cb0a5f9007db35abe71aa7d9bca68eeaf87b2e0c0c8bcddc958
+  metadata.gz: 43d308cfe325c7985ff9d0a6310ee36a7d23f3c4080bd97445375d0d01ed59ed9cbed104efd5a40824b0cef277b2934976df028a827965612eac1c2a97659b9c
+  data.tar.gz: 87293cc2c9f04ec783873109a65d30162d02698ddc5947287a71a3662c53041e5b6eefbc166595fc3a014f18025311d3117ef93bd8cc07fa5f4c1d5da73082da

data/Gemfile

@@ -12,7 +12,9 @@ def location_for(place, fake_version = nil)
   end
 end
 
-# Make sure these gem requirements are in sync with the gempspec and ext/project_data.yaml
+# Make sure these gem requirements are in sync with the gempspec. Specifically,
+# the runtime_dependencies in puppet.gemspec match the runtime dependencies here
+# (like facter, semantic_puppet, and puppet-resource_api)
 
 gem "facter", *location_for(ENV['FACTER_LOCATION'] || ["~> 4.3"])
 gem "semantic_puppet", *location_for(ENV['SEMANTIC_PUPPET_LOCATION'] || ["~> 1.0"])
@@ -33,10 +35,13 @@ group(:features) do
   # requires native ldap headers/libs
   # gem 'ruby-ldap', '~> 0.9', require: false, platforms: [:ruby]
   gem 'puppetserver-ca', '~> 2.0', require: false
+  gem 'syslog', '~> 0.1.1', require: false, platforms: [:ruby]
+  gem 'CFPropertyList', ['>= 3.0.6', '< 4'], require: false
 end
 
 group(:test) do
-  gem "ffi", '1.15.5', require: false
+  # 1.16.0 - 1.16.2 are broken on Windows
+  gem 'ffi', '>= 1.15.5', '< 1.17.0', '!= 1.16.0', '!= 1.16.1', '!= 1.16.2', require: false
   gem "json-schema", "~> 2.0", require: false
   gem "rake", *location_for(ENV['RAKE_LOCATION'] || '~> 13.0')
   gem "rspec", "~> 3.1", require: false

data/Gemfile.lock

@@ -1,12 +1,12 @@
 PATH
   remote: .
   specs:
-    puppet (8.6.0)
-      CFPropertyList (~> 2.2)
+    puppet (8.8.1)
       concurrent-ruby (~> 1.0)
       deep_merge (~> 1.0)
       facter (>= 4.3.0, < 5)
-      fast_gettext (>= 2.1, < 3)
+      fast_gettext (>= 2.1, < 4)
+      getoptlong (~> 0.2.0)
       locale (~> 2.1)
       multi_json (~> 1.13)
       puppet-resource_api (~> 1.5)
@@ -16,17 +16,18 @@ PATH
 GEM
   remote: https://artifactory.delivery.puppetlabs.net/artifactory/api/gems/rubygems/
   specs:
-    CFPropertyList (2.3.6)
-    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 6.0)
-    apt_stage_artifacts (0.11.0)
-      docopt
+    CFPropertyList (3.0.7)
+      base64
+      nkf
+      rexml
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     artifactory (3.0.17)
     ast (2.4.2)
     base64 (0.2.0)
-    bigdecimal (3.1.7)
+    bigdecimal (3.1.8)
     coderay (1.1.3)
-    concurrent-ruby (1.2.3)
+    concurrent-ruby (1.3.3)
     crack (1.0.0)
       bigdecimal
       rexml
@@ -37,17 +38,20 @@ GEM
     digest-crc (0.6.5)
       rake (>= 12.0.0, < 14.0.0)
     docopt (0.6.1)
-    erubi (1.12.0)
-    facter (4.6.1)
+    erubi (1.13.0)
+    facter (4.8.0)
       hocon (~> 1.3)
-      thor (>= 1.0.1, < 2.0)
-    faraday (2.9.0)
+      thor (>= 1.0.1, < 1.3)
+    faraday (2.10.0)
       faraday-net_http (>= 2.0, < 3.2)
+      logger
     faraday-net_http (3.1.0)
       net-http
-    fast_gettext (2.3.0)
-    ffi (1.15.5)
+    fast_gettext (2.4.0)
+      prime
+    ffi (1.16.3)
     forwardable (1.3.3)
+    getoptlong (0.2.1)
     gettext (3.4.9)
       erubi
       locale (>= 2.0.5)
@@ -58,7 +62,7 @@ GEM
       fast_gettext (~> 2.1)
       gettext (~> 3.4)
       locale
-    google-apis-core (0.14.1)
+    google-apis-core (0.15.0)
       addressable (~> 2.5, >= 2.5.1)
       googleauth (~> 1.9)
       httpclient (>= 2.8.1, < 3.a)
@@ -66,22 +70,22 @@ GEM
       representable (~> 3.0)
       retriable (>= 2.0, < 4.a)
       rexml
-    google-apis-iamcredentials_v1 (0.20.0)
-      google-apis-core (>= 0.14.0, < 2.a)
-    google-apis-storage_v1 (0.37.0)
-      google-apis-core (>= 0.14.0, < 2.a)
+    google-apis-iamcredentials_v1 (0.21.0)
+      google-apis-core (>= 0.15.0, < 2.a)
+    google-apis-storage_v1 (0.40.0)
+      google-apis-core (>= 0.15.0, < 2.a)
     google-cloud-core (1.7.0)
       google-cloud-env (>= 1.0, < 3.a)
       google-cloud-errors (~> 1.0)
     google-cloud-env (2.1.1)
       faraday (>= 1.0, < 3.a)
     google-cloud-errors (1.4.0)
-    google-cloud-storage (1.49.0)
+    google-cloud-storage (1.52.0)
       addressable (~> 2.8)
       digest-crc (~> 0.4)
       google-apis-core (~> 0.13)
       google-apis-iamcredentials_v1 (~> 0.18)
-      google-apis-storage_v1 (~> 0.33)
+      google-apis-storage_v1 (~> 0.38)
       google-cloud-core (~> 1.6)
       googleauth (~> 1.9)
       mini_mime (~> 1.0)
@@ -93,22 +97,23 @@ GEM
       os (>= 0.9, < 2.0)
       signet (>= 0.16, < 2.a)
     hashdiff (1.1.0)
-    hiera-eyaml (3.4.0)
-      highline
-      optimist
-    highline (3.0.1)
+    hiera-eyaml (4.1.0)
+      highline (~> 2.1)
+      optimist (~> 3.1)
+    highline (2.1.0)
     hocon (1.4.0)
     hpricot (0.8.6)
     httpclient (2.8.3)
     json (2.7.2)
     json-schema (2.8.1)
       addressable (>= 2.4)
-    jwt (2.8.1)
+    jwt (2.8.2)
       base64
     language_server-protocol (3.17.0.3)
     locale (2.1.4)
-    memory_profiler (1.0.1)
-    method_source (1.0.0)
+    logger (1.6.0)
+    memory_profiler (1.0.2)
+    method_source (1.1.0)
     mini_mime (1.1.5)
     minitar (0.9)
     msgpack (1.7.2)
@@ -116,18 +121,18 @@ GEM
     mustache (1.1.1)
     net-http (0.4.1)
       uri
+    nkf (0.2.0)
     optimist (3.1.0)
     os (1.1.4)
-    packaging (0.118.0)
-      apt_stage_artifacts
+    packaging (0.120.0)
       artifactory (~> 3)
       csv (>= 3.1.5)
       google-cloud-storage
       googleauth
       rake (>= 12.3)
       release-metrics
-    parallel (1.24.0)
-    parser (3.3.0.5)
+    parallel (1.25.1)
+    parser (3.3.4.0)
       ast (~> 2.4.1)
       racc
     prime (0.1.2)
@@ -136,7 +141,7 @@ GEM
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    public_suffix (5.0.5)
+    public_suffix (6.0.1)
     puppet-resource_api (1.9.0)
       hocon (>= 1.0)
     puppetserver-ca (2.7.0)
@@ -146,7 +151,7 @@ GEM
     rake (13.2.1)
     rdiscount (2.2.7.3)
     rdoc (6.3.4.1)
-    regexp_parser (2.9.0)
+    regexp_parser (2.9.2)
     release-metrics (1.1.0)
       csv
       docopt
@@ -155,7 +160,8 @@ GEM
       trailblazer-option (>= 0.1.1, < 0.2.0)
       uber (< 0.2.0)
     retriable (3.1.2)
-    rexml (3.2.6)
+    rexml (3.3.2)
+      strscan
     ronn (0.7.3)
       hpricot (>= 0.8.2)
       mustache (>= 0.7.0)
@@ -166,47 +172,47 @@ GEM
       rspec-mocks (~> 3.13.0)
     rspec-core (3.13.0)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.0)
+    rspec-expectations (3.13.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-its (1.3.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
-    rspec-mocks (3.13.0)
+    rspec-mocks (3.13.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.63.0)
+    rubocop (1.65.0)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
+      regexp_parser (>= 2.4, < 3.0)
       rexml (>= 3.2.5, < 4.0)
       rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.2)
-      parser (>= 3.3.0.4)
-    rubocop-capybara (2.20.0)
-      rubocop (~> 1.41)
-    rubocop-factory_bot (2.25.1)
+    rubocop-ast (1.31.3)
+      parser (>= 3.3.1.0)
+    rubocop-capybara (2.21.0)
       rubocop (~> 1.41)
+    rubocop-factory_bot (2.26.1)
+      rubocop (~> 1.61)
     rubocop-i18n (3.0.0)
       rubocop (~> 1.0)
-    rubocop-performance (1.21.0)
+    rubocop-performance (1.21.1)
       rubocop (>= 1.48.1, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
-    rubocop-rspec (2.29.1)
+    rubocop-rspec (2.31.0)
       rubocop (~> 1.40)
       rubocop-capybara (~> 2.17)
       rubocop-factory_bot (~> 2.22)
       rubocop-rspec_rails (~> 2.28)
-    rubocop-rspec_rails (2.28.2)
-      rubocop (~> 1.40)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
     ruby-prof (1.7.0)
     ruby-progressbar (1.13.0)
     scanf (1.0.0)
@@ -217,14 +223,16 @@ GEM
       jwt (>= 1.5, < 3.0)
       multi_json (~> 1.10)
     singleton (0.2.0)
+    strscan (3.1.0)
+    syslog (0.1.2)
     text (1.3.1)
-    thor (1.3.1)
+    thor (1.2.2)
     trailblazer-option (0.1.2)
     uber (0.1.0)
     unicode-display_width (2.5.0)
     uri (0.13.0)
     vcr (6.2.0)
-    webmock (3.23.0)
+    webmock (3.23.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
@@ -235,9 +243,10 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  CFPropertyList (>= 3.0.6, < 4)
   diff-lcs (~> 1.3)
   facter (~> 4.3)
-  ffi (= 1.15.5)
+  ffi (>= 1.15.5, < 1.17.0, != 1.16.2, != 1.16.1, != 1.16.0)
   gettext-setup (~> 1.0)
   hiera-eyaml
   hocon (~> 1.0)
@@ -264,6 +273,7 @@ DEPENDENCIES
   rubocop-rspec (~> 2.0)
   ruby-prof (>= 0.16.0)
   semantic_puppet (~> 1.0)
+  syslog (~> 0.1.1)
   vcr (~> 6.1)
   webmock (~> 3.0)
   webrick (~> 1.7)

data/Rakefile

@@ -1,27 +1,9 @@
-# Rakefile for Puppet -*- ruby -*-
-RAKE_ROOT = File.dirname(__FILE__)
+# frozen_string_literal: true
 
-# We need access to the Puppet.version method
-$LOAD_PATH.unshift(File.expand_path("lib"))
-require 'puppet/version'
-
-$LOAD_PATH << File.join(RAKE_ROOT, 'tasks')
-
-begin
-  require 'rubygems'
-  require 'rubygems/package_task'
-rescue LoadError
-  # Users of older versions of Rake (0.8.7 for example) will not necessarily
-  # have rubygems installed, or the newer rubygems package_task for that
-  # matter.
-  require 'rake/packagetask'
-  require 'rake/gempackagetask'
-end
-
-require 'rake'
 require 'open3'
-
-Dir['tasks/**/*.rake'].each { |t| load t }
+require 'rake'
+require 'rubygems'
+require 'rubygems/package_task'
 
 if Rake.application.top_level_tasks.grep(/^(pl:|package:)/).any?
   begin
@@ -45,6 +27,47 @@ task :default do
   sh %{rake -T}
 end
 
+namespace :pl_ci do
+  desc 'Build puppet gems'
+  task :gem_build, [:gemspec] do |t, args|
+    args.with_defaults(gemspec: 'puppet.gemspec')
+    stdout, stderr, status = Open3.capture3(<<~END)
+      gem build #{args.gemspec} --platform x86-mingw32 && \
+      gem build #{args.gemspec} --platform x64-mingw32 && \
+      gem build #{args.gemspec} --platform universal-darwin && \
+      gem build #{args.gemspec}
+    END
+    if !status.exitstatus.zero?
+      puts "Error building #{args.gemspec}\n#{stdout} \n#{stderr}"
+      exit(1)
+    else
+      puts stdout
+    end
+  end
+
+  desc 'build the nightly puppet gems'
+  task :nightly_gem_build do
+    # this is taken from `rake package:nightly_gem`
+    extended_dot_version = %x{git describe --tags --dirty --abbrev=7}.chomp.tr('-', '.')
+
+    # we must create tempfile in the same directory as puppetg.gemspec, since
+    # it uses __dir__ to determine which files to include
+    require 'tempfile'
+    Tempfile.create('gemspec', __dir__) do |dst|
+      File.open('puppet.gemspec', 'r') do |src|
+        src.readlines.each do |line|
+          if line.match?(/version\s*=\s*['"][0-9.]+['"]/)
+            line = "spec.version = '#{extended_dot_version}'"
+          end
+          dst.puts line
+        end
+      end
+      dst.flush
+      Rake::Task['pl_ci:gem_build'].invoke(dst.path)
+    end
+  end
+end
+
 task :spec do
   ENV["LOG_SPEC_ORDER"] = "true"
   sh %{rspec #{ENV['TEST'] || ENV['TESTS'] || 'spec'}}

data/examples/hiera/README.md

@@ -1,91 +1,102 @@
-A working demo of Hiera with YAML and Puppet backends.
+A working demo of Hiera with YAML backend.
 ======================================================
 
 This demo consists of:
 
- * A NTP module that has defaults for pool.ntp.org servers
- * A common data module where module users can create override data in pp files
- * A YAML data source in etc/hieradb where users can override data in yaml files
- * A couple of users modules that just notify the fact that they are being included
- * In Hiera data files a key called _classes_ that decides what to include on a node
+- A **NTP** module that has defaults for *pool.ntp.org* servers
+- A **YAML** data source in the *data/* directory where users can override data in yaml files
+- A **Users** module that has a few manifests that simply notify that they are being included
+- In Hiera data files a key called **classes** that decides what to include on a node
 
 Below various usage scenarios can be tested using this module.
 
-The examples below assume you have Hiera already installed and that you have
-hiera-puppet cloned from github and running these commands in _hiera-puppet/example_ as cwd.
+The examples below assume you:
+- Have the puppet-agent already installed
+- You have this repository cloned from github
+- Are running these commands from within the *examples/hiera* directory as cwd.
 
 Module from forge with module defaults
 --------------------------------------
 
- * Move the _modules/data_ directory to _modules/data.bak_ to avoid overrides
-   used further in the example
- * Run puppet, creates _/etc/ntp.conf_ with ntp.org addresses
- * The _hiera\_include()_ function includes just _users::common_
-
-<pre>
-$ mv modules/data modules/data.bak
-$ puppet apply --config etc/puppet.conf site.pp
-notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/ensure: defined content as '{md5}7045121976147a932a66c7671939a9ad'
-notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
+- Comment out lines 6-8 of [data/common.yaml](data/common.yaml#L6-8) to avoid overrides used further in the example
+- Run a `puppet apply` to create a */tmp/ntp.conf* file containing the two *pool.ntp.org* addresses
+- The *users::common* class should also be present in your catalog
+
+```shell
+$ sed -i '6,8 s/^/#/' data/common.yaml
+$ puppet apply site.pp --hiera_config=hiera.yaml --modulepath=modules
+Notice: Compiled catalog for node.corp.com in environment production in 0.04 seconds
+Notice: Adding users::common
+Notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
+Notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/ensure: defined content as '{sha256}949c7247dbe0870258c921418cc8b270afcc57e1aa6f9d9933f306009ede60d0'
+Notice: Applied catalog in 0.02 seconds
 $ cat /tmp/ntp.conf
 server 1.pool.ntp.org
 server 2.pool.ntp.org
-</pre>
+```
 
 Site wide override data in _data::common_
 -----------------------------------------
 
- * Restore the _modules/data_ directory that has a class _data::common_ that declares site wide overrides
- * The _hiera_include()_ function includes just _users::common_
-
-<pre>
-$ mv modules/data.bak modules/data
-$ puppet apply --config etc/puppet.conf site.pp
-notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/content: content changed '{md5}7045121976147a932a66c7671939a9addc2' to '{md5}8f9039fe1989a278a0a8e1836acb8d23'
-notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
+- Remove the comments on lines 6-8 of [data/common.yaml](data/common.yaml#L6-8)
+- Run a `puppet apply` to update */tmp/ntp.conf* to contain the two *ntp.example.com* addresses
+- The *users::common* class should also be present in your catalog
+
+```shell
+$ sed -i '6,8 s/^#//' data/common.yaml
+$ puppet apply site.pp --hiera_config=hiera.yaml --modulepath=modules
+Notice: Compiled catalog for node.corp.com in environment production in 0.04 seconds
+Notice: Adding users::common
+Notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
+Notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/content: content changed '{sha256}949c7247dbe0870258c921418cc8b270afcc57e1aa6f9d9933f306009ede60d0' to '{sha256}28ced955a8ed9efd7514b2364fe378ba645ab947f26e8c0b4d84e8368f1257a0'
+Notice: Applied catalog in 0.02 seconds
 $ cat /tmp/ntp.conf
 server ntp1.example.com
 server ntp2.example.com
-</pre>
+```
 
 Fact driven overrides for location=dc1
 --------------------------------------
 
- * Set a fact location=dc1 that uses the YAML data in _etc/hieradb/dc1.yaml_ to override
- * Show that machines in dc2 would use site-wide defaults
- * The _hiera_include()_ function includes _users::common_ and _users::dc1_ as the data file for dc1 adds that
-
-<pre>
-$ FACTER_location=dc1 puppet apply --config etc/puppet.conf site.pp
-notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/content: content changed '{md5}8f9039fe1989a278a0a8e1836acb8d23' to '{md5}074d0e2ac727f6cb9afe3345d574b578'
-notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
-notice: /Stage[main]/Users::Dc1/Notify[Adding users::dc1]/message: defined 'message' as 'Adding users::dc1'
+- Override the location fact to `dc1` to demonstrate *data/dc1.yaml* overrides the *ntp::config::ntpservers* values in *data/common.yaml*
+- `dc1` nodes will
+  - have the *users::common* and *users::dc1* in their catalogs
+  - */tmp/ntp.conf* will contain the two *ntp.dc1.example.com* addresses
+- Show that the nodes in `dc2` would use the site-wide defaults
+
+```shell
+$ FACTER_location=dc1 puppet apply site.pp --hiera_config=hiera.yaml --modulepath=modules
+Notice: Compiled catalog for node.corp.com in environment production in 0.04 seconds
+Notice: Adding users::dc1
+Notice: /Stage[main]/Users::Dc1/Notify[Adding users::dc1]/message: defined 'message' as 'Adding users::dc1'
+Notice: Adding users::common
+Notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
+Notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/content: content changed '{sha256}28ced955a8ed9efd7514b2364fe378ba645ab947f26e8c0b4d84e8368f1257a0' to '{sha256}39227f1cf8d09623d2e66b6622af2e8db01ab26f77a5a2e6d6e058d0977f369b'
+Notice: Applied catalog in 0.02 seconds
 $ cat /tmp/ntp.conf
 server ntp1.dc1.example.com
 server ntp2.dc1.example.com
-</pre>
-
-Now simulate a machine in _dc2_, because there is no data for dc2 it uses the site wide defaults and
-does not include the _users::dc1_ class anymore
-
-<pre>
-$ FACTER_location=dc2 puppet apply --config etc/puppet.conf site.pp
-warning: Could not find class data::dc2 for nephilim.ml.org
-notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/content: content changed '{md5}074d0e2ac727f6cb9afe3345d574b578' to '{md5}8f9039fe1989a278a0a8e1836acb8d23'
-notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
+```
+
+Now simulate a machine in `dc2`, because there is no data for `dc2` it uses the site wide defaults and
+does not include the *users::dc1* class anymore
+
+```shell
+$ FACTER_location=dc2 puppet apply site.pp --hiera_config=hiera.yaml --modulepath=modules
+Notice: Compiled catalog for node.corp.com in environment production in 0.04 seconds
+Notice: Adding users::common
+Notice: /Stage[main]/Users::Common/Notify[Adding users::common]/message: defined 'message' as 'Adding users::common'
+Notice: /Stage[main]/Ntp::Config/File[/tmp/ntp.conf]/content: content changed '{sha256}39227f1cf8d09623d2e66b6622af2e8db01ab26f77a5a2e6d6e058d0977f369b' to '{sha256}28ced955a8ed9efd7514b2364fe378ba645ab947f26e8c0b4d84e8368f1257a0'
+Notice: Applied catalog in 0.02 seconds
 $ cat /tmp/ntp.conf
 server ntp1.example.com
 server ntp2.example.com
-</pre>
+```
 
-You could create override data in the following places for a machine in _location=dc2_, they will be searched in this order and the first one with data will match.
+You could create override data in the following places for a machine in *location=dc2*, they will be searched in this order and the first one with data will match.
 
- * file etc/hieradb/dc2.yaml
- * file etc/hieradb/common.yaml
- * class data::dc2
- * class data::production
- * class data::common
- * class ntp::config::data
- * class ntp::data
+- file data/dc2.yaml
+- file data/&lt;environment&gt;.yaml
+- file data/common.yaml
 
-In this example due to the presence of _common.yaml_ that declares _ntpservers_ the classes will never be searched, it will have precedence.
+In this example due to the presence of *common.yaml* that declares *ntpservers* the classes will never be searched, it will have precedence.

data/examples/hiera/data/common.yaml

@@ -0,0 +1,12 @@
+---
+classes:
+  - users::common
+  - ntp::config
+
+ntp::config::ntpservers:
+  - 'ntp1.example.com'
+  - 'ntp2.example.com'
+
+lookup_options:
+  classes:
+    merge: unique

data/examples/hiera/data/dc1.yaml

@@ -0,0 +1,6 @@
+---
+ntp::config::ntpservers:
+  - 'ntp1.dc1.example.com'
+  - 'ntp2.dc1.example.com'
+classes:
+  - users::dc1

data/examples/hiera/hiera.yaml

@@ -0,0 +1,15 @@
+---
+version: 5
+defaults:
+  datadir: data
+  data_hash: yaml_data
+
+hierarchy:
+  - name: 'Per Location'
+    path: "%{facts.location}.yaml"
+
+  - name: 'Per Environment'
+    path: "%{facts.environment}.yaml"
+
+  - name: 'Common Data'
+    path: 'common.yaml'

data/examples/hiera/modules/ntp/data/common.yaml

@@ -0,0 +1,4 @@
+---
+ntp::config::ntpservers:
+  - '1.pool.ntp.org'
+  - '2.pool.ntp.org'

data/examples/hiera/modules/ntp/hiera.yaml

@@ -0,0 +1,9 @@
+---
+version: 5
+defaults:
+  datadir: data
+  data_hash: yaml_data
+
+hierarchy:
+  - name: 'Common Data'
+    path: 'common.yaml'

data/examples/hiera/modules/ntp/manifests/config.pp

@@ -1,6 +1,18 @@
-# lookup ntpservers from hiera, or allow user of class to provide other value
-class ntp::config($ntpservers = hiera('ntpservers')) {
-  file{'/tmp/ntp.conf':
-    content => template('ntp/ntp.conf.erb')
+# @summary Manage /tmp/ntp.conf file
+#
+# Given an array of ntpservers, manage the /tmp/ntp.conf file
+#
+# @example
+#   include ntp::config
+#
+# @param ntpservers
+#   An array of ntpserver(s) that should be present in the conf file
+class ntp::config(
+  Array[String[1], 1] $ntpservers = undef,
+) {
+
+  file { '/tmp/ntp.conf':
+    content => epp('ntp/ntp.conf.epp')
   }
+
 }

data/examples/hiera/modules/ntp/templates/ntp.conf.epp

@@ -0,0 +1,3 @@
+<% $ntp::config::ntpservers.each |$server| { -%>
+server <%= $server %>
+<% } -%>

data/examples/hiera/modules/users/manifests/common.pp

@@ -1,4 +1,9 @@
-# notifies
+# @summary Notify to demonstrate users::common in catalog
+#
+# A common Class that all examples should include
+#
+# @example
+#   include users::common
 class users::common {
-  notify{'Adding users::common': }
+  notify { 'Adding users::common': }
 }