kitchen-vcenter 2.8.6 → 2.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1da356cf16429bae878bc2a5672f2c574c9cd82028914f4aca53d1311955eb4c
-  data.tar.gz: ddf119be74e493604cef87b3cf3d45e2c486492a26eeac5fd5bb6c21ef58a38a
+  metadata.gz: 7c1f638e5648056082f4da2ce087031e468d0bb1113c480af1f04b98496fad5a
+  data.tar.gz: 00d9fd698d02804d4942c1be24802954d5f72ad6cbf97040eecd1d099e959631
 SHA512:
-  metadata.gz: '07824b2bb5850ba139bea24ea65082c602e6e56ea79903a3645ce90d64ff1614e35eeee52ce1dae68670d688be6c9aaec577eab283ac4efb5fcfc4d9da23af1b'
-  data.tar.gz: a3d4f536ad36b3bf666183a607f2ba06a8bbfe9806e2e1917db30b65ec900a808fd69977587df44622e71f9a9ebce3363581c9cc689992f0fa8aac815457f93d
+  metadata.gz: 66e78bad8190b260de8eebcca12051a76452110ad39136e198d1f1c9823dbadbf6698aab4d7e2fe70873fb001f28268f37c5ddec2b72ecc853f6e1d06c77b17a
+  data.tar.gz: 1c60d33094d436b989b503268ce68ef7bd729a0216a848cb6de6d00c65f1ecf1af3dd92fb6913f5104a2c7de225ddc6159ddbd02ee7353c6bf1d4aa4a9357ace

data/lib/kitchen-vcenter/version.rb

@@ -20,5 +20,5 @@
 # The main kitchen-vcenter module
 module KitchenVcenter
   # The version of this version of test-kitchen we assume enterprises want.
-  VERSION = "2.8.6"
+  VERSION = "2.10.2"
 end

data/lib/kitchen/driver/vcenter.rb

@@ -16,6 +16,7 @@
 #
 
 require "kitchen"
+require "rbvmomi"
 require "vsphere-automation-cis"
 require "vsphere-automation-vcenter"
 require_relative "../../kitchen-vcenter/version"
@@ -29,8 +30,17 @@ module Kitchen
   module Driver
     # Extends the Base class for vCenter
     class Vcenter < Kitchen::Driver::Base
+      class UnauthenticatedError < RuntimeError; end
+      class ResourceMissingError < RuntimeError; end
+      class ResourceAmbiguousError < RuntimeError; end
+
       attr_accessor :connection_options, :ipaddress, :api_client
 
+      UNAUTH_CLASSES = [
+        VSphereAutomation::CIS::VapiStdErrorsUnauthenticated,
+        VSphereAutomation::VCenter::VapiStdErrorsUnauthenticated,
+      ].freeze
+
       required_config :vcenter_username
       required_config :vcenter_password
       required_config :vcenter_host
@@ -50,7 +60,7 @@ module Kitchen
       default_config :vm_wait_timeout, 90
       default_config :vm_wait_interval, 2.0
       default_config :vm_rollback, false
-      default_config :customize, nil
+      default_config :vm_customization, nil
       default_config :guest_customization, nil
       default_config :interface, nil
       default_config :active_discovery, false
@@ -80,6 +90,10 @@ module Kitchen
         The 'aggressive_password' setting was renamed to 'vm_password' and will
         be removed in future versions.
       MSG
+      deprecate_config_for :customize, Util.outdent!(<<-MSG)
+        The `customize` setting was renamed to `vm_customization` and will
+        be removed in future versions.
+      MSG
 
       # The main create method
       #
@@ -102,6 +116,7 @@ module Kitchen
             config[:resource_pool] = root_pool
           else
             rp_api = VSphereAutomation::VCenter::ResourcePoolApi.new(api_client)
+            raise_if_unauthenticated rp_api, "checking for resource pools"
 
             found_pool = nil
             pools = rp_api.get(root_pool).value.resource_pools
@@ -110,7 +125,7 @@ module Kitchen
               found_pool = pool if name == config[:resource_pool]
             end
 
-            raise format("Pool %s not found on cluster %s", config[:resource_pool], config[:cluster]) if found_pool.nil?
+            raise_if_missing found_pool, format("Resource pool `%s` not found on cluster `%s`", config[:resource_pool], config[:cluster])
 
             config[:resource_pool] = found_pool
           end
@@ -126,7 +141,6 @@ module Kitchen
         datacenter = get_datacenter(dc_folder, dc_name)
         cluster_id = get_cluster_id(config[:cluster])
 
-        # Using the clone class, create a machine for TK
         # Find the identifier for the targethost to pass to rbvmomi
         config[:targethost] = get_host(config[:targethost], datacenter, cluster_id)
 
@@ -141,13 +155,16 @@ module Kitchen
           }
         end
 
+        # Check for valid tags before cloning
+        vm_tags = map_tags(config[:tags])
+
         # Allow different clone types
         config[:clone_type] = :linked if config[:clone_type] == "linked"
         config[:clone_type] = :instant if config[:clone_type] == "instant"
 
         # Create a hash of options that the clone requires
         options = {
-          name: config[:vm_name],
+          vm_name: config[:vm_name],
           targethost: config[:targethost],
           poweron: config[:poweron],
           template: config[:template],
@@ -159,7 +176,7 @@ module Kitchen
           interface: config[:interface],
           wait_timeout: config[:vm_wait_timeout],
           wait_interval: config[:vm_wait_interval],
-          customize: config[:customize],
+          vm_customization: config[:vm_customization],
           guest_customization: config[:guest_customization],
           active_discovery: config[:active_discovery],
           active_discovery_command: config[:active_discovery_command],
@@ -178,11 +195,11 @@ module Kitchen
           new_vm.clone
 
           state[:hostname] = new_vm.ip
-          state[:vm_name] = new_vm.name
+          state[:vm_name] = new_vm.vm_name
 
         rescue # Kitchen::ActionFailed => e
           if config[:vm_rollback] == true
-            error format("Rolling back VM %s after critical error", config[:vm_name])
+            error format("Rolling back VM `%s` after critical error", config[:vm_name])
 
             # Inject name of failed VM for destroy to work
             state[:vm_name] = config[:vm_name]
@@ -193,31 +210,18 @@ module Kitchen
           raise
         end
 
-        unless config[:tags].nil? || config[:tags].empty?
-          tag_api = VSphereAutomation::CIS::TaggingTagApi.new(api_client)
-          vm_tags = tag_api.list.value
-          raise format("No configured tags found on VCenter, but %s specified", config[:tags].to_s) if vm_tags.empty?
-
-          valid_tags = {}
-          vm_tags.each do |uid|
-            tag = tag_api.get(uid)
-
-            valid_tags[tag.value.name] = tag.value.id if tag.is_a? VSphereAutomation::CIS::CisTaggingTagResult
-          end
-
-          # Error out on undefined tags
-          invalid = config[:tags] - valid_tags.keys
-          raise format("Specified tag(s) %s not valid", invalid.join(",")) unless invalid.empty?
+        if vm_tags
+          debug format("Setting tags on machine: `%s`", vm_tags.keys.join("`, `"))
 
           tag_service = VSphereAutomation::CIS::TaggingTagAssociationApi.new(api_client)
-          tag_ids = config[:tags].map { |name| valid_tags[name] }
+          raise_if_unauthenticated tag_service, "connecting to tagging service"
 
           request_body = {
             object_id: {
               id: get_vm(config[:vm_name]).vm,
               type: "VirtualMachine",
             },
-            tag_ids: tag_ids,
+            tag_ids: vm_tags.values,
           }
           tag_service.attach_multiple_tags_to_object(request_body)
         end
@@ -239,6 +243,7 @@ module Kitchen
         vm = get_vm(state[:vm_name])
         unless vm.nil?
           vm_api = VSphereAutomation::VCenter::VMApi.new(api_client)
+          raise_if_unauthenticated vm_api, "connecting to VM API"
 
           # shut the machine down if it is running
           if vm.power_state == "POWERED_ON"
@@ -280,6 +285,7 @@ module Kitchen
         config[:vm_os] = config[:aggressive_os] unless config[:aggressive_os].nil?
         config[:vm_username] = config[:aggressive_username] unless config[:aggressive_username].nil?
         config[:vm_password] = config[:aggressive_password] unless config[:aggressive_password].nil?
+        config[:vm_customization] = config[:customize] unless config[:customize].nil?
       end
 
       # A helper method to validate the state
@@ -291,17 +297,69 @@ module Kitchen
         state.key?(property) && !state[property].nil?
       end
 
+      # Handle the non-ruby way of the SDK to report errors.
+      #
+      # @param api_response [Object] a generic API response class, which might include an error type
+      # @param message [String] description to output in case of error
+      # @raise UnauthenticatedError
+      def raise_if_unauthenticated(api_response, message)
+        session_id = api_response.api_client.default_headers["vmware-api-session-id"]
+        return unless UNAUTH_CLASSES.include? session_id.class
+
+        message = format("Authentication or permissions error on %s", message)
+        raise UnauthenticatedError.new(message)
+      end
+
+      # Handle missing resources in a query.
+      #
+      # @param collection [Enumerable] list which is supposed to have at least one entry
+      # @param message [String] description to output in case of error
+      # @raise ResourceMissingError
+      def raise_if_missing(collection, message)
+        return unless collection.nil? || collection.empty?
+
+        raise ResourceMissingError.new(message)
+      end
+
+      # Handle ambiguous resources in a query.
+      #
+      # @param collection [Enumerable] list which is supposed to one entry at most
+      # @param message [String] description to output in case of error
+      # @raise ResourceAmbiguousError
+      def raise_if_ambiguous(collection, message)
+        return unless collection.length > 1
+
+        raise ResourceAmbiguousError.new(message)
+      end
+
+      # Access to legacy SOAP based vMOMI API for some functionality
+      #
+      # @return [RbVmomi::VIM] VIM instance
+      def vim
+        @vim ||= RbVmomi::VIM.connect(connection_options)
+      end
+
+      # Search host data via vMOMI
+      #
+      # @param moref [String] identifier of a host system ("host-xxxx")
+      # @return [RbVmomi::VIM::HostSystem]
+      def host_by_moref(moref)
+        vim.serviceInstance.content.hostSpecManager.RetrieveHostSpecification(host: moref, fromHost: false).host
+      end
+
       # Sees in the datacenter exists or not
       #
       # @param [folder] folder is the name of the folder in which the Datacenter is stored in inventory, possibly nil
       # @param [name] name is the name of the datacenter
       def datacenter_exists?(folder, name)
         dc_api = VSphereAutomation::VCenter::DatacenterApi.new(api_client)
+        raise_if_unauthenticated dc_api, "checking for datacenter `#{name}`"
+
         opts = { filter_names: name }
         opts[:filter_folders] = get_folder(folder, "DATACENTER") if folder
         dcs = dc_api.list(opts).value
 
-        raise format("Unable to find data center: %s", name) if dcs.empty?
+        raise_if_missing dcs, format("Unable to find data center `%s`", name)
       end
 
       # Checks if a network exists or not
@@ -309,9 +367,43 @@ module Kitchen
       # @param [name] name is the name of the Network
       def network_exists?(name)
         net_api = VSphereAutomation::VCenter::NetworkApi.new(api_client)
+        raise_if_unauthenticated net_api, "checking for VM network `#{name}`"
+
         nets = net_api.list({ filter_names: name }).value
 
-        raise format("Unable to find target network: %s", name) if nets.empty?
+        raise_if_missing nets, format("Unable to find target network: `%s`", name)
+      end
+
+      # Map VCenter tag names to URNs (VCenter needs tags to be predefined)
+      #
+      # @param tags [tags] tags is the list of tags to associate
+      # @return [Hash] mapping of VCenter tag name to URN
+      # @raise UnauthenticatedError
+      # @raise ResourceMissingError
+      def map_tags(tags)
+        return nil if tags.nil? || tags.empty?
+
+        tag_api = VSphereAutomation::CIS::TaggingTagApi.new(api_client)
+        raise_if_unauthenticated tag_api, "checking for tags"
+
+        vm_tags = tag_api.list.value
+        raise_if_missing vm_tags, format("No configured tags found on VCenter, but `%s` specified", config[:tags].to_s)
+
+        # Create list of all VCenter defined tags, associated with their internal ID
+        valid_tags = {}
+        vm_tags.each do |uid|
+          tag = tag_api.get(uid)
+
+          valid_tags[tag.value.name] = tag.value.id if tag.is_a? VSphereAutomation::CIS::CisTaggingTagResult
+        end
+
+        invalid = config[:tags] - valid_tags.keys
+        unless invalid.empty?
+          message = format("Specified tag(s) `%s` not preconfigured on VCenter", invalid.join("`, `"))
+          raise ResourceMissingError.new(message)
+        end
+
+        valid_tags.select { |tag, _urn| config[:tags].include? tag }
       end
 
       # Validates the host name of the server you can connect to
@@ -320,15 +412,31 @@ module Kitchen
       def get_host(name, datacenter, cluster = nil)
         # create a host object to work with
         host_api = VSphereAutomation::VCenter::HostApi.new(api_client)
+        raise_if_unauthenticated host_api, "checking for target host `#{name || "(any)"}`"
 
         hosts = host_api.list({ filter_names: name,
                                 filter_datacenters: datacenter,
                                 filter_clusters: cluster,
                                 filter_connection_states: ["CONNECTED"] }).value
 
-        raise format("Unable to find target host: %s", name) if hosts.empty?
+        raise_if_missing hosts, format("Unable to find target host `%s`", name || "(any)")
+
+        filter_maintenance!(hosts)
+        raise_if_missing hosts, "Unable to find active target host in datacenter (check maintenance mode?)"
+
+        # Randomize returned hosts
+        host = hosts.sample
+        debug format("Selected host `%s` randomly for deployment", host.name)
 
-        hosts.sample
+        host
+      end
+
+      def filter_maintenance!(hosts)
+        # Exclude hosts which are in maintenance mode (via SOAP API only)
+        hosts.reject! do |hostinfo|
+          host = host_by_moref(hostinfo.host)
+          host.runtime.inMaintenanceMode
+        end
       end
 
       # Gets the folder you want to create the VM
@@ -338,6 +446,8 @@ module Kitchen
       # @param [datacenter] datacenter is the datacenter of the folder
       def get_folder(name, type = "VIRTUAL_MACHINE", datacenter = nil)
         folder_api = VSphereAutomation::VCenter::FolderApi.new(api_client)
+        raise_if_unauthenticated folder_api, "checking for folder `#{name}`"
+
         parent_path, basename = File.split(name)
         filter = { filter_names: basename, filter_type: type }
         filter[:filter_datacenters] = datacenter if datacenter
@@ -345,9 +455,8 @@ module Kitchen
 
         folders = folder_api.list(filter).value
 
-        raise format("Unable to find folder: %s", basename) if folders.empty?
-
-        raise format("`%s` returned too many folders", basename) if folders.length > 1
+        raise_if_missing folders, format("Unable to find VM/template folder: `%s`", basename)
+        raise_if_ambiguous folders, format("`%s` returned too many VM/template folders", basename)
 
         folders.first.folder
       end
@@ -357,8 +466,13 @@ module Kitchen
       # @param [name] name is the name of the VM
       def get_vm(name)
         vm_api = VSphereAutomation::VCenter::VMApi.new(api_client)
+        raise_if_unauthenticated vm_api, "checking for VM `#{name}`"
+
         vms = vm_api.list({ filter_names: name }).value
 
+        raise_if_missing vms, format("Unable to find VM `%s`", name)
+        raise_if_ambiguous vms, format("`%s` returned too many VMs", name)
+
         vms.first
       end
 
@@ -368,13 +482,14 @@ module Kitchen
       # @param [name] name is the name of the Datacenter
       def get_datacenter(folder, name)
         dc_api = VSphereAutomation::VCenter::DatacenterApi.new(api_client)
+        raise_if_unauthenticated dc_api, "checking for datacenter `#{name}` in folder `#{folder}`"
+
         opts = { filter_names: name }
         opts[:filter_folders] = get_folder(folder, "DATACENTER") if folder
         dcs = dc_api.list(opts).value
 
-        raise format("Unable to find data center: %s", name) if dcs.empty?
-
-        raise format("%s returned too many data centers", name) if dcs.length > 1
+        raise_if_missing dcs, format("Unable to find data center: `%s`", name)
+        raise_if_ambiguous dcs, format("`%s` returned too many data centers", name)
 
         dcs.first.datacenter
       end
@@ -386,11 +501,12 @@ module Kitchen
         return if name.nil?
 
         cluster_api = VSphereAutomation::VCenter::ClusterApi.new(api_client)
-        clusters = cluster_api.list({ filter_names: name }).value
+        raise_if_unauthenticated cluster_api, "checking for ID of cluster `#{name}`"
 
-        raise format("Unable to find Cluster: %s", name) if clusters.empty?
+        clusters = cluster_api.list({ filter_names: name }).value
 
-        raise format("%s returned too many clusters", name) if clusters.length > 1
+        raise_if_missing clusters, format("Unable to find Cluster: `%s`", name)
+        raise_if_ambiguous clusters, format("`%s` returned too many clusters", name)
 
         clusters.first.cluster
       end
@@ -402,9 +518,11 @@ module Kitchen
         cluster_id = get_cluster_id(name)
 
         host_api = VSphereAutomation::VCenter::HostApi.new(api_client)
-        hosts = host_api.list({ filter_clusters: cluster_id, connection_states: "CONNECTED" }).value
+        raise_if_unauthenticated host_api, "checking for cluster `#{name}`"
 
-        raise format("Unable to find active host in cluster %s", name) if hosts.empty?
+        hosts = host_api.list({ filter_clusters: cluster_id, connection_states: "CONNECTED" }).value
+        filter_maintenance!(hosts)
+        raise_if_missing hosts, format("Unable to find active hosts in cluster `%s`", name)
 
         cluster_api = VSphereAutomation::VCenter::ClusterApi.new(api_client)
         cluster_api.get(cluster_id).value
@@ -417,6 +535,7 @@ module Kitchen
       def get_resource_pool(name)
         # Create a resource pool object
         rp_api = VSphereAutomation::VCenter::ResourcePoolApi.new(api_client)
+        raise_if_unauthenticated rp_api, "checking for resource pool `#{name || "(default)"}`"
 
         # If no name has been set, use the first resource pool that can be found,
         # otherwise try to find by given name
@@ -441,7 +560,7 @@ module Kitchen
           debug("Search for resource pools found: " + resource_pools.map(&:name).to_s)
         end
 
-        raise format("Unable to find Resource Pool: %s", name) if resource_pools.empty?
+        raise_if_missing resource_pools, format("Unable to find resource pool `%s`", name || "(default)")
 
         resource_pools.first.resource_pool
       end

data/lib/support/clone_vm.rb

@@ -1,20 +1,25 @@
 require "kitchen"
 require "rbvmomi"
+
+require_relative "guest_customization"
 require_relative "guest_operations"
 
 class Support
   class CloneError < RuntimeError; end
 
   class CloneVm
-    attr_reader :vim, :options, :ssl_verify, :vm, :name, :ip, :guest_auth, :username
+    attr_reader :vim, :vem, :options, :ssl_verify, :src_vm, :vm, :vm_name, :ip, :guest_auth, :username
+
+    include GuestCustomization
 
     def initialize(conn_opts, options)
       @options = options
-      @name = options[:name]
+      @vm_name = options[:vm_name]
       @ssl_verify = !conn_opts[:insecure]
 
       # Connect to vSphere
       @vim ||= RbVmomi::VIM.connect conn_opts
+      @vem ||= vim.serviceContent.eventManager
 
       @username = options[:vm_username]
       password = options[:vm_password]
@@ -156,8 +161,8 @@ class Support
       Kitchen.logger.debug format("Benchmark: Appended data to file %s", benchmark_file)
     end
 
-    def detect_os
-      vm.config&.guestId&.match(/^win/) ? :windows : :linux
+    def detect_os(vm_or_template)
+      vm_or_template.config&.guestId&.match(/^win/) ? :windows : :linux
     end
 
     def windows?
@@ -318,14 +323,14 @@ class Support
       end
     end
 
-    def reconfigure_guest
-      Kitchen.logger.info "Waiting for reconfiguration to finish"
+    def vm_customization
+      Kitchen.logger.info "Waiting for VM customization..."
 
       # Pass some contents right through
       # https://pubs.vmware.com/vsphere-6-5/index.jsp?topic=%2Fcom.vmware.wssdk.smssdk.doc%2Fvim.vm.ConfigSpec.html
-      config = options[:customize].select { |key, _| %i{annotation memoryMB numCPUs}.include? key }
+      config = options[:vm_customization].select { |key, _| %i{annotation memoryMB numCPUs}.include? key }
 
-      add_disks = options[:customize]&.fetch(:add_disks, nil)
+      add_disks = options[:vm_customization]&.fetch(:add_disks, nil)
       unless add_disks.nil?
         config[:deviceChange] = []
 
@@ -438,86 +443,16 @@ class Support
       false
     end
 
-    def customization_spec
-      unless options[:guest_customization]
-        return false
-      end
-
-      if options[:guest_customization][:ip_address]
-        unless ip?(options[:guest_customization][:ip_address])
-          raise Support::CloneError.new("Guest customization error: ip_address is required to be formatted as an IPv4 address")
-        end
-
-        unless options[:guest_customization][:subnet_mask]
-          raise Support::CloneError.new("Guest customization error: subnet_mask is required if assigning a fixed IPv4 address")
-        end
-
-        unless ip?(options[:guest_customization][:subnet_mask])
-          raise Support::CloneError.new("Guest customization error: subnet_mask is required to be formatted as an IPv4 address")
-        end
-      end
+    def vm_events(event_types = [])
+      raise Support::CloneError.new("`vm_events` called before VM clone") unless vm
 
-      if options[:guest_customization][:gateway]
-        unless options[:guest_customization][:gateway].is_a?(Array)
-          raise Support::CloneError.new("Guest customization error: gateway must be an array")
-        end
-
-        options[:guest_customization][:gateway].each do |v|
-          unless ip?(v)
-            raise Support::CloneError.new("Guest customization error: gateway is required to be formatted as an IPv4 address")
-          end
-        end
-      end
-
-      required = %i{dns_domain timezone dns_server_list dns_suffix_list}
-      missing = required - options[:guest_customization].keys
-      unless missing.empty?
-        raise Support::CloneError.new("Guest customization error: #{missing.join(", ")} are required to support guest customization")
-      end
-
-      options[:guest_customization][:dns_server_list].each do |v|
-        unless ip?(v)
-          raise Support::CloneError.new("Guest customization error: dns_server_list is required to be formatted as an IPv4 address")
-        end
-      end
-
-      if !options[:guest_customization][:dns_server_list].is_a?(Array)
-        raise Support::CloneError.new("Guest customization error: dns_server_list must be an array")
-      elsif !options[:guest_customization][:dns_suffix_list].is_a?(Array)
-        raise Support::CloneError.new("Guest customization error: dns_suffix_list must be an array")
-      end
-
-      if options[:guest_customization][:ip_address]
-        customized_ip = RbVmomi::VIM::CustomizationIPSettings.new(
-          ip: RbVmomi::VIM::CustomizationFixedIp(ipAddress: options[:guest_customization][:ip_address]),
-          gateway: options[:guest_customization][:gateway],
-          subnetMask: options[:guest_customization][:subnet_mask],
-          dnsDomain: options[:guest_customization][:dns_domain]
-        )
-      else
-        customized_ip = RbVmomi::VIM::CustomizationIPSettings.new(
-          ip: RbVmomi::VIM::CustomizationDhcpIpGenerator.new,
-          dnsDomain: options[:guest_customization][:dns_domain]
-        )
-      end
-
-      RbVmomi::VIM::CustomizationSpec.new(
-        identity: RbVmomi::VIM::CustomizationLinuxPrep.new(
-          domain: options[:guest_customization][:dns_domain],
-          hostName: RbVmomi::VIM::CustomizationFixedName.new(
-            name: name
-          ),
-          hwClockUTC: true,
-          timeZone: options[:guest_customization][:timezone]
-        ),
-        globalIPSettings: RbVmomi::VIM::CustomizationGlobalIPSettings.new(
-          dnsServerList: options[:guest_customization][:dns_server_list],
-          dnsSuffixList: options[:guest_customization][:dns_suffix_list]
+      vem.QueryEvents(filter: RbVmomi::VIM::EventFilterSpec(
+        entity: RbVmomi::VIM::EventFilterSpecByEntity(
+          entity: vm,
+          recursion: RbVmomi::VIM::EventFilterSpecRecursionOption(:self)
         ),
-        nicSettingMap: [RbVmomi::VIM::CustomizationAdapterMapping.new(
-          adapter: customized_ip
-        )]
-      )
+        eventTypeId: event_types
+      ))
     end
 
     def clone
@@ -526,12 +461,9 @@ class Support
       # set the datacenter name
       dc = find_datacenter
 
-      # get guest customization spec
-      guest_customization = customization_spec
-
       # reference template using full inventory path
       inventory_path = format("/%s/vm/%s", datacenter, options[:template])
-      src_vm = root_folder.findByInventoryPath(inventory_path)
+      @src_vm = root_folder.findByInventoryPath(inventory_path)
       raise Support::CloneError.new(format("Unable to find template: %s", options[:template])) if src_vm.nil?
 
       if src_vm.config.template && !full_clone?
@@ -544,6 +476,13 @@ class Support
         options[:clone_type] = :full
       end
 
+      # Autodetect OS, if none given
+      if options[:vm_os].nil?
+        os = detect_os(src_vm)
+        Kitchen.logger.debug format('OS for VM not configured, got "%s" from VMware', os.to_s.capitalize)
+        options[:vm_os] = os
+      end
+
       # Specify where the machine is going to be created
       relocate_spec = RbVmomi::VIM.VirtualMachineRelocateSpec
 
@@ -642,23 +581,21 @@ class Support
         ]
 
         clone_spec = RbVmomi::VIM.VirtualMachineInstantCloneSpec(location: relocate_spec,
-                                                                 name: name)
+                                                                 name: vm_name)
 
         benchmark_checkpoint("initialized") if benchmark?
         task = src_vm.InstantClone_Task(spec: clone_spec)
       else
         clone_spec = RbVmomi::VIM.VirtualMachineCloneSpec(
           location: relocate_spec,
-          powerOn: options[:poweron] && options[:customize].nil?,
+          powerOn: options[:poweron] && options[:vm_customization].nil?,
           template: false
         )
 
-        if guest_customization
-          clone_spec.customization = guest_customization
-        end
+        clone_spec.customization = guest_customization_spec if options[:guest_customization]
 
         benchmark_checkpoint("initialized") if benchmark?
-        task = src_vm.CloneVM_Task(spec: clone_spec, folder: dest_folder, name: name)
+        task = src_vm.CloneVM_Task(spec: clone_spec, folder: dest_folder, name: vm_name)
       end
       task.wait_for_completion
 
@@ -666,31 +603,28 @@ class Support
 
       # get the IP address of the machine for bootstrapping
       # machine name is based on the path, e.g. that includes the folder
-      path = options[:folder].nil? ? name : format("%s/%s", options[:folder][:name], name)
+      path = options[:folder].nil? ? vm_name : format("%s/%s", options[:folder][:name], vm_name)
       @vm = dc.find_vm(path)
       raise Support::CloneError.new(format("Unable to find machine: %s", path)) if vm.nil?
 
-      if options[:vm_os].nil?
-        os = detect_os
-        Kitchen.logger.debug format('OS for VM not configured, got "%s" from VMware', os.to_s.capitalize)
-        options[:vm_os] = os
-      end
-
       # Reconnect network device after Instant Clone is ready
       if instant_clone?
         Kitchen.logger.info "Reconnecting network adapter"
         reconnect_network_device(vm)
       end
 
-      reconfigure_guest unless options[:customize].nil?
+      vm_customization if options[:vm_customization]
 
       # Start only if specified or customizations wanted; no need for instant clones as they start in running state
-      if options[:poweron] && !options[:customize].nil? && !instant_clone?
+      if options[:poweron] && !options[:vm_customization].nil? && !instant_clone?
         task = vm.PowerOnVM_Task
         task.wait_for_completion
       end
       benchmark_checkpoint("powered_on") if benchmark?
 
+      # Windows customization takes a while, so check for its completion
+      guest_customization_wait if options[:guest_customization]
+
       Kitchen.logger.info format("Waiting for VMware tools to become available (timeout: %d seconds)...", options[:wait_timeout])
       wait_for_tools(options[:wait_timeout], options[:wait_interval])
 
@@ -698,7 +632,7 @@ class Support
       benchmark_checkpoint("ip_detected") if benchmark?
 
       benchmark_persist if benchmark?
-      Kitchen.logger.info format("Created machine %s with IP %s", name, ip)
+      Kitchen.logger.info format("Created machine %s with IP %s", vm_name, ip)
     end
   end
 end

data/lib/support/guest_customization.rb

@@ -0,0 +1,336 @@
+require "net/ping"
+require "rbvmomi"
+
+class Support
+  class GuestCustomizationError < RuntimeError; end
+  class GuestCustomizationOptionsError < RuntimeError; end
+
+  module GuestCustomization
+    DEFAULT_LINUX_TIMEZONE = "Etc/UTC".freeze
+    DEFAULT_WINDOWS_ORG = "TestKitchen".freeze
+    DEFAULT_WINDOWS_TIMEZONE = 0x80000050 # Etc/UTC
+    DEFAULT_TIMEOUT_TASK = 600
+    DEFAULT_TIMEOUT_IP = 60
+
+    # Generic Volume License Keys for temporary Windows Server setup.
+    #
+    # @see https://docs.microsoft.com/en-us/windows-server/get-started/kmsclientkeys
+    WINDOWS_KMS_KEYS = {
+      "Microsoft Windows Server 2019 (64-bit)" => "N69G4-B89J2-4G8F4-WWYCC-J464C",
+      "Microsoft Windows Server 2016 (64-bit)" => "WC2BQ-8NRM3-FDDYY-2BFGV-KHKQY",
+      "Microsoft Windows Server 2012R2 (64-bit)" => "D2N9P-3P6X9-2R39C-7RTCD-MDVJX",
+      "Microsoft Windows Server 2012 (64-bit)" => "BN3D2-R7TKB-3YPBD-8DRP2-27GG4",
+    }.freeze
+
+    # Configuration values for Guest Customization
+    #
+    # @returns [Hash] Configuration values from file
+    def guest_customization
+      options[:guest_customization]
+    end
+
+    # Build CustomizationSpec for Guest OS Customization
+    #
+    # @returns [RbVmomi::VIM::CustomizationSpec] Customization Spec for guest adjustments
+    def guest_customization_spec
+      return unless guest_customization
+
+      guest_customization_validate_options
+
+      if guest_customization[:ip_address]
+        customized_ip = RbVmomi::VIM::CustomizationIPSettings.new(
+          ip: RbVmomi::VIM::CustomizationFixedIp(ipAddress: guest_customization[:ip_address]),
+          gateway: guest_customization[:gateway],
+          subnetMask: guest_customization[:subnet_mask],
+          dnsDomain: guest_customization[:dns_domain]
+        )
+      else
+        customized_ip = RbVmomi::VIM::CustomizationIPSettings.new(
+          ip: RbVmomi::VIM::CustomizationDhcpIpGenerator.new,
+          dnsDomain: guest_customization[:dns_domain]
+        )
+      end
+
+      RbVmomi::VIM::CustomizationSpec.new(
+        identity: guest_customization_identity,
+        globalIPSettings: RbVmomi::VIM::CustomizationGlobalIPSettings.new(
+          dnsServerList: guest_customization[:dns_server_list],
+          dnsSuffixList: guest_customization[:dns_suffix_list]
+        ),
+        nicSettingMap: [RbVmomi::VIM::CustomizationAdapterMapping.new(
+          adapter: customized_ip
+        )]
+      )
+    end
+
+    # Check options for existance and format
+    #
+    # @raise [Support::GuestCustomizationOptionsError] For any violation
+    def guest_customization_validate_options
+      if guest_customization_ip_change?
+        unless ip?(guest_customization[:ip_address])
+          raise Support::GuestCustomizationOptionsError.new("Parameter `ip_address` is required to be formatted as an IPv4 address")
+        end
+
+        unless guest_customization[:subnet_mask]
+          raise Support::GuestCustomizationOptionsError.new("Parameter `subnet_mask` is required if assigning a fixed IPv4 address")
+        end
+
+        unless ip?(guest_customization[:subnet_mask])
+          raise Support::GuestCustomizationOptionsError.new("Parameter `subnet_mask` is required to be formatted as an IPv4 address")
+        end
+
+        if up?(guest_customization[:ip_address])
+          raise Support::GuestCustomizationOptionsError.new("Parameter `ip_address` points to a host reachable via ICMP") unless guest_customization[:continue_on_ip_conflict]
+
+          Kitchen.logger.warn("Continuing customization despite `ip_address` conflicting with a reachable host per user request")
+        end
+      end
+
+      if guest_customization[:gateway]
+        unless guest_customization[:gateway].is_a?(Array)
+          raise Support::GuestCustomizationOptionsError.new("Parameter `gateway` must be an array")
+        end
+
+        guest_customization[:gateway].each do |v|
+          unless ip?(v)
+            raise Support::GuestCustomizationOptionsError.new("Parameter `gateway` is required to be formatted as an IPv4 address")
+          end
+        end
+      end
+
+      required = %i{dns_domain dns_server_list dns_suffix_list}
+      missing = required - guest_customization.keys
+      unless missing.empty?
+        raise Support::GuestCustomizationOptionsError.new("Parameters `#{missing.join("`, `")}` are required to support guest customization")
+      end
+
+      guest_customization[:dns_server_list].each do |v|
+        unless ip?(v)
+          raise Support::GuestCustomizationOptionsError.new("Parameter `dns_server_list` is required to be formatted as an IPv4 address")
+        end
+      end
+
+      if !guest_customization[:dns_server_list].is_a?(Array)
+        raise Support::GuestCustomizationOptionsError.new("Parameter `dns_server_list` must be an array")
+      elsif !guest_customization[:dns_suffix_list].is_a?(Array)
+        raise Support::GuestCustomizationOptionsError.new("Parameter `dns_suffix_list` must be an array")
+      end
+    end
+
+    # Check if an IP change is requested
+    #
+    # @returns [Boolean] If `ip_address` is to be changed
+    def guest_customization_ip_change?
+      guest_customization[:ip_address]
+    end
+
+    # Return OS-specific CustomizationIdentity object
+    def guest_customization_identity
+      if linux?
+        guest_customization_identity_linux
+      elsif windows?
+        guest_customization_identity_windows
+      else
+        raise Support::GuestCustomizationError.new("Unknown OS, no valid customization found")
+      end
+    end
+
+    # Construct Linux-specific customization information
+    def guest_customization_identity_linux
+      timezone = guest_customization[:timezone]
+      if timezone && !valid_linux_timezone?(timezone)
+        raise Support::GuestCustomizationError.new <<~ERROR
+          Linux customization requires `timezone` in `Area/Location` format.
+          See https://kb.vmware.com/s/article/2145518
+        ERROR
+      end
+
+      Kitchen.logger.warn("Linux guest customization: No timezone passed, assuming UTC") unless timezone
+
+      RbVmomi::VIM::CustomizationLinuxPrep.new(
+        domain: guest_customization[:dns_domain],
+        hostName: guest_hostname,
+        hwClockUTC: true,
+        timeZone: timezone || DEFAULT_LINUX_TIMEZONE
+      )
+    end
+
+    # Construct Windows-specific customization information
+    def guest_customization_identity_windows
+      timezone = guest_customization[:timezone]
+      if timezone && !valid_windows_timezone?(timezone)
+        raise Support::GuestCustomizationOptionsError.new <<~ERROR
+          Windows customization requires `timezone` as decimal number or hex number (0x55).
+          See https://support.microsoft.com/en-us/help/973627/microsoft-time-zone-index-values
+        ERROR
+      end
+
+      Kitchen.logger.warn("Windows guest customization: No timezone passed, assuming UTC") unless timezone
+
+      product_id = guest_customization[:product_id]
+
+      # Try to look up and use a known, documented 120-day trial key
+      unless product_id
+        guest_os = src_vm.guest&.guestFullName
+        product_id = windows_kms_for_guest(guest_os)
+
+        Kitchen.logger.warn format("Windows guest customization:: Using KMS Key `%<key>s` for %<os>s", key: product_id, os: guest_os) if product_id
+      end
+
+      unless valid_windows_key? product_id
+        raise Support::GuestCustomizationOptionsError.new <<~ERROR
+          Windows customization requires `product_id` to work. Add a valid product key or
+          see https://docs.microsoft.com/en-us/windows-server/get-started/kmsclientkeys for KMS trial keys
+        ERROR
+      end
+
+      customization_pass = nil
+      if guest_customization[:administrator_password]
+        customization_pass = RbVmomi::VIM::CustomizationPassword.new(
+          plainText: true,
+          value: guest_customization[:administrator_password]
+        )
+      end
+
+      RbVmomi::VIM::CustomizationSysprep.new(
+        guiUnattended: RbVmomi::VIM::CustomizationGuiUnattended.new(
+          timeZone: timezone.to_i || DEFAULT_WINDOWS_TIMEZONE,
+          autoLogon: false,
+          autoLogonCount: 1,
+          password: customization_pass
+        ),
+        identification: RbVmomi::VIM::CustomizationIdentification.new,
+        userData: RbVmomi::VIM::CustomizationUserData.new(
+          computerName: guest_hostname,
+          fullName: guest_customization[:org_name] || DEFAULT_WINDOWS_ORG,
+          orgName: guest_customization[:org_name] || DEFAULT_WINDOWS_ORG,
+          productId: product_id
+        )
+      )
+    end
+
+    # Check if a host is reachable
+    def up?(host)
+      check = Net::Ping::External.new(host)
+      check.ping?
+    end
+
+    # Retrieve a GVLK (evaluation key) for the named OS
+    #
+    # @param [String] name Name of the OS as reported by VMware
+    # @returns [String] GVLK key, if any
+    def windows_kms_for_guest(name)
+      WINDOWS_KMS_KEYS.fetch(name, false)
+    end
+
+    # Check format of Linux-specific timezone, according to VMware support
+    #
+    # @param [Integer] input Value to check for validity
+    # @returns [Boolean] if value is valid
+    def valid_linux_timezone?(input)
+      # Specific to VMware: https://kb.vmware.com/s/article/2145518
+      linux_timezone_pattern = %r{^[A-Z][A-Za-z]+\/[A-Z][-_+A-Za-z0-9]+$}
+
+      input.to_s.match? linux_timezone_pattern
+    end
+
+    # Check format of Windows-specific timezone
+    #
+    # @param [Integer] input Value to check for validity
+    # @returns [Boolean] if value is valid
+    def valid_windows_timezone?(input)
+      # Accept decimals and hex
+      # See https://support.microsoft.com/en-us/help/973627/microsoft-time-zone-index-values
+      windows_timezone_pattern = /^([0-9]+|0x[0-9a-fA-F]+)$/
+
+      input.to_s.match? windows_timezone_pattern
+    end
+
+    # Check for format of Windows Product IDs
+    #
+    # @param [String] input String to check
+    # @returns [Boolean] if value is in Windows Key format
+    def valid_windows_key?(input)
+      windows_key_pattern = /^[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}$/
+
+      input.to_s.match? windows_key_pattern
+    end
+
+    # Return Guest hostname to be configured and check for validity.
+    #
+    # @returns [String] New hostname to assign
+    def guest_hostname
+      hostname = guest_customization[:hostname] || options[:vm_name]
+
+      hostname_pattern = /^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])$/
+      unless hostname.match?(hostname_pattern)
+        raise Support::GuestCustomizationError.new("Only letters, numbers or hyphens in hostnames allowed")
+      end
+
+      RbVmomi::VIM::CustomizationFixedName.new(name: hostname)
+    end
+
+    # Wait for vSphere task completion and subsequent IP address update (if any).
+    def guest_customization_wait
+      guest_customization_wait_task(guest_customization[:timeout_task] || DEFAULT_TIMEOUT_TASK)
+      guest_customization_wait_ip(guest_customization[:timeout_ip] || DEFAULT_TIMEOUT_IP)
+    end
+
+    # Wait for Guest customization to finish successfully.
+    #
+    # @param [Integer] timeout Timeout in seconds
+    # @param [Integer] sleep_time Time to wait between tries
+    def guest_customization_wait_task(timeout = 600, sleep_time = 10)
+      waited_seconds = 0
+
+      Kitchen.logger.info "Waiting for guest customization (timeout: #{timeout} seconds)..."
+
+      while waited_seconds < timeout
+        events = guest_customization_events
+
+        if events.any? { |event| event.is_a? RbVmomi::VIM::CustomizationSucceeded }
+          return
+        elsif (failed = events.detect { |event| event.is_a? RbVmomi::VIM::CustomizationFailed })
+          # Only matters for Linux, as Windows won't come up at all to report a failure via VMware Tools
+          raise Support::GuestCustomizationError.new("Customization of VM failed: #{failed.fullFormattedMessage}")
+        end
+
+        sleep(sleep_time)
+        waited_seconds += sleep_time
+      end
+
+      raise Support::GuestCustomizationError.new("Customization of VM did not complete within #{timeout} seconds.")
+    end
+
+    # Wait for new IP to be reported, if any.
+    #
+    # @param [Integer] timeout Timeout in seconds. Tools report every 30 seconds, Default: 30 seconds
+    # @param [Integer] sleep_time Time to wait between tries
+    def guest_customization_wait_ip(timeout = 30, sleep_time = 1)
+      return unless guest_customization_ip_change?
+
+      waited_seconds = 0
+
+      Kitchen.logger.info "Waiting for guest customization IP update..."
+
+      while waited_seconds < timeout
+        found_ip = wait_for_ip(timeout, 1.0)
+
+        return if found_ip == guest_customization[:ip_address]
+
+        sleep(sleep_time)
+        waited_seconds += sleep_time
+      end
+
+      raise Support::GuestCustomizationError.new("Customized IP was not reported within #{timeout} seconds.")
+    end
+
+    # Filter Customization events for the current VM
+    #
+    # @returns [Array<RbVmomi::VIM::CustomizationEvent>] All matching events
+    def guest_customization_events
+      vm_events %w{CustomizationSucceeded CustomizationFailed CustomizationStartedEvent}
+    end
+  end
+end

metadata

@@ -1,15 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-vcenter
 version: !ruby/object:Gem::Version
-  version: 2.8.6
+  version: 2.10.2
 platform: ruby
 authors:
 - Chef Software
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-22 00:00:00.000000000 Z
+date: 2021-08-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-ping
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rbvmomi
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +59,7 @@ dependencies:
         version: '1.16'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,7 +69,7 @@ dependencies:
         version: '1.16'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: vsphere-automation-sdk
   requirement: !ruby/object:Gem::Requirement
@@ -75,6 +95,7 @@ files:
 - lib/kitchen-vcenter/version.rb
 - lib/kitchen/driver/vcenter.rb
 - lib/support/clone_vm.rb
+- lib/support/guest_customization.rb
 - lib/support/guest_operations.rb
 homepage: https://github.com/chef/kitchen-vcenter
 licenses:
@@ -88,15 +109,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
-summary: Test Kitchen driver for VMare vCenter
+summary: Test Kitchen driver for VMware vCenter
 test_files: []