puppet 4.9.4 → 4.10.0

data/spec/unit/face/certificate_spec.rb

@@ -9,6 +9,13 @@ describe Puppet::Face[:certificate, '0.0.1'] do
 
   let(:ca) { Puppet::SSL::CertificateAuthority.instance }
 
+  # different UTF-8 widths
+  # 1-byte A
+  # 2-byte ۿ - http://www.fileformat.info/info/unicode/char/06ff/index.htm - 0xDB 0xBF / 219 191
+  # 3-byte ᚠ - http://www.fileformat.info/info/unicode/char/16A0/index.htm - 0xE1 0x9A 0xA0 / 225 154 160
+  # 4-byte ܎ - http://www.fileformat.info/info/unicode/char/2070E/index.htm - 0xF0 0xA0 0x9C 0x8E / 240 160 156 142
+  let (:mixed_utf8) { "A\u06FF\u16A0\u{2070E}" } # Aۿᚠ܎
+
   before :each do
     Puppet[:confdir] = tmpdir('conf')
     Puppet::SSL::CertificateAuthority.stubs(:ca?).returns true
@@ -84,9 +91,10 @@ describe Puppet::Face[:certificate, '0.0.1'] do
       it "should add the provided dns_alt_names if they are specified" do
         Puppet[:dns_alt_names] = 'from,the,config'
 
-        subject.generate(hostname, options.merge(:dns_alt_names => 'explicit,alt,names'))
+        subject.generate(hostname, options.merge(:dns_alt_names => "explicit,alt,#{mixed_utf8}"))
 
-        expected = %W[DNS:explicit DNS:alt DNS:names DNS:#{hostname}]
+        # CSRs will return subject_alt_names as BINARY strings
+        expected = %W[DNS:explicit DNS:alt DNS:#{mixed_utf8.force_encoding(Encoding::BINARY)} DNS:#{hostname}]
 
         expect(csr.subject_alt_names).to match_array(expected)
       end

data/spec/unit/functions/dig_spec.rb

@@ -50,7 +50,7 @@ describe 'the dig function' do
   end
 
   it 'errors if not given a non Collection as the starting point' do
-    expect { compile_to_catalog(<<-SOURCE)}.to raise_error(/'dig' parameter 'data' expects a Collection value, got String/)
+    expect { compile_to_catalog(<<-SOURCE)}.to raise_error(/'dig' parameter 'data' expects a value of type Undef or Collection, got String/)
     "hello".dig(1, yes, 2)
     SOURCE
   end

data/spec/unit/functions/hiera_spec.rb

@@ -66,6 +66,8 @@ describe 'when calling' do
           name: postgres
           uid: 500
           gid: 500
+          groups:
+            db: 520
         b:
           b1: first b1
           b2: first b2
@@ -74,6 +76,19 @@ describe 'when calling' do
           - mod::bar
           - mod::baz
         empty_array: []
+        nested_array:
+          first:
+            - 10
+            - 11
+          second:
+            - 21
+            - 22
+        dotted.key:
+          a: dotted.key a
+          b: dotted.key b
+        dotted.array:
+          - a
+          - b
         YAML
       'second.yaml' => <<-YAML.unindent,
         ---
@@ -193,6 +208,14 @@ describe 'when calling' do
       expect(func('a')).to eql('first a')
     end
 
+    it 'should allow lookup with quoted dotted key' do
+      expect(func("'dotted.key'")).to eql({'a' => 'dotted.key a', 'b' => 'dotted.key b'})
+    end
+
+    it 'should allow lookup with dotted key' do
+      expect(func('database_user.groups.db')).to eql(520)
+    end
+
     it 'should not find data in module' do
       expect(func('mod::c', 'default mod::c')).to eql('default mod::c')
     end
@@ -292,6 +315,14 @@ describe 'when calling' do
       expect(func('fbb', {'fbb' => 'foo_result'})).to eql(%w[mod::foo mod::bar mod::baz])
     end
 
+    it 'should allow lookup with quoted dotted key' do
+      expect(func("'dotted.array'")).to eql(['a', 'b'])
+    end
+
+    it 'should fail lookup with dotted key' do
+      expect{ func('nested_array.0.first') }.to raise_error(/Resolution type :array is illegal when accessing values using dotted keys. Offending key was 'nested_array.0.first'/)
+    end
+
     it 'should use default block' do
       expect(func('foo') { |k| ['key', k] }).to eql(%w[key foo])
     end
@@ -313,7 +344,15 @@ describe 'when calling' do
     end
 
     it 'should lookup and return a hash' do
-      expect(func('database_user')).to eql({ 'name' => 'postgres', 'uid' => 500, 'gid' => 500})
+      expect(func('database_user')).to eql({ 'name' => 'postgres', 'uid' => 500, 'gid' => 500, 'groups' => { 'db' => 520 }})
+    end
+
+    it 'should allow lookup with quoted dotted key' do
+      expect(func("'dotted.key'")).to eql({'a' => 'dotted.key a', 'b' => 'dotted.key b'})
+    end
+
+    it 'should fail lookup with dotted key' do
+      expect{ func('database_user.groups') }.to raise_error(/Resolution type :hash is illegal when accessing values using dotted keys. Offending key was 'database_user.groups'/)
     end
 
     it 'should log deprecation errors' do

data/spec/unit/functions/lookup_fixture_spec.rb

@@ -383,7 +383,7 @@ describe 'The lookup function' do
         expect { compiler.compile }.to raise_error(Puppet::ParseError, /did not find a value for the name 'bad_data::b'/)
       end
       warnings = logs.select { |log| log.level == :warning }.map { |log| log.message }
-      expect(warnings).to include("Module 'bad_data': deprecated API function \"bad_data::data\" must use keys qualified with the name of the module")
+      expect(warnings).to include("Module 'bad_data': Value returned from deprecated API function 'bad_data::data' must use keys qualified with the name of the module")
     end
 
     it 'will succeed finding prefixed keys even when a key in the function provided module data is not prefixed' do
@@ -397,7 +397,7 @@ describe 'The lookup function' do
         expect(resources).to include('module_c')
       end
       warnings = logs.select { |log| log.level == :warning }.map { |log| log.message }
-      expect(warnings).to include("Module 'bad_data': deprecated API function \"bad_data::data\" must use keys qualified with the name of the module")
+      expect(warnings).to include("Module 'bad_data': Value returned from deprecated API function 'bad_data::data' must use keys qualified with the name of the module")
     end
 
     it 'will resolve global, environment, and module correctly' do
@@ -429,7 +429,7 @@ describe 'The lookup function' do
         compiler.compile
       end
       warnings = logs.select { |log| log.level == :warning }.map { |log| log.message }
-      expect(warnings).to include("Module 'bad_data': deprecated API function \"bad_data::data\" must use keys qualified with the name of the module")
+      expect(warnings).to include("Module 'bad_data': Value returned from deprecated API function 'bad_data::data' must use keys qualified with the name of the module")
     end
 
     it 'a warning will be logged when key in the hiera provided module data is not prefixed' do
@@ -439,7 +439,7 @@ describe 'The lookup function' do
         compiler.compile
       end
       warnings = logs.select { |log| log.level == :warning }.map { |log| log.message }
-      expect(warnings).to include("Module 'hieraprovider': Hierarchy entry \"two paths\" must use keys qualified with the name of the module")
+      expect(warnings).to include("Module 'hieraprovider': Value returned from data_hash function 'json_data', when using location '#{environmentpath}/production/modules/hieraprovider/data/first.json', must use keys qualified with the name of the module")
     end
   end
 
@@ -514,7 +514,7 @@ describe 'The lookup function' do
         end
         expect(lookup_invocation.explainer.explain).to include(<<-EOS.unindent('  '))
           Module "abc" Data Provider (hiera configuration version 5)
-            deprecated API function "abc::data"
+            Deprecated API function "abc::data"
               No such key: "abc::x"
         EOS
       end
@@ -530,13 +530,13 @@ describe 'The lookup function' do
               Global Data Provider (hiera configuration version 5)
                 No such key: "abc::e"
               Environment Data Provider (hiera configuration version 5)
-                deprecated API function "environment::data"
+                Deprecated API function "environment::data"
                   Found key: "abc::e" value: {
                     "k1" => "env_e1",
                     "k3" => "env_e3"
                   }
               Module "abc" Data Provider (hiera configuration version 5)
-                deprecated API function "abc::data"
+                Deprecated API function "abc::data"
                   Found key: "abc::e" value: {
                     "k1" => "module_e1",
                     "k2" => "module_e2"
@@ -576,7 +576,7 @@ describe 'The lookup function' do
               Global Data Provider (hiera configuration version 5)
                 No such key: "hieraprovider::test::not_found"
               Environment Data Provider (hiera configuration version 5)
-                deprecated API function "environment::data"
+                Deprecated API function "environment::data"
                   No such key: "hieraprovider::test::not_found"
               Module "hieraprovider" Data Provider (hiera configuration version 4)
                 Using configuration "#{environmentpath}/production/modules/hieraprovider/hiera.yaml"
@@ -636,7 +636,7 @@ describe 'The lookup function' do
                     :branches => [
                       {
                         :type => :data_provider,
-                        :name => 'deprecated API function "environment::data"',
+                        :name => 'Deprecated API function "environment::data"',
                         :key => 'abc::e',
                         :value => { 'k1' => 'env_e1', 'k3' => 'env_e3' },
                         :event => :found
@@ -650,7 +650,7 @@ describe 'The lookup function' do
                     :branches => [
                       {
                         :type => :data_provider,
-                        :name => 'deprecated API function "abc::data"',
+                        :name => 'Deprecated API function "abc::data"',
                         :key => 'abc::e',
                         :event => :found,
                         :value => {

data/spec/unit/functions/lookup_spec.rb

@@ -9,205 +9,429 @@ describe "The lookup function" do
   include PuppetSpec::Compiler
   include PuppetSpec::Files
 
-  context 'with an environment' do
-    let(:env_name) { 'spec' }
-    let(:code_dir_files) { {} }
-    let(:code_dir) { tmpdir('code') }
-    let(:ruby_dir) { tmpdir('ruby') }
-    let(:env_modules) { {} }
-    let(:env_hiera_yaml) do
-      <<-YAML.unindent
-        ---
-        version: 5
-        hierarchy:
-          - name: "Common"
-            data_hash: yaml_data
-            path: "common.yaml"
-        YAML
-    end
+  let(:env_name) { 'spec' }
+  let(:code_dir_files) { {} }
+  let(:code_dir) { tmpdir('code') }
+  let(:ruby_dir) { tmpdir('ruby') }
+  let(:env_modules) { {} }
+  let(:env_hiera_yaml) do
+    <<-YAML.unindent
+      ---
+      version: 5
+      hierarchy:
+        - name: "Common"
+          data_hash: yaml_data
+          path: "common.yaml"
+      YAML
+  end
 
-    let(:env_data) do
-      {
-        'common.yaml' => <<-YAML.unindent
-          ---
-          a: value a (from environment)
-          c:
-            c_b: value c_b (from environment)
-          mod_a::a: value mod_a::a (from environment)
-          mod_a::hash_a:
-            a: value mod_a::hash_a.a (from environment)
-          mod_a::hash_b:
-            a: value mod_a::hash_b.a (from environment)
-          hash_b:
-            hash_ba:
-              bab: value hash_b.hash_ba.bab (from environment)
-          hash_c:
-            hash_ca:
-              caa: value hash_c.hash_ca.caa (from environment)
-          lookup_options:
-            mod_a::hash_b:
-              merge: hash
-            hash_c:
-              merge: hash
-          YAML
-      }
-    end
+  let(:env_data) { {} }
 
-    let(:environment_files) do
-      {
-        env_name => {
-          'modules' => env_modules,
-          'hiera.yaml' => env_hiera_yaml,
-          'data' => env_data
-        }
+  let(:environment_files) do
+    {
+      env_name => {
+        'modules' => env_modules,
+        'hiera.yaml' => env_hiera_yaml,
+        'data' => env_data
       }
-    end
+    }
+  end
 
-    let(:ruby_dir_files) do
-      {
-        'hiera' => {
-          'backend' => {
-            'custom_backend.rb' => <<-RUBY.unindent,
-              class Hiera::Backend::Custom_backend
-                def lookup(key, scope, order_override, resolution_type, context)
-                  case key
-                  when 'hash_c'
-                    { 'hash_ca' => { 'cad' => 'value hash_c.hash_ca.cad (from global custom)' }}
-                  when 'hash'
-                    { 'array' => [ 'x5,x6' ] }
-                  when 'array'
-                    [ 'x5,x6' ]
-                  when 'datasources'
-                    Hiera::Backend.datasources(scope, order_override) { |source| source }
-                  else
-                    throw :no_such_key
-                  end
-                end
-              end
-              RUBY
-            'other_backend.rb' => <<-RUBY.unindent,
-              class Hiera::Backend::Other_backend
-                def lookup(key, scope, order_override, resolution_type, context)
-                  value = Hiera::Config[:other][key.to_sym]
-                  throw :no_such_key if value.nil?
-                  value
-                end
-              end
-              RUBY
-          }
-        }
-      }
-    end
+  let(:ruby_dir_files) { {} }
+
+  let(:logs) { [] }
+  let(:scope_additions ) { {} }
+  let(:notices) { logs.select { |log| log.level == :notice }.map { |log| log.message } }
+  let(:warnings) { logs.select { |log| log.level == :warning }.map { |log| log.message } }
+  let(:debugs) { logs.select { |log| log.level == :debug }.map { |log| log.message } }
+  let(:env) { Puppet::Node::Environment.create(env_name.to_sym, [File.join(populated_env_dir, env_name, 'modules')]) }
+  let(:environments) { Puppet::Environments::Directories.new(populated_env_dir, []) }
+  let(:node) { Puppet::Node.new('test_lookup', :environment => env) }
+  let(:compiler) { Puppet::Parser::Compiler.new(node) }
+  let(:lookup_func) { Puppet.lookup(:loaders).puppet_system_loader.load(:function, 'lookup') }
+  let(:invocation_with_explain) { Puppet::Pops::Lookup::Invocation.new(compiler.topscope, {}, {}, true) }
+  let(:explanation) { invocation_with_explain.explainer.explain }
+
+  let(:populated_code_dir) do
+    dir_contained_in(code_dir, code_dir_files)
+    code_dir
+  end
 
-    let(:logs) { [] }
-    let(:scope_additions ) { {} }
-    let(:notices) { logs.select { |log| log.level == :notice }.map { |log| log.message } }
-    let(:warnings) { logs.select { |log| log.level == :warning }.map { |log| log.message } }
-    let(:debugs) { logs.select { |log| log.level == :debug }.map { |log| log.message } }
-    let(:env) { Puppet::Node::Environment.create(env_name.to_sym, [File.join(populated_env_dir, env_name, 'modules')]) }
-    let(:environments) { Puppet::Environments::Directories.new(populated_env_dir, []) }
-    let(:node) { Puppet::Node.new('test_lookup', :environment => env) }
-    let(:compiler) { Puppet::Parser::Compiler.new(node) }
-    let(:lookup_func) { Puppet.lookup(:loaders).puppet_system_loader.load(:function, 'lookup') }
-    let(:defaults) {
-      {
-        'mod_a::xd' => 'value mod_a::xd (from default)',
-        'mod_a::xd_found' => 'value mod_a::xd_found (from default)',
-        'scope_xd' => 'value scope_xd (from default)'
-      }}
-    let(:overrides) {
-      {
-        'mod_a::xo' => 'value mod_a::xo (from override)',
-        'scope_xo' => 'value scope_xo (from override)'
-      }}
-    let(:invocation_with_explain) { Puppet::Pops::Lookup::Invocation.new(compiler.topscope, {}, {}, true) }
-    let(:explanation) { invocation_with_explain.explainer.explain }
-
-    let(:populated_code_dir) do
-      dir_contained_in(code_dir, code_dir_files)
-      code_dir
-    end
+  let(:populated_ruby_dir) do
+    dir_contained_in(ruby_dir, ruby_dir_files)
+    ruby_dir
+  end
 
-    let(:populated_ruby_dir) do
-      dir_contained_in(ruby_dir, ruby_dir_files)
-      ruby_dir
-    end
+  let(:env_dir) do
+    d = File.join(populated_code_dir, 'environments')
+    Dir.mkdir(d)
+    d
+  end
+
+  let(:populated_env_dir) do
+    dir_contained_in(env_dir, environment_files)
+    env_dir
+  end
 
-    let(:env_dir) do
-      d = File.join(populated_code_dir, 'environments')
-      Dir.mkdir(d)
-      d
+  before(:each) do
+    Puppet.settings[:codedir] = code_dir
+    Puppet.push_context(:environments => environments, :current_environment => env)
+  end
+
+  after(:each) do
+    Puppet.pop_context
+    if Object.const_defined?(:Hiera)
+      Hiera.send(:remove_instance_variable, :@config) if Hiera.instance_variable_defined?(:@config)
+      Hiera.send(:remove_instance_variable, :@logger) if Hiera.instance_variable_defined?(:@logger)
+      if Hiera.const_defined?(:Config)
+        Hiera::Config.send(:remove_instance_variable, :@config) if Hiera::Config.instance_variable_defined?(:@config)
+      end
+      if Hiera.const_defined?(:Backend) && Hiera::Backend.respond_to?(:clear!)
+        Hiera::Backend.clear!
+      end
     end
+  end
 
-    let(:populated_env_dir) do
-      dir_contained_in(env_dir, environment_files)
-      env_dir
+  def collect_notices(code, explain = false, &block)
+    Puppet[:code] = code
+    Puppet::Util::Log.with_destination(Puppet::Test::LogCollector.new(logs)) do
+      scope = compiler.topscope
+      scope['environment'] = env_name
+      scope['domain'] = 'example.com'
+      scope_additions.each_pair { |k, v| scope[k] = v }
+      if explain
+        begin
+          invocation_with_explain.lookup('dummy', nil) do
+            if block_given?
+              compiler.compile { |catalog| block.call(compiler.topscope); catalog }
+            else
+              compiler.compile
+            end
+          end
+        rescue RuntimeError => e
+          invocation_with_explain.report_text { e.message }
+        end
+      else
+        if block_given?
+          compiler.compile { |catalog| block.call(compiler.topscope); catalog }
+        else
+          compiler.compile
+        end
+      end
     end
+    nil
+  end
 
-    before(:each) do
-      Puppet.settings[:codedir] = code_dir
-      Puppet.push_context(:environments => environments, :current_environment => env)
+  def lookup(key, options = {}, explain = false)
+    nc_opts = options.empty? ? '' : ", #{Puppet::Pops::Types::TypeFormatter.string(options)}"
+    keys = key.is_a?(Array) ? key : [key]
+    collect_notices(keys.map { |k| "notice(String(lookup('#{k}'#{nc_opts}), '%p'))" }.join("\n"), explain)
+    if explain
+      explanation
+    else
+      result = notices.map { |n| Puppet::Pops::Types::TypeParser.singleton.parse_literal(n) }
+      key.is_a?(Array) ? result : result[0]
     end
+  end
+
+  def explain(key, options = {})
+    lookup(key, options, true)[1]
+    explanation
+  end
+
+  context 'with faulty hiera.yaml configuration' do
+    context 'in global layer' do
+      let(:global_data) do
+        {
+          'common.yaml' => <<-YAML.unindent
+            a: value a (from global)
+            YAML
+        }
+      end
+
+      let(:code_dir_files) do
+        {
+          'hiera.yaml' => hiera_yaml,
+          'data' => global_data
+        }
+      end
+
+      before(:each) do
+        # Need to set here since spec_helper defines these settings in its "before each"
+        Puppet.settings[:codedir] = populated_code_dir
+        Puppet.settings[:hiera_config] = File.join(code_dir, 'hiera.yaml')
+      end
 
-    after(:each) do
-      Puppet.pop_context
-      if Object.const_defined?(:Hiera)
-        Hiera.send(:remove_instance_variable, :@config) if Hiera.instance_variable_defined?(:@config)
-        Hiera.send(:remove_instance_variable, :@logger) if Hiera.instance_variable_defined?(:@logger)
-        if Hiera.const_defined?(:Config)
-          Hiera::Config.send(:remove_instance_variable, :@config) if Hiera::Config.instance_variable_defined?(:@config)
+      context 'using a not yet supported hiera version' do
+        let(:hiera_yaml) { <<-YAML.unindent }
+          version: 6
+          YAML
+
+        it 'fails and reports error' do
+          expect { lookup('a') }.to raise_error("This runtime does not support hiera.yaml version 6 in #{code_dir}/hiera.yaml")
         end
-        if Hiera.const_defined?(:Backend) && Hiera::Backend.respond_to?(:clear!)
-          Hiera::Backend.clear!
+      end
+
+      context 'with multiply defined backend using hiera version 3' do
+        let(:hiera_yaml) { <<-YAML.unindent }
+          :version: 3
+          :backends:
+            - yaml
+            - json
+            - yaml
+          YAML
+
+        it 'fails and reports error' do
+          expect { lookup('a') }.to raise_error(
+            "Backend 'yaml' is defined more than once. First defined at line 3 at #{code_dir}/hiera.yaml:5")
         end
       end
-    end
 
-    def collect_notices(code, explain = false, &block)
-      Puppet[:code] = code
-      Puppet::Util::Log.with_destination(Puppet::Test::LogCollector.new(logs)) do
-        scope = compiler.topscope
-        scope['environment'] = env_name
-        scope['domain'] = 'example.com'
-        scope_additions.each_pair { |k, v| scope[k] = v }
-        if explain
-          begin
-            invocation_with_explain.lookup('dummy', nil) do
-              if block_given?
-                compiler.compile { |catalog| block.call(compiler.topscope); catalog }
-              else
-                compiler.compile
-              end
-            end
-          rescue RuntimeError => e
-            invocation_with_explain.report_text { e.message }
+      context 'using hiera version 4' do
+        let(:hiera_yaml) { <<-YAML.unindent }
+          version: 4
+          YAML
+
+        it 'fails and reports error' do
+          expect { lookup('a') }.to raise_error(
+            "hiera.yaml version 4 cannot be used in the global layer in #{code_dir}/hiera.yaml")
+        end
+      end
+
+      context 'using hiera version 5' do
+        context 'with multiply defined hierarchy' do
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common
+                path: common.yaml
+              - name: Other
+                path: other.yaml
+              - name: Common
+                path: common.yaml
+            YAML
+
+          it 'fails and reports error' do
+            expect { lookup('a') }.to raise_error(
+              "Hierarchy name 'Common' defined more than once. First defined at line 3 at #{code_dir}/hiera.yaml:7")
           end
-        else
-          if block_given?
-            compiler.compile { |catalog| block.call(compiler.topscope); catalog }
-          else
-            compiler.compile
+        end
+
+        context 'with hiera3_backend that is provided as data_hash function' do
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common
+                hiera3_backend: hocon
+                path: common.conf
+            YAML
+
+          it 'fails and reports error' do
+            expect { lookup('a') }.to raise_error(
+              "Use \"data_hash: hocon_data\" instead of \"hiera3_backend: hocon\" at #{code_dir}/hiera.yaml:4")
+          end
+        end
+
+        context 'with no data provider function defined' do
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            defaults:
+              datadir: data
+            hierarchy:
+              - name: Common
+                path: common.txt
+            YAML
+
+          it 'fails and reports error' do
+            expect { lookup('a') }.to raise_error(
+              "One of data_hash, lookup_key, data_dig, or hiera3_backend must be defined in hierarchy 'Common' in #{code_dir}/hiera.yaml")
+          end
+        end
+
+        context 'with multiple data providers in defaults' do
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            defaults:
+              data_hash: yaml_data
+              lookup_key: eyaml_lookup_key
+              datadir: data
+            hierarchy:
+              - name: Common
+                path: common.txt
+            YAML
+
+          it 'fails and reports error' do
+            expect { lookup('a') }.to raise_error(
+              "Only one of data_hash, lookup_key, data_dig, or hiera3_backend can be defined in defaults in #{code_dir}/hiera.yaml")
+          end
+        end
+
+        context 'with non existing data provider function' do
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common
+                data_hash: nonesuch_txt_data
+                path: common.yaml
+            YAML
+
+          it 'fails and reports error' do
+            Puppet[:strict] = :error
+            expect { lookup('a') }.to raise_error(
+              "Unable to find 'data_hash' function named 'nonesuch_txt_data' in #{code_dir}/hiera.yaml")
+          end
+        end
+
+        context 'with a declared default_hierarchy' do
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common
+                path: common.yaml
+            default_hierarchy:
+              - name: Defaults
+                path: defaults.yaml
+            YAML
+
+          it 'fails and reports error' do
+            Puppet[:strict] = :error
+            expect { lookup('a') }.to raise_error(
+              "'default_hierarchy' is only allowed in the module layer at #{code_dir}/hiera.yaml:5")
+          end
+        end
+
+        context 'with missing variables' do
+          let(:scope_additions) { { 'fqdn' => 'test.example.com' } }
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common # don't report this line %{::nonesuch}
+                path: "%{::fqdn}/%{::nonesuch}/data.yaml"
+            YAML
+
+          it 'fails and reports errors when strict == error' do
+            Puppet[:strict] = :error
+            expect { lookup('a') }.to raise_error("Undefined variable '::nonesuch' at #{code_dir}/hiera.yaml:4")
+          end
+        end
+
+        context 'using interpolation functions' do
+          let(:hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common # don't report this line %{::nonesuch}
+                path: "%{lookup('fqdn')}/data.yaml"
+            YAML
+
+          it 'fails and reports errors when strict == error' do
+            Puppet[:strict] = :error
+            expect { lookup('a') }.to raise_error("Interpolation using method syntax is not allowed in this context in #{code_dir}/hiera.yaml")
           end
         end
       end
-      nil
     end
 
-    def lookup(key, options = {}, explain = false)
-      nc_opts = options.empty? ? '' : ", #{Puppet::Pops::Types::TypeFormatter.string(options)}"
-      keys = key.is_a?(Array) ? key : [key]
-      collect_notices(keys.map { |k| "notice(String(lookup('#{k}'#{nc_opts}), '%p'))" }.join("\n"), explain)
-      if explain
-        explanation
-      else
-        result = notices.map { |n| Puppet::Pops::Types::TypeParser.singleton.parse_literal(n) }
-        key.is_a?(Array) ? result : result[0]
+    context 'in environment layer' do
+      context 'using hiera version 4' do
+        context 'with an unknown backend' do
+          let(:env_hiera_yaml) { <<-YAML.unindent }
+            version: 4
+            hierarchy:
+              - name: Common
+                backend: nonesuch
+                path: common.yaml
+            YAML
+
+          it 'fails and reports error' do
+            expect { lookup('a') }.to raise_error(
+              "No data provider is registered for backend 'nonesuch' at #{env_dir}/spec/hiera.yaml:4")
+          end
+        end
+
+        context 'with multiply defined hierarchy' do
+          let(:env_hiera_yaml) { <<-YAML.unindent }
+            version: 4
+            hierarchy:
+              - name: Common
+                backend: yaml
+                path: common.yaml
+              - name: Other
+                backend: yaml
+                path: other.yaml
+              - name: Common
+                backend: yaml
+                path: common.yaml
+            YAML
+
+          it 'fails and reports error' do
+            expect { lookup('a') }.to raise_error(
+              "Hierarchy name 'Common' defined more than once. First defined at line 3 at #{env_dir}/spec/hiera.yaml:9")
+          end
+        end
+      end
+
+      context 'using hiera version 5' do
+        context 'with a hiera3_backend declaration' do
+          let(:env_hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common
+                hiera3_backend: something
+            YAML
+
+          it 'fails and reports error' do
+            expect { lookup('a') }.to raise_error(
+              "'hiera3_backend' is only allowed in the global layer at #{env_dir}/spec/hiera.yaml:4")
+          end
+        end
+
+        context 'with a declared default_hierarchy' do
+          let(:env_hiera_yaml) { <<-YAML.unindent }
+            version: 5
+            hierarchy:
+              - name: Common
+                path: common.yaml
+            default_hierarchy:
+              - name: Defaults
+                path: defaults.yaml
+            YAML
+
+          it 'fails and reports error' do
+            Puppet[:strict] = :error
+            expect { lookup('a') }.to raise_error(
+              "'default_hierarchy' is only allowed in the module layer at #{env_dir}/spec/hiera.yaml:5")
+          end
+        end
       end
     end
+  end
 
-    def explain(key, options = {})
-      lookup(key, options, true)[1]
-      explanation
+  context 'with an environment' do
+    let(:env_data) do
+      {
+        'common.yaml' => <<-YAML.unindent
+        ---
+        a: value a (from environment)
+        c:
+          c_b: value c_b (from environment)
+        mod_a::a: value mod_a::a (from environment)
+        mod_a::hash_a:
+          a: value mod_a::hash_a.a (from environment)
+        mod_a::hash_b:
+          a: value mod_a::hash_b.a (from environment)
+        hash_b:
+          hash_ba:
+            bab: value hash_b.hash_ba.bab (from environment)
+        hash_c:
+          hash_ca:
+            caa: value hash_c.hash_ca.caa (from environment)
+        lookup_options:
+          mod_a::hash_b:
+            merge: hash
+          hash_c:
+            merge: hash
+      YAML
+      }
     end
 
     it 'finds data in the environment' do
@@ -303,7 +527,7 @@ describe "The lookup function" do
           hierarchy:
             - name: "Varying"
               data_hash: yaml_data
-              path: "x%{var.sub}.yaml"
+              path: "#{data_path}"
           YAML
       end
 
@@ -315,83 +539,144 @@ describe "The lookup function" do
             'data' => {
               'x.yaml' => <<-YAML.unindent,
                 y: value y from x
-              YAML
+                YAML
               'x_d.yaml' => <<-YAML.unindent,
                 y: value y from x_d
-              YAML
-              'x_e.yaml' => <<-YAML.unindent
+                YAML
+              'x_e.yaml' => <<-YAML.unindent,
                 y: value y from x_e
-              YAML
+                YAML
             }
           }
         }
       end
 
-      it 'reloads the configuration if interpolated values change' do
-        Puppet[:log_level] = 'debug'
-        collect_notices("notice('success')") do |scope|
-          expect(lookup_func.call(scope, 'y')).to eql('value y from x')
-          scope['var'] = { 'sub' => '_d' }
-          expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
-          nested_scope = scope.compiler.newscope(scope)
-          nested_scope['var'] = { 'sub' => '_e' }
-          expect(lookup_func.call(nested_scope, 'y')).to eql('value y from x_e')
+      context 'using local variable reference' do
+        let(:data_path) { 'x%{var.sub}.yaml' }
+
+        it 'reloads the configuration if interpolated values change' do
+          Puppet[:log_level] = 'debug'
+          collect_notices("notice('success')") do |scope|
+            expect(lookup_func.call(scope, 'y')).to eql('value y from x')
+            scope['var'] = { 'sub' => '_d' }
+            expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
+            nested_scope = scope.compiler.newscope(scope)
+            nested_scope['var'] = { 'sub' => '_e' }
+            expect(lookup_func.call(nested_scope, 'y')).to eql('value y from x_e')
+          end
+          expect(notices).to eql(['success'])
+          expect(debugs.any? { |m| m =~ /Hiera configuration recreated due to change of scope variables used in interpolation expressions/ }).to be_truthy
+        end
+
+        it 'does not include the lookups performed during stability check in explain output' do
+          Puppet[:log_level] = 'debug'
+          collect_notices("notice('success')") do |scope|
+            var = { 'sub' => '_d' }
+            scope['var'] = var
+            expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
+
+            # Second call triggers the check
+            expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
+          end
+          expect(notices).to eql(['success'])
+          expect(debugs.any? { |m| m =~ /Sub key: "sub"/ }).to be_falsey
         end
-        expect(notices).to eql(['success'])
-        expect(debugs.any? { |m| m =~ /Hiera configuration recreated due to change of scope variables used in interpolation expressions/ }).to be_truthy
       end
 
-      it 'does not include the lookups performed during stability check in explain output' do
-        Puppet[:log_level] = 'debug'
-        collect_notices("notice('success')") do |scope|
-          var = { 'sub' => '_d' }
-          scope['var'] = var
-          expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
+      context 'using global variable reference' do
+        let(:data_path) { 'x%{::var.sub}.yaml' }
 
-          # Second call triggers the check
-          expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
+        it 'reloads the configuration if interpolated that was previously undefined, gets defined' do
+          Puppet[:log_level] = 'debug'
+          collect_notices("notice('success')") do |scope|
+            expect(lookup_func.call(scope, 'y')).to eql('value y from x')
+            scope['var'] = { 'sub' => '_d' }
+            expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
+          end
+          expect(notices).to eql(['success'])
+          expect(debugs.any? { |m| m =~ /Hiera configuration recreated due to change of scope variables used in interpolation expressions/ }).to be_truthy
+        end
+
+        it 'does not reload the configuration if value changes locally' do
+          Puppet[:log_level] = 'debug'
+          collect_notices("notice('success')") do |scope|
+            scope['var'] = { 'sub' => '_d' }
+            expect(lookup_func.call(scope, 'y')).to eql('value y from x_d')
+            nested_scope = scope.compiler.newscope(scope)
+            nested_scope['var'] = { 'sub' => '_e' }
+            expect(lookup_func.call(nested_scope, 'y')).to eql('value y from x_d')
+          end
+          expect(notices).to eql(['success'])
+          expect(debugs.any? { |m| m =~ /Hiera configuration recreated due to change of scope variables used in interpolation expressions/ }).to be_falsey
         end
-        expect(notices).to eql(['success'])
-        expect(debugs.any? { |m| m =~ /Sub key: "sub"/ }).to be_falsey
       end
     end
 
-    context 'that uses reserved option' do
-      let(:environment_files) do
-        {
-          env_name => {
-            'hiera.yaml' => <<-YAML.unindent,
-              ---
-              version: 5
-              hierarchy:
-                - name: "Illegal"
-                  options:
-                    #{opt_spec}
-                  data_hash: yaml_data
-              YAML
-            'data' => {
-              'foo.yaml' => "a: The value a\n"
-            }
-          }
-        }
+    context 'that uses reserved' do
+       let(:environment_files) do
+        { env_name => { 'hiera.yaml' => hiera_yaml } }
       end
 
-      context 'path' do
-        let(:opt_spec) { 'path: data/foo.yaml' }
+      context 'option' do
+       let(:hiera_yaml) { <<-YAML.unindent }
+          version: 5
+          hierarchy:
+            - name: "Illegal"
+              options:
+                #{opt_spec}
+              data_hash: yaml_data
+          YAML
 
-        it 'fails and reports the reserved option key' do
-          expect { lookup('a') }.to raise_error do |e|
-            expect(e.message).to match(/Option key 'path' used in hierarchy 'Illegal' is reserved by Puppet/)
+        context 'path' do
+          let(:opt_spec) { 'path: data/foo.yaml' }
+
+          it 'fails and reports the reserved option key' do
+            expect { lookup('a') }.to raise_error do |e|
+              expect(e.message).to match(/Option key 'path' used in hierarchy 'Illegal' is reserved by Puppet/)
+            end
+          end
+        end
+
+        context 'uri' do
+          let(:opt_spec) { 'uri: file:///data/foo.yaml' }
+
+          it 'fails and reports the reserved option key' do
+            expect { lookup('a') }.to raise_error do |e|
+              expect(e.message).to match(/Option key 'uri' used in hierarchy 'Illegal' is reserved by Puppet/)
+            end
           end
         end
       end
 
-      context 'uri' do
-        let(:opt_spec) { 'uri: file:///data/foo.yaml' }
+      context 'default option' do
+        let(:hiera_yaml) { <<-YAML.unindent }
+          ---
+          version: 5
+          defaults:
+              options:
+                #{opt_spec}
+          hierarchy:
+            - name: "Illegal"
+              data_hash: yaml_data
+          YAML
 
-        it 'fails and reports the reserved option key' do
-          expect { lookup('a') }.to raise_error do |e|
-            expect(e.message).to match(/Option key 'uri' used in hierarchy 'Illegal' is reserved by Puppet/)
+        context 'path' do
+          let(:opt_spec) { 'path: data/foo.yaml' }
+
+          it 'fails and reports the reserved option key' do
+            expect { lookup('a') }.to raise_error do |e|
+              expect(e.message).to match(/Option key 'path' used in defaults is reserved by Puppet/)
+            end
+          end
+        end
+
+        context 'uri' do
+          let(:opt_spec) { 'uri: file:///data/foo.yaml' }
+
+          it 'fails and reports the reserved option key' do
+            expect { lookup('a') }.to raise_error do |e|
+              expect(e.message).to match(/Option key 'uri' used in defaults is reserved by Puppet/)
+            end
           end
         end
       end
@@ -505,7 +790,31 @@ describe "The lookup function" do
 
         it 'fails lookup and reports a type mismatch' do
           expect { lookup('a') }.to raise_error do |e|
-            expect(e.message).to match(/wrong type, expects a value of type Scalar, Sensitive, Type, Hash, or Array, got Runtime/)
+            expect(e.message).to match(/key 'a'.*data_hash function 'yaml_data'.*using location.*wrong type, expects Puppet::LookupValue, got Runtime/)
+          end
+        end
+      end
+
+      context 'that contains illegal interpolations' do
+        context 'in the form of an alias that is not the entire string' do
+          let(:common_yaml) { <<-YAML.unindent }
+            a: "%{alias('x')} and then some"
+            x: value x
+            YAML
+
+          it 'fails lookup and reports a type mismatch' do
+            expect { lookup('a') }.to raise_error("'alias' interpolation is only permitted if the expression is equal to the entire string")
+          end
+        end
+
+        context 'in the form of an unknown function name' do
+          let(:common_yaml) { <<-YAML.unindent }
+            a: "%{what('x')}"
+            x: value x
+            YAML
+
+          it 'fails lookup and reports a type mismatch' do
+            expect { lookup('a') }.to raise_error("Unknown interpolation method 'what'")
           end
         end
       end
@@ -561,56 +870,59 @@ describe "The lookup function" do
           YAML
       end
 
+      let(:env_lookup_options) { <<-YAML.unindent }
+        lookup_options:
+          b:
+            merge: hash
+          '^[^b]$':
+             merge: deep
+          '^c':
+             merge: first
+          '^b':
+             merge: first
+          '^mod::ha.*_b':
+            merge: hash
+        YAML
+
       let(:env_data) do
         {
-          'first.yaml' => <<-YAML.unindent,
-                a:
-                  aa:
-                    aaa: a.aa.aaa
-                b:
-                  ba:
-                    baa: b.ba.baa
-                  bb:
-                    bba: b.bb.bba
-                c:
-                  ca:
-                    caa: c.ca.caa
-                mod::hash_a:
-                  aa:
-                    aab: aab (from environment)
-                  ab:
-                    aba: aba (from environment)
-                    abb: abb (from environment)
-                mod::hash_b:
-                  ba:
-                    bab: bab (from environment)
-                  bc:
-                    bca: bca (from environment)
-                lookup_options:
-                  b:
-                    merge: hash
-                  '^[^b]$':
-                     merge: deep
-                  '^c':
-                     merge: first
-                  '^b':
-                     merge: first
-                  '^mod::ha.*_b':
-                    merge: hash
-        YAML
-        'second.yaml' => <<-YAML.unindent,
-                a:
-                  aa:
-                    aab: a.aa.aab
-                b:
-                  ba:
-                    bab: b.ba.bab
-                  bb:
-                    bbb: b.bb.bbb
-                c:
-                  ca:
-                    cab: c.ca.cab
-        YAML
+          'first.yaml' => <<-YAML.unindent + env_lookup_options,
+            a:
+              aa:
+                aaa: a.aa.aaa
+            b:
+              ba:
+                baa: b.ba.baa
+              bb:
+                bba: b.bb.bba
+            c:
+              ca:
+                caa: c.ca.caa
+            mod::hash_a:
+              aa:
+                aab: aab (from environment)
+              ab:
+                aba: aba (from environment)
+                abb: abb (from environment)
+            mod::hash_b:
+              ba:
+                bab: bab (from environment)
+              bc:
+                bca: bca (from environment)
+            YAML
+          'second.yaml' => <<-YAML.unindent,
+            a:
+              aa:
+                aab: a.aa.aab
+            b:
+              ba:
+                bab: b.ba.bab
+              bb:
+                bbb: b.bb.bbb
+            c:
+              ca:
+                cab: c.ca.cab
+            YAML
         }
       end
 
@@ -671,26 +983,24 @@ describe "The lookup function" do
           expect { lookup('mod::a') }.to raise_error(Puppet::DataBinding::LookupError, /all lookup_options patterns must match a key starting with module name/)
         end
       end
-    end
-
-    context 'and a global Hiera v4 configuration' do
-      let(:code_dir_files) do
-        {
-          'hiera.yaml' => <<-YAML.unindent,
-            ---
-            version: 4
-        YAML
-        }
-      end
 
-      before(:each) do
-        # Need to set here since spec_helper defines these settings in its "before each"
-        Puppet.settings[:codedir] = populated_code_dir
-        Puppet.settings[:hiera_config] = File.join(code_dir, 'hiera.yaml')
-      end
+      context 'and there are no lookup options that do not use patterns' do
+
+        let(:env_lookup_options) { <<-YAML.unindent }
+          lookup_options:
+            '^[^b]$':
+              merge: deep
+            '^c':
+              merge: first
+            '^b':
+              merge: first
+            '^mod::ha.*_b':
+              merge: hash
+          YAML
 
-      it 'raises an error' do
-        expect { lookup('a') }.to raise_error(Puppet::Error, /hiera configuration version 4 cannot be used in the global layer/)
+        it 'finds lookup_options that matches a pattern' do
+          expect(lookup('a')).to eql({'aa' => { 'aaa' => 'a.aa.aaa', 'aab' => 'a.aa.aab' }})
+        end
       end
     end
 
@@ -732,6 +1042,30 @@ describe "The lookup function" do
           }
         }
       end
+    end
+
+    context 'and an environment Hiera v5 configuration using mapped_paths' do
+      let(:scope_additions) do
+        {
+          'mapped' =>  {
+            'array_var' => ['a', 'b', 'c'],
+            'hash_var' => { 'x' => 'a', 'y' => 'b', 'z' => 'c' },
+            'string_var' => 's' },
+          'var' => 'global_var' # overridden by mapped path variable
+        }
+      end
+
+      let(:env_hiera_yaml) do
+        <<-YAML.unindent
+        ---
+        version: 5
+        hierarchy:
+          - name: Mapped Paths
+            mapped_paths: #{mapped_paths}
+          - name: Global Path
+            path: "%{var}.yaml"
+        YAML
+      end
 
       let(:environment_files) do
         {
@@ -742,20 +1076,199 @@ describe "The lookup function" do
         }
       end
 
-      it 'finds environment data using globs' do
-        expect(lookup('glob_a')).to eql('value glob_a')
-        expect(warnings).to be_empty
+      context 'that originates from an array' do
+        let (:mapped_paths) { '[mapped.array_var, var, "paths/%{var}.yaml"]' }
+
+        let(:env_data) do
+          {
+            'paths' => {
+              'a.yaml' => <<-YAML.unindent,
+                path_a: value path_a
+                path_h:
+                  a: value path_h.a
+                  c: value path_h.c
+                YAML
+              'b.yaml' => <<-YAML.unindent,
+                path_h:
+                  b: value path_h.b
+                  d: value path_h.d
+                YAML
+              'd.yaml' => <<-YAML.unindent
+                path_h:
+                  b: value path_h.b (from d.yaml)
+                  d: value path_h.d (from d.yaml)
+                YAML
+            },
+            'global_var.yaml' => <<-YAML.unindent,
+              path_h:
+                e: value path_h.e
+              YAML
+            'other_var.yaml' => <<-YAML.unindent
+              path_h:
+                e: value path_h.e (from other_var.yaml)
+              YAML
+          }
+        end
+
+        it 'finds environment data using mapped_paths' do
+          expect(lookup('path_a')).to eql('value path_a')
+          expect(warnings).to be_empty
+        end
+
+        it 'includes mapped path in explain output' do
+          explanation = explain('path_h', 'merge' => 'deep')
+          ['a', 'b', 'c'].each do |var|
+            expect(explanation).to match(/^\s+Path "#{env_dir}\/spec\/data\/paths\/#{var}\.yaml"\n\s+Original path: "paths\/%\{var\}\.yaml"/)
+          end
+          expect(warnings).to be_empty
+        end
+
+        it 'performs merges between mapped paths and global path interpolated using same key' do
+          expect(lookup('path_h', 'merge' => 'hash')).to eql(
+            {
+              'a' => 'value path_h.a',
+              'b' => 'value path_h.b',
+              'c' => 'value path_h.c',
+              'd' => 'value path_h.d',
+              'e' => 'value path_h.e'
+            })
+          expect(warnings).to be_empty
+        end
+
+        it 'keeps track of changes in key overridden by interpolated key' do
+          Puppet[:log_level] = 'debug'
+          collect_notices("notice('success')") do |scope|
+            expect(lookup_func.call(scope, 'path_h', 'merge' => 'hash')).to eql(
+              {
+                'a' => 'value path_h.a',
+                'b' => 'value path_h.b',
+                'c' => 'value path_h.c',
+                'd' => 'value path_h.d',
+                'e' => 'value path_h.e'
+              })
+            scope.with_local_scope('var' => 'other_var') do
+              expect(lookup_func.call(scope, 'path_h', 'merge' => 'hash')).to eql(
+                {
+                  'a' => 'value path_h.a',
+                  'b' => 'value path_h.b',
+                  'c' => 'value path_h.c',
+                  'd' => 'value path_h.d',
+                  'e' => 'value path_h.e (from other_var.yaml)'
+                })
+            end
+          end
+          expect(notices).to eql(['success'])
+          expect(debugs.any? { |m| m =~ /Hiera configuration recreated due to change of scope variables used in interpolation expressions/ }).to be_truthy
+        end
+
+        it 'keeps track of changes in elements of mapped key' do
+          Puppet[:log_level] = 'debug'
+          collect_notices("notice('success')") do |scope|
+            expect(lookup_func.call(scope, 'path_h', 'merge' => 'hash')).to eql(
+              {
+                'a' => 'value path_h.a',
+                'b' => 'value path_h.b',
+                'c' => 'value path_h.c',
+                'd' => 'value path_h.d',
+                'e' => 'value path_h.e'
+              })
+            scope['mapped']['array_var'] = ['a', 'c', 'd']
+            expect(lookup_func.call(scope, 'path_h', 'merge' => 'hash')).to eql(
+              {
+                'a' => 'value path_h.a',
+                'b' => 'value path_h.b (from d.yaml)',
+                'c' => 'value path_h.c',
+                'd' => 'value path_h.d (from d.yaml)',
+                'e' => 'value path_h.e'
+              })
+          end
+          expect(notices).to eql(['success'])
+          expect(debugs.any? { |m| m =~ /Hiera configuration recreated due to change of scope variables used in interpolation expressions/ }).to be_truthy
+        end
+      end
+
+      context 'that originates from a hash' do
+        let (:mapped_paths) { '[mapped.hash_var, var, "paths/%{var.0}.%{var.1}.yaml"]' }
+
+        let(:env_data) do
+          {
+            'paths' => {
+              'x.a.yaml' => <<-YAML.unindent,
+                path_xa: value path_xa
+                path_m:
+                  a: value path_m.a
+                  c: value path_m.c
+                YAML
+              'y.b.yaml' => <<-YAML.unindent
+                path_m:
+                  b: value path_m.b
+                  d: value path_m.d
+                YAML
+            },
+            'global_var.yaml' => <<-YAML.unindent
+              path_m:
+                e: value path_m.e
+              YAML
+          }
+        end
+
+        it 'finds environment data using mapped_paths' do
+          expect(lookup('path_xa')).to eql('value path_xa')
+          expect(warnings).to be_empty
+        end
+
+        it 'includes mapped path in explain output' do
+          explanation = explain('path_h', 'merge' => 'deep')
+          ['x\.a', 'y\.b', 'z\.c'].each do |var|
+            expect(explanation).to match(/^\s+Path "#{env_dir}\/spec\/data\/paths\/#{var}\.yaml"\n\s+Original path: "paths\/%\{var\.0\}\.%\{var\.1\}\.yaml"/)
+          end
+          expect(warnings).to be_empty
+        end
+
+        it 'performs merges between mapped paths' do
+          expect(lookup('path_m', 'merge' => 'hash')).to eql(
+            {
+              'a' => 'value path_m.a',
+              'b' => 'value path_m.b',
+              'c' => 'value path_m.c',
+              'd' => 'value path_m.d',
+              'e' => 'value path_m.e'
+            })
+          expect(warnings).to be_empty
+        end
       end
 
-      it 'performs merges between interpolated and globbed paths' do
-        expect(lookup('glob_b', 'merge' => 'hash')).to eql(
+      context 'that originates from a string' do
+        let (:mapped_paths) { '[mapped.string_var, var, "paths/%{var}.yaml"]' }
+
+        let(:env_data) do
           {
-            'a' => 'value glob_b.a',
-            'b' => 'value glob_b.b',
-            'c' => 'value glob_b.c',
-            'd' => 'value glob_b.d'
-          })
-        expect(warnings).to be_empty
+            'paths' => {
+              's.yaml' => <<-YAML.unindent,
+                path_s: value path_s
+                YAML
+            }
+          }
+        end
+
+        it 'includes mapped path in explain output' do
+          expect(explain('path_s')).to match(/^\s+Path "#{env_dir}\/spec\/data\/paths\/s\.yaml"\n\s+Original path: "paths\/%\{var\}\.yaml"/)
+          expect(warnings).to be_empty
+        end
+
+        it 'finds environment data using mapped_paths' do
+          expect(lookup('path_s')).to eql('value path_s')
+          expect(warnings).to be_empty
+        end
+      end
+
+      context 'where the enty does not exist' do
+        let (:mapped_paths) { '[mapped.nosuch_var, var, "paths/%{var}.yaml"]' }
+
+        it 'finds environment data using mapped_paths' do
+          expect(explain('hello')).to match(/No such key: "hello"/)
+          expect(warnings).to be_empty
+        end
       end
     end
 
@@ -784,7 +1297,7 @@ describe "The lookup function" do
 
       it 'will raise an error if --strict is set to error' do
         Puppet[:strict] = :error
-        expect { lookup('g') }.to raise_error(Puppet::Error, /hiera configuration version 3 cannot be used in an environment/)
+        expect { lookup('g') }.to raise_error(Puppet::Error, /hiera.yaml version 3 cannot be used in an environment/)
       end
 
       it 'will log a warning and ignore the file if --strict is set to warning' do
@@ -879,6 +1392,9 @@ describe "The lookup function" do
               hash_c:
                 hash_ca:
                   cab: value hash_c.hash_ca.cab (from global)
+              ipl_hiera_env: "environment value '%{hiera('mod_a::hash_a.a')}'"
+              ipl_hiera_mod: "module value '%{hiera('mod_a::abc')}'"
+              ipl_hiera_modc: "module value '%{hiera('mod_a::caller')}'"
               YAML
             'example.com.yaml' =>  <<-YAML.unindent,
               x: value x (from global example.com.yaml)
@@ -905,6 +1421,44 @@ describe "The lookup function" do
         }
       end
 
+      let(:ruby_dir_files) do
+        {
+          'hiera' => {
+            'backend' => {
+              'custom_backend.rb' => <<-RUBY.unindent,
+            class Hiera::Backend::Custom_backend
+              def lookup(key, scope, order_override, resolution_type, context)
+                case key
+                when 'hash_c'
+                  { 'hash_ca' => { 'cad' => 'value hash_c.hash_ca.cad (from global custom)' }}
+                when 'hash'
+                  { 'array' => [ 'x5,x6' ] }
+                when 'array'
+                  [ 'x5,x6' ]
+                when 'datasources'
+                  Hiera::Backend.datasources(scope, order_override) { |source| source }
+                when 'dotted.key'
+                  'custom backend received request for dotted.key value'
+                else
+                  throw :no_such_key
+                end
+              end
+            end
+            RUBY
+            'other_backend.rb' => <<-RUBY.unindent,
+            class Hiera::Backend::Other_backend
+              def lookup(key, scope, order_override, resolution_type, context)
+                value = Hiera::Config[:other][key.to_sym]
+                throw :no_such_key if value.nil?
+                value
+              end
+            end
+            RUBY
+            }
+          }
+        }
+      end
+
       before(:each) do
         # Need to set here since spec_helper defines these settings in its "before each"
         Puppet.settings[:codedir] = populated_code_dir
@@ -929,7 +1483,7 @@ describe "The lookup function" do
       end
 
       context 'version 3' do
-        it 'finds data in the environment and reports deprecation warnings for both environment.conf and hiera.yaml' do
+        it 'finds data in in global layer and reports deprecation warnings for hiera.yaml' do
           expect(lookup('a')).to eql('value a (from global)')
           expect(warnings).to include(/Use of 'hiera.yaml' version 3 is deprecated. It should be converted to version 5/)
         end
@@ -981,6 +1535,64 @@ describe "The lookup function" do
           expect(lookup('xs.subkey')).to eql('value xs.subkey (from global hocon)')
         end
 
+        context 'with a module data provider' do
+          let(:module_files) do
+            {
+              'mod_a' => {
+                'hiera.yaml' => <<-YAML.unindent,
+                  version: 5
+                  hierarchy:
+                    - name: Common
+                      path: common.yaml
+                  YAML
+                'data' => {
+                  'common.yaml' =>  <<-YAML.unindent
+                    mod_a::abc: value mod_a::abc (from module)
+                    mod_a::caller: "calling module is %{calling_module}"
+                  YAML
+                }
+              }
+            }
+          end
+
+          let(:environment_files) do
+            {
+              env_name => {
+                'hiera.yaml' => env_hiera_yaml,
+                'data' => env_data,
+                'modules' => module_files
+              }
+            }
+          end
+
+          it "interpolation function 'hiera' finds values in environment" do
+            expect(lookup('ipl_hiera_env')).to eql("environment value 'value mod_a::hash_a.a (from environment)'")
+          end
+
+          it "interpolation function 'hiera' finds values in module" do
+            expect(lookup('ipl_hiera_mod')).to eql("module value 'value mod_a::abc (from module)'")
+          end
+
+          it "interpolation function 'hiera' finds values in module and that module does not find %{calling_module}" do
+            expect(lookup('ipl_hiera_modc')).to eql("module value 'calling module is '")
+          end
+
+          context 'but no environment data provider' do
+            let(:environment_files) do
+              {
+                env_name => {
+                  'modules' => module_files
+                }
+              }
+            end
+
+            it "interpolation function 'hiera' does not find values in a module" do
+              expect(lookup('ipl_hiera_mod')).to eql("module value ''")
+            end
+          end
+        end
+
+
         context 'using an eyaml backend' do
           let(:private_key_name) { 'private_key.pkcs7.pem' }
           let(:public_key_name) { 'public_key.pkcs7.pem' }
@@ -1309,6 +1921,10 @@ describe "The lookup function" do
           expect(lookup('other_option')).to eql('value of other_option')
         end
 
+        it 'dotted keys are passed down to custom backend' do
+          expect(lookup('dotted.key')).to eql('custom backend received request for dotted.key value')
+        end
+
         it 'multiple hiera3_backend declarations can be used and are merged into the generated config' do
           expect(lookup(['datasources', 'other_option'])).to eql([['common', 'example.com'], 'value of other_option'])
           expect(Hiera::Config.instance_variable_get(:@config)).to eql(
@@ -1328,6 +1944,60 @@ describe "The lookup function" do
             expect(e.message).to match(/Lookup using Hocon data_hash function is not supported without hocon library/)
           end
         end
+
+        context 'with missing path declaraion' do
+          context 'and yaml_data function' do
+            let(:hiera_yaml) { <<-YAML.unindent }
+              version: 5
+              hierarchy:
+                - name: Yaml
+                  data_hash: yaml_data
+              YAML
+
+            it 'fails and reports the missing path' do
+              expect { lookup('a') }.to raise_error(/one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this data_hash function/)
+            end
+          end
+
+          context 'and json_data function' do
+            let(:hiera_yaml) { <<-YAML.unindent }
+              version: 5
+              hierarchy:
+                - name: Json
+                  data_hash: json_data
+              YAML
+
+            it 'fails and reports the missing path' do
+              expect { lookup('a') }.to raise_error(/one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this data_hash function/)
+            end
+          end
+
+          context 'and hocon_data function' do
+            let(:hiera_yaml) { <<-YAML.unindent }
+              version: 5
+              hierarchy:
+                - name: Hocon
+                  data_hash: hocon_data
+              YAML
+
+            it 'fails and reports the missing path' do
+              expect { lookup('a') }.to raise_error(/one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this data_hash function/)
+            end
+          end
+
+          context 'and eyaml_lookup_key function' do
+            let(:hiera_yaml) { <<-YAML.unindent }
+              version: 5
+              hierarchy:
+                - name: Yaml
+                  lookup_key: eyaml_lookup_key
+              YAML
+
+            it 'fails and reports the missing path' do
+              expect { lookup('a') }.to raise_error(/one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this lookup_key function/)
+            end
+          end
+        end
       end
 
       context 'with a hiera3_backend that has no paths' do
@@ -1387,7 +2057,7 @@ describe "The lookup function" do
           end
 
           it 'raises an error' do
-            expect { lookup('mod_a::a') }.to raise_error(Puppet::Error, /hiera configuration version 3 cannot be used in a module/)
+            expect { lookup('mod_a::a') }.to raise_error(Puppet::Error, /hiera.yaml version 3 cannot be used in a module/)
           end
         end
 
@@ -1438,13 +2108,24 @@ describe "The lookup function" do
       end
 
       context 'using a data_hash that reads a yaml file' do
+        let(:defaults) {
+          {
+            'mod_a::xd' => 'value mod_a::xd (from default)',
+            'mod_a::xd_found' => 'value mod_a::xd_found (from default)',
+            'scope_xd' => 'value scope_xd (from default)'
+          }}
+        let(:overrides) {
+          {
+            'mod_a::xo' => 'value mod_a::xo (from override)',
+            'scope_xo' => 'value scope_xo (from override)'
+          }}
+
         let(:scope_additions) do
           {
             'scope_scalar' => 'scope scalar value',
             'scope_hash' => { 'a' => 'scope hash a', 'b' => 'scope hash b' }
           }
         end
-
         let(:mod_a_files) do
           {
             'mod_a' => {
@@ -1628,55 +2309,57 @@ describe "The lookup function" do
       end
 
       context 'using a lookup_key that is a puppet function' do
+        let(:puppet_function) { <<-PUPPET.unindent }
+          function mod_a::pp_lookup_key(Puppet::LookupKey $key, Hash[String,String] $options, Puppet::LookupContext $context) >> Puppet::LookupValue {
+            case $key {
+              'mod_a::really_interpolated': { $context.interpolate("-- %{lookup('mod_a::a')} --") }
+              'mod_a::recursive': { lookup($key) }
+              default: {
+                if $context.cache_has_key(mod_a::a) {
+                  $context.explain || { 'reusing cache' }
+                } else {
+                  $context.explain || { 'initializing cache' }
+                  $context.cache_all({
+                    mod_a::a => 'value mod_a::a (from mod_a)',
+                    mod_a::b => 'value mod_a::b (from mod_a)',
+                    mod_a::c => 'value mod_a::c (from mod_a)',
+                    mod_a::hash_a => {
+                      a => 'value mod_a::hash_a.a (from mod_a)',
+                      b => 'value mod_a::hash_a.b (from mod_a)'
+                    },
+                    mod_a::hash_b => {
+                      a => 'value mod_a::hash_b.a (from mod_a)',
+                      b => 'value mod_a::hash_b.b (from mod_a)'
+                    },
+                    mod_a::interpolated => "-- %{lookup('mod_a::a')} --",
+                    mod_a::a_a => "-- %{lookup('mod_a::hash_a.a')} --",
+                    mod_a::a_b => "-- %{lookup('mod_a::hash_a.b')} --",
+                    mod_a::b_a => "-- %{lookup('mod_a::hash_b.a')} --",
+                    mod_a::b_b => "-- %{lookup('mod_a::hash_b.b')} --",
+                    'mod_a::a.quoted.key' => 'value mod_a::a.quoted.key (from mod_a)',
+                    mod_a::sensitive => Sensitive('reduct me please'),
+                    mod_a::type => Object[{name => 'FindMe', 'attributes' => {'x' => String}}],
+                    mod_a::version => SemVer('3.4.1'),
+                    mod_a::version_range => SemVerRange('>=3.4.1'),
+                    mod_a::timestamp => Timestamp("1994-03-25T19:30:00"),
+                    mod_a::timespan => Timespan("3-10:00:00")
+                  })
+                }
+                if !$context.cache_has_key($key) {
+                  $context.not_found
+                }
+                $context.explain || { "returning value for $key" }
+                $context.cached_value($key)
+              }
+            }
+          }
+        PUPPET
+
         let(:mod_a_files) do
           {
             'mod_a' => {
               'functions' => {
-                'pp_lookup_key.pp' => <<-PUPPET.unindent
-                function mod_a::pp_lookup_key($key, $options, $context) {
-                  case $key {
-                    'mod_a::really_interpolated': { $context.interpolate("-- %{lookup('mod_a::a')} --") }
-                    'mod_a::recursive': { lookup($key) }
-                    default: {
-                      if $context.cache_has_key(mod_a::a) {
-                        $context.explain || { 'reusing cache' }
-                      } else {
-                        $context.explain || { 'initializing cache' }
-                        $context.cache_all({
-                          mod_a::a => 'value mod_a::a (from mod_a)',
-                          mod_a::b => 'value mod_a::b (from mod_a)',
-                          mod_a::c => 'value mod_a::c (from mod_a)',
-                          mod_a::hash_a => {
-                            a => 'value mod_a::hash_a.a (from mod_a)',
-                            b => 'value mod_a::hash_a.b (from mod_a)'
-                          },
-                          mod_a::hash_b => {
-                            a => 'value mod_a::hash_b.a (from mod_a)',
-                            b => 'value mod_a::hash_b.b (from mod_a)'
-                          },
-                          mod_a::interpolated => "-- %{lookup('mod_a::a')} --",
-                          mod_a::a_a => "-- %{lookup('mod_a::hash_a.a')} --",
-                          mod_a::a_b => "-- %{lookup('mod_a::hash_a.b')} --",
-                          mod_a::b_a => "-- %{lookup('mod_a::hash_b.a')} --",
-                          mod_a::b_b => "-- %{lookup('mod_a::hash_b.b')} --",
-                          'mod_a::a.quoted.key' => 'value mod_a::a.quoted.key (from mod_a)',
-                          mod_a::sensitive => Sensitive('reduct me please'),
-                          mod_a::type => Object[{name => 'FindMe', 'attributes' => {'x' => String}}],
-                          mod_a::version => SemVer('3.4.1'),
-                          mod_a::version_range => SemVerRange('>=3.4.1'),
-                          mod_a::timestamp => Timestamp("1994-03-25T19:30:00"),
-                          mod_a::timespan => Timespan("3-10:00:00")
-                        })
-                      }
-                      if !$context.cache_has_key($key) {
-                        $context.not_found
-                      }
-                      $context.explain || { "returning value for $key" }
-                      $context.cached_value($key)
-                    }
-                  }
-                }
-              PUPPET
+                'pp_lookup_key.pp' => puppet_function
               },
               'hiera.yaml' => <<-YAML.unindent,
               ---
@@ -1749,6 +2432,19 @@ describe "The lookup function" do
             expect(notices).to eql(['success'])
           end
         end
+
+        context 'with declared but incompatible return_type' do
+          let(:puppet_function) { <<-PUPPET.unindent }
+            function mod_a::pp_lookup_key(Puppet::LookupKey $key, Hash[String,String] $options, Puppet::LookupContext $context) >> Runtime['ruby','Symbol'] {
+              undef
+            }
+            PUPPET
+
+          it 'fails and reports error' do
+            expect{lookup('mod_a::a')}.to raise_error(
+              "Return type of 'lookup_key' function named 'mod_a::pp_lookup_key' is incorrect, expects a value of type Undef, Scalar, Sensitive, Type, Hash, or Array, got Runtime")
+          end
+        end
       end
 
       context 'using a data_dig that is a ruby function' do
@@ -1765,6 +2461,7 @@ describe "The lookup function" do
                           param 'Array[String[1]]', :segments
                           param 'Hash[String,Any]', :options
                           param 'Puppet::LookupContext', :context
+                          return_type 'Puppet::LookupValue'
                         end
 
                         def ruby_dig(segments, options, context)
@@ -1813,6 +2510,11 @@ describe "The lookup function" do
               'hiera.yaml' => <<-YAML.unindent,
               ---
               version: 5
+              defaults:
+                options:
+                  option_b:
+                    z: Default option value b.z
+
               hierarchy:
                 - name: "Common"
                   data_dig: mod_a::ruby_dig
@@ -1822,7 +2524,9 @@ describe "The lookup function" do
                     option_b:
                       x: Option value b.x
                       y: Option value b.y
-            YAML
+                - name: "Extra"
+                  data_dig: mod_a::ruby_dig
+           YAML
             }
           }
         end
@@ -1844,11 +2548,13 @@ describe "The lookup function" do
         end
 
         it 'does not accept return of runtime type from function' do
-          expect(explain('mod_a::bad_type')).to include('Value returned from Hierarchy entry "Common" has wrong type')
+          # Message is produced by the called function, not by the lookup framework
+          expect(explain('mod_a::bad_type')).to include("value returned from function 'ruby_dig' has wrong type")
         end
 
         it 'does not accept return of runtime type embedded in hash from function' do
-          expect(explain('mod_a::bad_type_in_hash')).to include('Value returned from Hierarchy entry "Common" has wrong type')
+          # Message is produced by the called function, not by the lookup framework
+          expect(explain('mod_a::bad_type_in_hash')).to include("value returned from function 'ruby_dig' has wrong type")
         end
 
         it 'will not merge hashes from environment and module unless strategy hash is used' do
@@ -1859,6 +2565,22 @@ describe "The lookup function" do
           expect(lookup('mod_a::options.option_b.x')).to eql('Option value b.x')
         end
 
+        it 'default options are passed to the function' do
+          expect(lookup('mod_a::options.option_b.z')).to eql('Default option value b.z')
+        end
+
+        it 'default options are not merged with hierarchy options' do
+          expect(lookup('mod_a::options')).to eql(
+            {
+              'option_a' => 'Option value a',
+              'option_b' => {
+                'y' => 'Option value b.y',
+                'x' => 'Option value b.x'
+              },
+              'uri' => 'http://www.example.com/passed/as/option'
+            })
+        end
+
         it 'hierarchy entry "uri" is passed as location option to the function' do
           expect(lookup('mod_a::options.uri')).to eql('http://www.example.com/passed/as/option')
         end
@@ -1878,6 +2600,125 @@ describe "The lookup function" do
           end
         end
       end
+
+      context 'that has a default_hierarchy' do
+        let(:mod_a_hiera_yaml) { <<-YAML.unindent }
+          version: 5
+          hierarchy:
+            - name: "Common"
+              path: common.yaml
+            - name: "Common 2"
+              path: common2.yaml
+
+          default_hierarchy:
+            - name: "Default"
+              path: defaults.yaml
+            - name: "Default 2"
+              path: defaults2.yaml
+          YAML
+
+        let(:mod_a_common) { <<-YAML.unindent }
+          mod_a::a: value mod_a::a (from module)
+          mod_a::d:
+            a: value mod_a::d.a (from module)
+          mod_a::f:
+            a:
+              a: value mod_a::f.a.a (from module)
+          lookup_options:
+            mod_a::e:
+              merge: deep
+          YAML
+
+
+        let(:mod_a_common2) { <<-YAML.unindent }
+          mod_a::b: value mod_a::b (from module)
+          mod_a::d:
+            c: value mod_a::d.c (from module)
+          mod_a::f:
+            a:
+              b: value mod_a::f.a.b (from module)
+          YAML
+
+        let(:mod_a_defaults) { <<-YAML.unindent }
+          mod_a::a: value mod_a::a (from module defaults)
+          mod_a::b: value mod_a::b (from module defaults)
+          mod_a::c: value mod_a::c (from module defaults)
+          mod_a::d:
+            b: value mod_a::d.b (from module defaults)
+          mod_a::e:
+            a:
+              a: value mod_a::e.a.a (from module defaults)
+          mod_a::g:
+            a:
+              a: value mod_a::g.a.a (from module defaults)
+          lookup_options:
+            mod_a::d:
+              merge: hash
+            mod_a::g:
+              merge: deep
+          YAML
+
+        let(:mod_a_defaults2) { <<-YAML.unindent }
+          mod_a::e:
+            a:
+              b: value mod_a::e.a.b (from module defaults)
+          mod_a::g:
+            a:
+              b: value mod_a::g.a.b (from module defaults)
+          YAML
+
+        let(:mod_a_files) do
+          {
+            'mod_a' => {
+              'data' => {
+                'common.yaml' => mod_a_common,
+                'common2.yaml' => mod_a_common2,
+                'defaults.yaml' => mod_a_defaults,
+                'defaults2.yaml' => mod_a_defaults2
+              },
+              'hiera.yaml' => mod_a_hiera_yaml
+            }
+          }
+        end
+
+        it 'the default hierarchy does not interfere with environment hierarchy' do
+          expect(lookup('mod_a::a')).to eql('value mod_a::a (from environment)')
+        end
+
+        it 'the default hierarchy does not interfere with regular hierarchy in module' do
+          expect(lookup('mod_a::b')).to eql('value mod_a::b (from module)')
+        end
+
+        it 'the default hierarchy is consulted when no value is found elsewhere' do
+          expect(lookup('mod_a::c')).to eql('value mod_a::c (from module defaults)')
+        end
+
+        it 'the default hierarchy does not participate in a merge' do
+          expect(lookup('mod_a::d', 'merge' => 'hash')).to eql('a' => 'value mod_a::d.a (from module)', 'c' => 'value mod_a::d.c (from module)')
+        end
+
+        it 'lookup_options from regular hierarchy does not effect values found in the default hierarchy' do
+          expect(lookup('mod_a::e')).to eql('a' => { 'a' => 'value mod_a::e.a.a (from module defaults)' })
+        end
+
+        it 'lookup_options from default hierarchy affects values found in the default hierarchy' do
+          expect(lookup('mod_a::g')).to eql('a' => { 'a' => 'value mod_a::g.a.a (from module defaults)', 'b' => 'value mod_a::g.a.b (from module defaults)'})
+        end
+
+        it 'merge parameter does not override lookup_options defined in the default hierarchy' do
+          expect(lookup('mod_a::g', 'merge' => 'hash')).to eql(
+            'a' => { 'a' => 'value mod_a::g.a.a (from module defaults)', 'b' => 'value mod_a::g.a.b (from module defaults)'})
+        end
+
+        it 'lookup_options from default hierarchy does not effect values found in the regular hierarchy' do
+          expect(lookup('mod_a::d')).to eql('a' => 'value mod_a::d.a (from module)')
+        end
+
+        it 'the default hierarchy lookup is included in the explain output' do
+          explanation = explain('mod_a::c')
+          expect(explanation).to match(/Searching default_hierarchy of module "mod_a".+Original path: "defaults.yaml"/m)
+        end
+      end
     end
 
     context 'and an eyaml lookup_key function' do
@@ -1968,6 +2809,7 @@ describe "The lookup function" do
       let(:data_files) do
         {
           'common.eyaml' => <<-YAML.unindent
+            # a: Encrypted value 'a' (from environment)
             a: >
               ENC[PKCS7,MIIBmQYJKoZIhvcNAQcDoIIBijCCAYYCAQAxggEhMIIBHQIBADAFMAACAQEw
               DQYJKoZIhvcNAQEBBQAEggEAUwwNRA5ZKM87SLnjnJfzDFRQbeheSYMTOhcr
@@ -1981,6 +2823,7 @@ describe "The lookup function" do
               dCILO7I8QqU=]
             hash_a:
               "hash_%{ipl_suffix}":
+                # aaa: Encrypted value hash_a.hash_aa.aaa (from environment)
                 aaa: >
                   ENC[PKCS7,MIIBqQYJKoZIhvcNAQcDoIIBmjCCAZYCAQAxggEhMIIBHQIBADAFMAACAQEw
                   DQYJKoZIhvcNAQEBBQAEggEAhvGXL5RxVUs9wdqJvpCyXtfCHrm2HbG/u30L
@@ -1993,6 +2836,7 @@ describe "The lookup function" do
                   ovm/gEB4oPlYJswoXuWqcEBfwZzbpy96x3b2Le/yoa72ylbPAUc5GfLENvFQ
                   zXpTtSmQE0fixY4JMaBTke65ZRvoiOQO]
             array_a:
+              # - "array_a[0]"
               - >
                 ENC[PKCS7,MIIBeQYJKoZIhvcNAQcDoIIBajCCAWYCAQAxggEhMIIBHQIBADAFMAACAQEw
                 DQYJKoZIhvcNAQEBBQAEggEAmXZfyfU77vVCZqHpR10qhD0Jy9DpMGBgal97
@@ -2003,6 +2847,7 @@ describe "The lookup function" do
                 MieIkHj93bX3gIEcenECLdWaEzcPa7MHgl6zevQKg4H0JVmcvKYyfHYqcrVE
                 PqizKDA8BgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBDf259KZEay1widVSFy
                 I9zGgBAICjm0x2GeqoCnHdiAA+jt]
+              # - "array_a[1]"
               - >
                 ENC[PKCS7,MIIBeQYJKoZIhvcNAQcDoIIBajCCAWYCAQAxggEhMIIBHQIBADAFMAACAQEw
                 DQYJKoZIhvcNAQEBBQAEggEATVy4hHG356INFKOswAhoravh66iJljp+Vn3o
@@ -2013,6 +2858,17 @@ describe "The lookup function" do
                 t22zpYK4J8lgCBV2gKfrOWSi9MAs6JhCeOb8wNLMmAUTbc0WrFJxoCwAPX0z
                 MAjsNjA8BgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBC4v4bNE4gFlbLmVY+9
                 BtSLgBBm7U0wu6d6s9wF9Ek9IHPe]
+            # ref_a: "A resolved = '%{hiera('a')}'"
+            ref_a: >
+                ENC[PKCS7,MIIBiQYJKoZIhvcNAQcDoIIBejCCAXYCAQAxggEhMIIBHQIBADAFMAACAQEw
+                DQYJKoZIhvcNAQEBBQAEggEAFSuUp+yk+oaA7b5ekT0u360CQ9Q2sIQ/bTcM
+                jT3XLjm8HIGYPcysOEnuo8WcAxJFY5iya4yQ7Y/UhMWXaTi7Vzv/6BmyPDwz
+                +7Z2Mf0r0PvS5+ylue6aem/3bXPOmXTKTf68OCehTRXlDUs8/av9gnsDzojp
+                yiUTBZvKxhIP2n//GyoHgyATveHT0lxPVpdMycB347DtWS7IduCxx0+KiOOw
+                DXYFlYbIVxVInwgERxtsfYSr+Fu0/mkjtRsQm+dPzMQOATE9Val2gGKsV6bi
+                kdm1OM9HrwVsFj6Lma6FYmr89Bcm/1uEc8fiOMtNK3z2+nwunWBMNCGneMYD
+                C5IJejBMBgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBAeiZDGQyXHkZlV5ceT
+                iCxpgCDDatuVvbPEEi8rKOC7xhPHZ22zLEEV//l7C9jxq+DZcA==]
             YAML
         }
       end
@@ -2027,6 +2883,10 @@ describe "The lookup function" do
         expect(lookup('hash_a')).to include('hash_aa')
       end
 
+      it 'evaluates interpolations in encrypted values' do
+        expect(lookup('ref_a')).to eql("A resolved = 'Encrypted value 'a' (from environment)'")
+      end
+
       it 'can read encrypted values inside a hash' do
         expect(lookup('hash_a.hash_aa.aaa')).to eql('Encrypted value hash_a.hash_aa.aaa (from environment)')
       end