chef-provisioning-vsphere 2.0.2 → 2.0.3

data/lib/chef/provisioning/vsphere_driver/version.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: false
+# Provisions machines in vSphere.
 module ChefProvisioningVsphere
-  VERSION = '2.0.2'.freeze
+  # The version of this awesome Gem. BOOM.
+  VERSION = "2.0.3".freeze
 end

data/lib/chef/provisioning/vsphere_driver/vm_helper.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
-require 'chef/provisioning/driver'
+require "chef/provisioning/driver"
 
+# Provisions machines in vSphere.
 module ChefProvisioningVsphere
   # Helps save data in provisioning a machine
   class VmHelper
     attr_accessor :ip, :port
 
+    # An array of all the known EXCEPTIONS for connecting via Chef-Provisioning-vSphere
     RESCUE_EXCEPTIONS_ON_ESTABLISH = [
       Errno::EACCES, Errno::EADDRINUSE, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
       Errno::ECONNRESET, Errno::ENETUNREACH, Errno::EHOSTUNREACH, Errno::EPIPE,
@@ -14,31 +16,46 @@ module ChefProvisioningVsphere
       Timeout::Error, IPAddr::AddressFamilyError
     ].freeze
 
+    # If the IP is true
+    #
     def ip?
       @ip
     end
 
+    # If the port is true
+    #
     def port?
       @port
     end
 
+    # Finds the port for to connect to the vm
+    #
+    # @param [Object] vm Uses the VM object from Chef provisioning.
+    # @param [Hash] options Uses the VM options from Chef provisioning.
+    # @return [true] The port to connect to the VM whether Windows or *nix.
     def find_port?(vm, options)
       @port = options[:ssh][:port]
       customization_spec = options[:customization_spec]
-      if vm.config.guestId.start_with?('win')
-        unless customization_spec.nil? && customization_spec.is_a?(Hash)
+      if vm.config.guestId.start_with?("win")
+        if customization_spec.is_a?(Hash)
           winrm_transport =
             customization_spec[:winrm_transport].nil? ? :negotiate : customization_spec[:winrm_transport].to_sym
         end
         winrm_transport ||= :negotiate
-        default_win_port = winrm_transport == :ssl ? '5986' : '5985'
+        default_win_port = winrm_transport == :ssl ? "5986" : "5985"
         @port = default_win_port if @port.nil?
       elsif port.nil?
-        @port = '22'
+        @port = "22"
       end
       true
     end
 
+    # Attempt to connects to the open port
+    #
+    # @param [String] host Uses the host string to connect.
+    # @param [String] port Uses the port number to connect.
+    # @param [Integer] timeout The number of seconds before timeout.
+    # @return [true] Returns true when the socket is available to connect.
     def open_port?(host, port, timeout = 5)
       true if ::Socket.tcp(host, port, connect_timeout: timeout)
     rescue *RESCUE_EXCEPTIONS_ON_ESTABLISH

data/lib/chef/provisioning/vsphere_driver/vsphere_helpers.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
-require 'rbvmomi'
-require 'uri'
-require 'net/http'
+require "rbvmomi"
+require "uri"
+require "net/http"
 
+# Provisions machines in vSphere.
 module ChefProvisioningVsphere
+  # A namespace to use for vSphere Helpers
   class VsphereHelper
     $guest_op_managers = {} unless $guest_op_managers
 
@@ -20,6 +22,8 @@ module ChefProvisioningVsphere
     attr_reader :connect_options
     attr_reader :datacenter_name
 
+    # Establishes the connection to the vSphere cluster
+    #
     def vim
       if @current_connection.nil? || @current_connection.serviceContent.sessionManager.currentSession.nil?
         @datacenter = nil
@@ -40,11 +44,18 @@ module ChefProvisioningVsphere
       @current_connection
     end
 
+    # Finds the vm using RbVmomi
+    #
+    # @param [String] folder the folder name for to look into.
+    # @param [String] vm_name the name of the machine.
     def find_vm(folder, vm_name)
       folder = find_folder(folder) unless folder.is_a? RbVmomi::VIM::Folder
       folder.find(vm_name, RbVmomi::VIM::VirtualMachine)
     end
 
+    # Finds the vm using the UUID
+    #
+    # @param [String] uuid the UUID of the machine
     def find_vm_by_id(uuid)
       vm = vim.searchIndex.FindByUuid(
         uuid: uuid,
@@ -53,18 +64,26 @@ module ChefProvisioningVsphere
       )
     end
 
+    # Starts the VM
+    #
+    # @param [Object] vm the main VM object to talk to vSphere.
+    # @param [Object] _wait_on_port Defaults to port 22, to connect and verify it's up.
     def start_vm(vm, _wait_on_port = 22)
       state = vm.runtime.powerState
-      vm.PowerOnVM_Task.wait_for_completion unless state == 'poweredOn'
+      vm.PowerOnVM_Task.wait_for_completion unless state == "poweredOn"
     end
 
+    # Stops the VM
+    #
+    # @param [Object] vm the main VM object to talk to vSphere.
+    # @param [Object] timeout Defaults to 600 seconds or 10 mins before giving up.
     def stop_vm(vm, timeout = 600)
       start = Time.now.utc
       begin
         vm.ShutdownGuest
         until (Time.now.utc - start) > timeout ||
-              vm.runtime.powerState == 'poweredOff'
-          print '.'
+            vm.runtime.powerState == "poweredOff"
+          print "."
           sleep 2
         end
       rescue
@@ -72,18 +91,26 @@ module ChefProvisioningVsphere
       end
     end
 
-    # folder could be like:  /Level1/Level2/folder_name
+    # Find the folder it could be like:  /Level1/Level2/folder_name
+    #
+    # @param [String] folder_name the name of the folder.
+    # @return [Object] base the location of the folder.
     def find_folder(folder_name)
       base = datacenter.vmFolder
       unless folder_name.nil?
-        folder_name.split('/').reject(&:empty?).each do |item|
+        folder_name.split("/").reject(&:empty?).each do |item|
           base = base.find(item, RbVmomi::VIM::Folder) ||
-                 raise("vSphere Folder not found [#{folder_name}]")
+            raise("vSphere Folder not found [#{folder_name}]")
         end
       end
       base
     end
 
+    # Walks through the folders to if needed
+    #
+    # @param [String] folder the name of the folder.
+    # @param [String] dcname the name of the DC.
+    # @return [False] Returns false if not needed.
     def traverse_folders_for_dc(folder, dcname)
       children = folder.children.find_all
       children.each do |child|
@@ -97,6 +124,9 @@ module ChefProvisioningVsphere
       false
     end
 
+    # Connects to the Datacenter and creates Object
+    #
+    # @return [Object] Creates the dc object to know where to create the VMs.
     def datacenter
       vim # ensure connection is valid
       @datacenter ||= begin
@@ -105,6 +135,13 @@ module ChefProvisioningVsphere
       end
     end
 
+    # Creates the network adapter for Rbvmomi
+    #
+    # @param [Object] operation what you need to do to RBvmomi
+    # @param [String] network_name the name of the network the adapter needs to connect to
+    # @param [String] network_label the more verbose name of the network the adapter needs to connect to
+    # @param [String] device_key TODO
+    # @param [String] backing_info TODO
     def network_adapter_for(operation, network_name, network_label, device_key, backing_info)
       connectable = RbVmomi::VIM::VirtualDeviceConnectInfo(
         allowGuestControl: true,
@@ -113,7 +150,7 @@ module ChefProvisioningVsphere
       )
       device = RbVmomi::VIM::VirtualVmxnet3(
         backing: backing_info,
-        deviceInfo: RbVmomi::VIM::Description(label: network_label, summary: network_name.split('/').last),
+        deviceInfo: RbVmomi::VIM::Description(label: network_label, summary: network_name.split("/").last),
         key: device_key,
         connectable: connectable
       )
@@ -123,10 +160,19 @@ module ChefProvisioningVsphere
       )
     end
 
+    # Finds the Network cards from the VM
+    #
+    # @param [Object] vm the VM object to do the query against.
     def find_ethernet_cards_for(vm)
       vm.config.hardware.device.select { |d| d.is_a?(RbVmomi::VIM::VirtualEthernetCard) }
     end
 
+    # Add another NIC to the VM
+    #
+    # @param [Object] action_handler TODO
+    # @param [String] vm_template the Name of the Template to clone
+    # @param [Object] options the options from Chef Provisioning to help configure the VM.
+    # @param [Object] vm the actual VM object to connect the VM to.
     def add_extra_nic(action_handler, vm_template, options, vm)
       deviceAdditions, changes = network_device_changes(action_handler, vm_template, options)
 
@@ -135,7 +181,7 @@ module ChefProvisioningVsphere
         new_devices = deviceAdditions.select { |device| !current_networks.include?(network_id_for(device.device.backing)) }
 
         if new_devices.count > 0
-          action_handler.report_progress 'Adding extra NICs'
+          action_handler.report_progress "Adding extra NICs"
           task = vm.ReconfigVM_Task(spec: RbVmomi::VIM.VirtualMachineConfigSpec(deviceChange: new_devices))
           task.wait_for_completion
           new_devices
@@ -143,6 +189,9 @@ module ChefProvisioningVsphere
       end
     end
 
+    # Gets the network id for a specific thing?
+    #
+    # @param [String] backing_info TODO
     def network_id_for(backing_info)
       if backing_info.is_a?(RbVmomi::VIM::VirtualEthernetCardDistributedVirtualPortBackingInfo)
         backing_info.port.portgroupKey
@@ -151,6 +200,9 @@ module ChefProvisioningVsphere
       end
     end
 
+    # Creates a delta disk for a vm template
+    #
+    # @param [String] vm_template the Name of the Template to clone.
     def create_delta_disk(vm_template)
       disks = vm_template.config.hardware.device.grep(RbVmomi::VIM::VirtualDisk)
       disks.select { |disk| disk.backing.parent.nil? }.each do |disk|
@@ -158,7 +210,7 @@ module ChefProvisioningVsphere
           deviceChange: [
             {
               operation: :remove,
-              device: disk
+              device: disk,
             },
             {
               operation: :add,
@@ -167,14 +219,19 @@ module ChefProvisioningVsphere
                 new_disk.backing = new_disk.backing.dup
                 new_disk.backing.fileName = "[#{disk.backing.datastore.name}]"
                 new_disk.backing.parent = disk.backing
-              end
-            }
-          ]
+              end,
+            },
+          ],
         }
         vm_template.ReconfigVM_Task(spec: spec).wait_for_completion
       end
-      end
+    end
 
+    # Creates a virtual disk for the VM
+    #
+    # @param [Object] vm the VM object.
+    # @param [Subject] datastore the datastore the disk will be created on.
+    # @param [Subject] size_gb the size of the disk.
     def virtual_disk_for(vm, datastore, size_gb)
       idx = vm.disks.count
       RbVmomi::VIM::VirtualDeviceConfigSpec(
@@ -184,7 +241,7 @@ module ChefProvisioningVsphere
           key: idx,
           backing: RbVmomi::VIM.VirtualDiskFlatVer2BackingInfo(
             fileName: "[#{datastore}]",
-            diskMode: 'persistent',
+            diskMode: "persistent",
             thinProvisioned: true
           ),
           capacityInKB: size_gb * 1024 * 1024,
@@ -194,6 +251,11 @@ module ChefProvisioningVsphere
       )
     end
 
+    # Add a new network card via the boot_options
+    #
+    # @param [Object] action_handler TODO
+    # @param [String] vm_template the Name of the Template to clone
+    # @param [Object] options the options from Chef Provisioning to help configure the VM.
     def network_device_changes(action_handler, vm_template, options)
       additions = []
       changes = []
@@ -208,14 +270,14 @@ module ChefProvisioningVsphere
         backing_info = backing_info_for(action_handler, networks[i])
         if card = cards.shift
           key = card.key
-          operation = RbVmomi::VIM::VirtualDeviceConfigSpecOperation('edit')
+          operation = RbVmomi::VIM::VirtualDeviceConfigSpecOperation("edit")
           action_handler.report_progress "changing template nic for #{networks[i]}"
           changes.push(
             network_adapter_for(operation, networks[i], label, key, backing_info)
           )
         else
           key += 1
-          operation = RbVmomi::VIM::VirtualDeviceConfigSpecOperation('add')
+          operation = RbVmomi::VIM::VirtualDeviceConfigSpecOperation("add")
           action_handler.report_progress "will be adding nic for #{networks[i]}"
           additions.push(
             network_adapter_for(operation, networks[i], label, key, backing_info)
@@ -225,8 +287,12 @@ module ChefProvisioningVsphere
       [additions, changes]
     end
 
+    # Discover and identity network names
+    #
+    # @param [Object] action_handler TODO
+    # @param [String] network_name The network name to attach to
     def backing_info_for(action_handler, network_name)
-      action_handler.report_progress('finding networks...')
+      action_handler.report_progress("finding networks...")
       network = find_network(network_name)
       action_handler.report_progress(
         "network: #{network_name} is a #{network.class}"
@@ -241,21 +307,28 @@ module ChefProvisioningVsphere
         )
       else
         RbVmomi::VIM::VirtualEthernetCardNetworkBackingInfo(
-          deviceName: network_name.split('/').last
+          deviceName: network_name.split("/").last
         )
       end
     end
 
+    # Find the datastore name.
+    #
+    # @param [String] datastore_name The datastore name.
     def find_datastore(datastore_name)
       datacenter.datastore.find { |f| f.info.name == datastore_name } || raise("no such datastore #{datastore_name}")
     end
 
+    # Locate the object/vm/whatever in the vSphere cluster
+    #
+    # @param [String] name The name of the "thing."
+    # @param [String] parent_folder The name of the folder to start from.
     def find_entity(name, parent_folder)
-      parts = name.split('/').reject(&:empty?)
+      parts = name.split("/").reject(&:empty?)
       parts.each do |item|
         Chef::Log.debug("Identifying entity part: #{item} in folder type: #{parent_folder.class}")
         if parent_folder.is_a? RbVmomi::VIM::Folder
-          Chef::Log.debug('Parent folder is a folder')
+          Chef::Log.debug("Parent folder is a folder")
           parent_folder = parent_folder.childEntity.find { |f| f.name == item }
         else
           parent_folder = yield(parent_folder, item)
@@ -264,6 +337,9 @@ module ChefProvisioningVsphere
       parent_folder
     end
 
+    # Find the (ESXi) host.
+    #
+    # @param [String] host_name Name of the (ESXi) VM host.
     def find_host(host_name)
       host = find_entity(host_name, datacenter.hostFolder) do |parent, part|
         case parent
@@ -280,6 +356,9 @@ module ChefProvisioningVsphere
       host
     end
 
+    # Find the Resource pool.
+    #
+    # @param [String] pool_name Name of the Resource Pool.
     def find_pool(pool_name)
       Chef::Log.debug("Finding pool: #{pool_name}")
       pool = find_entity(pool_name, datacenter.hostFolder) do |parent, part|
@@ -308,9 +387,12 @@ module ChefProvisioningVsphere
       pool
     end
 
+    # Find the Network name.
+    #
+    # @param [String] name Name of the Network.
     def find_network(name)
       base = datacenter.networkFolder
-      entity_array = name.split('/').reject(&:empty?)
+      entity_array = name.split("/").reject(&:empty?)
       entity_array.each do |item|
         case base
         when RbVmomi::VIM::Folder
@@ -326,6 +408,9 @@ module ChefProvisioningVsphere
       base
     end
 
+    # Locate the Customization Spec in vSphere.
+    #
+    # @param [String] customization_spec The name of the Customization Spec.
     def find_customization_spec(customization_spec)
       csm = vim.serviceContent.customizationSpecManager
       csi = csm.GetCustomizationSpec(name: customization_spec)
@@ -334,6 +419,13 @@ module ChefProvisioningVsphere
       spec
     end
 
+    # Upload a file to the VM using RbVmomi
+    #
+    # @param [Object] vm The VM object.
+    # @param [String] username The username to access the machine.
+    # @param [String] password The password to access the machine.
+    # @param [String] local The local file to upload.
+    # @param [String] remote The remote file to upload location.
     def upload_file_to_vm(vm, username, password, local, remote)
       auth = RbVmomi::VIM::NamePasswordAuthentication(username: username, password: password, interactiveSession: false)
       size = File.size(local)
@@ -353,8 +445,8 @@ module ChefProvisioningVsphere
 
       req = Net::HTTP::Put.new("#{uri.path}?#{uri.query}")
       req.body_stream = File.open(local)
-      req['Content-Type'] = 'application/octet-stream'
-      req['Content-Length'] = size
+      req["Content-Type"] = "application/octet-stream"
+      req["Content-Length"] = size
       res = http.request(req)
       unless res.is_a?(Net::HTTPSuccess)
         raise "Error: #{res.inspect} :: #{res.body} :: sending #{local} to #{remote} at #{vm.name} via #{endpoint} with a size of #{size}"

data/lib/chef/provisioning/vsphere_driver/vsphere_url.rb

@@ -1,46 +1,56 @@
 # frozen_string_literal: false
-require 'uri'
+require "uri"
 
+# The main URI Module
 module URI
+  # Creates the vSphereURL, extended by the Generic Class
   class VsphereUrl < Generic
+    # Default port for connecting to the vSphere cluster Webserver
     DEFAULT_PORT = 443
-    DEFAULT_PATH = '/sdk'.freeze
+    # Default path for connecting to the vSphere cluster URL
+    DEFAULT_PATH = "/sdk".freeze
 
+    # Creates the URL from options that are decided
+    #
     def self.from_config(options)
       parts = []
-      parts << 'vsphere://'
+      parts << "vsphere://"
       parts << options[:host]
-      parts << ':'
+      parts << ":"
       parts << (options[:port] || DEFAULT_PORT)
       parts << (options[:path] || DEFAULT_PATH)
-      parts << '?use_ssl='
+      parts << "?use_ssl="
       parts << (options[:use_ssl] == false ? false : true)
-      parts << '&insecure='
+      parts << "&insecure="
       parts << (options[:insecure] || false)
       URI parts.join
     end
 
+    # Converts URL to SSL if needed
+    #
     def use_ssl
       if query
-        ssl_query = query.split('&').each.select do |q|
-          q.start_with?('use_ssl=')
+        ssl_query = query.split("&").each.select do |q|
+          q.start_with?("use_ssl=")
         end.first
-        ssl_query == 'use_ssl=true'
+        ssl_query == "use_ssl=true"
       else
         true
       end
     end
 
+    # Converts URL to insecure if needed
+    #
     def insecure
       if query
-        insecure_query = query.split('&').each.select do |q|
-          q.start_with?('insecure=')
+        insecure_query = query.split("&").each.select do |q|
+          q.start_with?("insecure=")
         end.first
-        insecure_query == 'insecure=true'
+        insecure_query == "insecure=true"
       else
         false
       end
     end
   end
-  @@schemes['VSPHERE'] = VsphereUrl
+  @@schemes["VSPHERE"] = VsphereUrl
 end