(POOLER-107) Add configuration API endpoint

This commit adds a configuration endpoint to the vmpooler API. Pool
size, and pool template, can be adjusted for pools that are configured
at vmpooler application start time. Pool template changes trigger a pool
refresh, and the new template has delta disks created automatically by
vmpooler.

Additionally, the capability to create template delta disks is added to
the vsphere provider, and this is implemented to ensure that templates
have delta disks created at application start time.

The mechanism used to find template VM objects is simplified to make the flow of logic easier to understand. As an additional benefit, performance of this lookup is improved by using FindByInventoryPath.

A table of contents is added to API.md to ease navigation. Without this change API.md has no table of contents and is difficult to navigate.

Add mutex object for managing pool configuration updates

This commit adds a mutex object for ensuring that pool configuration changes are synchronized across multiple running threads, removing the possibility of two threads attempting to update something at once, without relying on redis data. Without this change this is managed crudely by specifying in redis that a configuration update is taking place. This redis data is left so the REPOPULATE section of _check_pool can still identify when a configuration change is in progress, and prevent a pool from repopulating at that time.

Add wake up event for pool template changes

This commit adds a wake up event to detect pool template changes.
Additionally, GET /config has a template_ready section added to the
output for each pool, which makes clear when a pool is ready to populate
itself.

spec/unit/providers/vsphere_spec.rb

@@ -283,6 +283,7 @@ EOT
 
     let(:clone_vm_task) { mock_RbVmomi_VIM_Task() }
     let(:new_vm_object)  { mock_RbVmomi_VIM_VirtualMachine({ :name => vmname }) }
+    let(:new_template_object)  { mock_RbVmomi_VIM_VirtualMachine({ :name => vmname }) }
 
     before(:each) do
       allow(subject).to receive(:connect_to_vsphere).and_return(connection)
@@ -305,19 +306,30 @@ EOT
       end
     end
 
-    context 'Given a template path that does not exist' do
+    context 'Given a template that starts with /' do
       before(:each) do
-        config[:pools][0]['template'] = 'missing_Templates/pool1'
+        config[:pools][0]['template'] = '/bad_template'
       end
 
       it 'should raise an error' do
-        expect{ subject.create_vm(poolname, vmname) }.to raise_error(/specifies a template folder of .+ which does not exist/)
+        expect{ subject.create_vm(poolname, vmname) }.to raise_error(/did not specify a full path for the template/)
+      end
+    end
+
+    context 'Given a template that ends with /' do
+      before(:each) do
+        config[:pools][0]['template'] = 'bad_template/'
+      end
+
+      it 'should raise an error' do
+        expect{ subject.create_vm(poolname, vmname) }.to raise_error(/did not specify a full path for the template/)
       end
     end
 
     context 'Given a template VM that does not exist' do
       before(:each) do
         config[:pools][0]['template'] = 'Templates/missing_template'
+        expect(subject).to receive(:find_template_vm).and_raise("specifies a template VM of #{vmname} which does not exist")
       end
 
       it 'should raise an error' do
@@ -327,7 +339,8 @@ EOT
 
     context 'Given a successful creation' do
       before(:each) do
-        template_vm = subject.find_folder('Templates',connection,datacenter_name).find('pool1')
+        template_vm = new_template_object
+        allow(subject).to receive(:find_template_vm).and_return(new_template_object)
         allow(template_vm).to receive(:CloneVM_Task).and_return(clone_vm_task)
         allow(clone_vm_task).to receive(:wait_for_completion).and_return(new_vm_object)
       end
@@ -339,7 +352,7 @@ EOT
       end
 
       it 'should use the appropriate Create_VM spec' do
-        template_vm = subject.find_folder('Templates',connection,datacenter_name).find('pool1')
+        template_vm = new_template_object
         expect(template_vm).to receive(:CloneVM_Task)
           .with(create_vm_spec(vmname,'pool1','datastore0'))
           .and_return(clone_vm_task)
@@ -3461,5 +3474,71 @@ EOT
     end
   end
 
+  describe 'find_template_vm' do
+    let(:vm_object) { mock_RbVmomi_VIM_VirtualMachine() }
 
+    before(:each) do
+      allow(connection.searchIndex).to receive(:FindByInventoryPath)
+    end
+    it 'should raise an error when the datacenter cannot be found' do
+      config[:providers][:vsphere]['datacenter'] = nil
+
+      expect{ subject.find_template_vm(config[:pools][0],connection) }.to raise_error('cannot find datacenter')
+    end
+
+    it 'should raise an error when the template specified cannot be found' do
+      expect(connection.searchIndex).to receive(:FindByInventoryPath).and_return(nil)
+
+      expect{ subject.find_template_vm(config[:pools][0],connection) }.to raise_error("Pool #{poolname} specifies a template VM of #{config[:pools][0]['template']} which does not exist for the provider vsphere")
+    end
+
+    it 'should return the vm object' do
+      expect(connection.searchIndex).to receive(:FindByInventoryPath).and_return(vm_object)
+
+      subject.find_template_vm(config[:pools][0],connection)
+    end
+  end
+
+  describe 'valid_template_path?' do
+
+    it 'should return true with a valid template path' do
+      expect(subject.valid_template_path?('test/template')).to eq(true)
+    end
+
+    it 'should return false when no / is found' do
+      expect(subject.valid_template_path?('testtemplate')).to eq(false)
+    end
+
+    it 'should return false when template path begins with /' do
+      expect(subject.valid_template_path?('/testtemplate')).to eq(false)
+    end
+
+    it 'should return false when template path ends with /' do
+      expect(subject.valid_template_path?('testtemplate/')).to eq(false)
+    end
+  end
+
+  describe 'create_template_delta_disks' do
+    let(:template_object) { mock_RbVmomi_VIM_VirtualMachine({
+        :name => vmname,
+      })
+    }
+
+    before(:each) do
+      allow(subject).to receive(:connect_to_vsphere).and_return(connection)
+    end
+
+    context 'with a template VM found' do
+
+      before(:each) do
+        expect(subject).to receive(:find_template_vm).and_return(template_object)
+      end
+
+      it 'should reconfigure the VM creating delta disks' do
+        expect(template_object).to receive(:add_delta_disk_layer_on_all_disks)
+
+        subject.create_template_delta_disks(config[:pools][0])
+      end
+    end
+  end
 end