kitchen-google 3.0.1 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b723b02e719da68e14ea28e557e7288ebf83e3f7770fe26b7a24c67b5edfa2a
-  data.tar.gz: 7fc550f1fa2ee2ef1803849c04ed561eeb8417ea34c7a9dec37a336d02223d90
+  metadata.gz: 915d1d94065a49854c4c040df37b17d4a1e6853bbffd4872bb6e94d255e070bf
+  data.tar.gz: ab9bbf5503260572daf07e281d7087db57110b27ef25fc47f1879cfcc8a1e75d
 SHA512:
-  metadata.gz: 619b786dc4939d75e666676eace51b0b87623ee800333e9569bd3ccc31204773badc2d5bcb449e2e9852faec5dc1cce997fd7d83dae58c07bb2651f265769081
-  data.tar.gz: e260b90a3249fe4f5de2469e9777b0f6a6a3e8c21cb86989c8470ee575d17155b7505df325f792321f91d098549278cf368026ff6275dee369c56be26cfc904c
+  metadata.gz: ddba9a545b204a39596ed608a310e6714976bb1553af5ab18df6fb4bb135f323c18e5cba31097f7ecb603f1366bef4cfbd03c70b761904b26d16183db47d1b39
+  data.tar.gz: 66f9605d7a1c529939b3aa1fe0ea375bb1eac6a9689b5ea6cc6427d8f70bf8fdfed63f245f6daab76bca11ef228b52c2e62a989faf1c143ca8511e719f8b1b5b

data/lib/kitchen/driver/gce.rb

@@ -21,6 +21,7 @@ require "kitchen"
 require_relative "gce_version"
 require_relative "gce/windows_password"
 require "securerandom" unless defined?(SecureRandom)
+require "time" unless defined?(Time.iso8601)
 require "timeout" unless defined?(Timeout)
 
 module Kitchen
@@ -43,6 +44,12 @@ module Kitchen
       # @return [Hash] the Test Kitchen state hash for the action in progress
       attr_accessor :state
 
+      # @!method state=(value)
+      #   Stores the Test Kitchen state hash for the action in progress.
+      #
+      #   @param value [Hash] the state hash to expose to the helper methods
+      #   @return [Hash] the assigned state hash
+
       # Maps the short scope aliases accepted by `gcloud` onto the scope
       # segment of their fully-qualified OAuth 2.0 URL.
       #
@@ -89,7 +96,10 @@ module Kitchen
       default_config :tags, []
       default_config :preemptible, false
       default_config :auto_restart, false
-      default_config :auto_migrate, false
+      # Matches GCE's own default for onHostMaintenance. Several machine
+      # families, E2 among them, reject TERMINATE unless the instance is
+      # preemptible, so defaulting this off makes them unusable.
+      default_config :auto_migrate, true
       default_config :image_family, nil
       default_config :image_name, nil
       default_config :image_project, nil
@@ -102,10 +112,18 @@ module Kitchen
       default_config :metadata, {}
       default_config :labels, {}
 
+      # Pattern a GCE resource name must match in full. GCE applies the same
+      # pattern to instance names and disk names alike.
+      #
+      # @return [Regexp] the permitted name pattern
+      RESOURCE_NAME_REGEX = /(?:[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)/
+
       # Pattern a GCE disk name must match in full.
       #
+      # @deprecated Use {RESOURCE_NAME_REGEX}, which is the same pattern and
+      #   says what it actually covers.
       # @return [Regexp] the permitted disk-name pattern
-      DISK_NAME_REGEX = /(?:[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)/
+      DISK_NAME_REGEX = RESOURCE_NAME_REGEX
 
       # Longest instance name GCE accepts.
       #
@@ -138,6 +156,22 @@ module Kitchen
         disk_size: 10,
       }.freeze
 
+      # Local Windows account Test Kitchen's WinRM transport defaults to, and
+      # which Google's Windows images ship disabled.
+      #
+      # @return [String] the built-in administrator account name
+      BUILTIN_ADMINISTRATOR = "administrator".freeze
+
+      # Told to the user when they are about to wait out a WinRM timeout for a
+      # reason the driver can see coming.
+      #
+      # @return [String] the warning text
+      BUILTIN_ADMINISTRATOR_WARNING =
+        "The WinRM transport is connecting as the built-in Administrator account, which is " \
+        "disabled on Google's Windows images. The guest agent resets its password without " \
+        "enabling it, so the login will be refused. Set transport.username to any other name " \
+        "and the agent will create that account instead.".freeze
+
       # Human-readable driver name shown in Test Kitchen output.
       #
       # @return [String] the driver's display name
@@ -154,7 +188,8 @@ module Kitchen
       # before the error is re-raised.
       #
       # @param state [Hash] the Test Kitchen state hash, mutated in place with
-      #   `:server_name`, `:hostname` and `:zone`
+      #   `:server_name`, `:hostname`, `:zone` and `:created_disks`, plus
+      #   `:password` for Windows guests
       # @return [void]
       # @raise [StandardError] if instance creation fails for any reason
       def create(state)
@@ -163,19 +198,31 @@ module Kitchen
 
         validate!
 
+        # The disk configuration has to be settled first: the instance name is
+        # budgeted against the longest disk name derived from it.
+        create_disks_config
+
         server_name = generate_server_name
 
-        create_disks_config
+        # Pin the zone before anything billable exists. In region mode it is
+        # picked at random, so cleanup would otherwise have no way to know
+        # where to look for the disks created below.
+        state[:zone] = zone
+
+        # Record the name before the request goes out, not after it returns.
+        # GCE starts billing as soon as the insert is accepted, and it may
+        # accept one whose response never reaches us -- an interrupted or
+        # timed-out request can leave an instance running that the state file
+        # knows nothing about, holding disks that cleanup then cannot delete.
+        # `destroy` copes with a name that never became an instance.
+        state[:server_name] = server_name
 
         info("Creating GCE instance <#{server_name}> in project #{project}, zone #{zone}...")
         operation = connection.insert_instance(project, zone, create_instance_object(server_name))
 
         wait_for_operation(operation)
 
-        server              = server_instance(server_name)
-        state[:server_name] = server_name
-        state[:hostname]    = ip_address_for(server)
-        state[:zone]        = zone
+        state[:hostname] = ip_address_for(server_instance(server_name))
 
         info("Server <#{server_name}> created.")
 
@@ -197,33 +244,101 @@ module Kitchen
         raise
       end
 
-      # Destroys the GCE instance recorded in the state file.
+      # Destroys the GCE instance recorded in the state file, together with any
+      # standalone disks an earlier create left behind.
       #
-      # Does nothing when the state file records no server, or when the
-      # instance no longer exists in GCE.
+      # An instance that no longer exists in GCE is treated as already
+      # destroyed, but the state file is still cleared: a create that fails
+      # after `insert_instance` records a server that may never have come into
+      # being, and leaving the name behind would make {#create}'s idempotency
+      # guard skip every subsequent retry.
+      #
+      # Disks are deleted after the instance, which holds them until it is
+      # gone. A create interrupted before it reached `insert_instance` records
+      # no server at all, so they are cleaned up whether or not there is one.
       #
       # @param state [Hash] the Test Kitchen state hash, mutated in place to
-      #   remove `:server_name`, `:hostname` and `:zone`
+      #   remove `:server_name`, `:hostname`, `:zone` and `:created_disks`
       # @return [void]
       def destroy(state)
         @state      = state
         server_name = state[:server_name]
-        return if server_name.nil?
 
-        unless server_exist?(server_name)
-          info("GCE instance <#{server_name}> does not exist - assuming it has been already destroyed.")
-          return
+        unless server_name.nil?
+          if server_exist?(server_name)
+            info("Destroying GCE instance <#{server_name}>...")
+            wait_for_operation(connection.delete_instance(project, zone, server_name))
+            info("GCE instance <#{server_name}> destroyed.")
+          else
+            info("GCE instance <#{server_name}> does not exist - assuming it has been already destroyed.")
+          end
         end
 
-        info("Destroying GCE instance <#{server_name}>...")
-        wait_for_operation(connection.delete_instance(project, zone, server_name))
-        info("GCE instance <#{server_name}> destroyed.")
+        delete_created_disks
 
         state.delete(:server_name)
         state.delete(:hostname)
         state.delete(:zone)
       end
 
+      # Reports whether the instance recorded in the state file is actually
+      # running, by asking GCE rather than trusting the state file.
+      #
+      # Test Kitchen 4 calls this for `kitchen list --live` and the `kitchen
+      # status` alias. Earlier versions never call it, so implementing it is
+      # safe across the whole supported range.
+      #
+      # The state file records only what the last action did, which goes stale
+      # in both directions: a preemptible instance GCE has reclaimed still
+      # reads as "Created", and an instance deleted outside Test Kitchen leaves
+      # a server name behind that no longer resolves.
+      #
+      # @param state [Hash] the Test Kitchen state hash
+      # @return [Hash] the status, in the shape `Kitchen::Instance` expects
+      def status(state)
+        @state      = state
+        server_name = state[:server_name]
+
+        return status_report(live: false, state_name: "not created") if server_name.nil?
+
+        gce_status = server_instance(server_name).status.to_s.downcase
+
+        status_report(
+          live: gce_status == "running",
+          state_name: gce_status,
+          resource_id: server_name
+        )
+      rescue Google::Apis::ClientError => e
+        debug("API error: #{e.message}")
+
+        status_report(
+          live: false,
+          state_name: "not found",
+          resource_id: server_name,
+          message: "Instance #{server_name} is recorded in the state file but no longer exists " \
+                   "in project #{project}, zone #{zone}."
+        )
+      end
+
+      # Builds a status hash in the shape `Kitchen::Instance` expects.
+      #
+      # @param live [Boolean] whether the instance is up and usable
+      # @param state_name [String] the state to display
+      # @param resource_id [String, nil] the GCE instance name
+      # @param message [String, nil] anything the user should know
+      # @return [Hash] the status
+      # @api private
+      def status_report(live:, state_name:, resource_id: nil, message: nil)
+        {
+          live: live,
+          state: state_name,
+          source: "driver",
+          resource_id: resource_id,
+          message: message,
+          checked_at: Time.now.utc.iso8601,
+        }.compact
+      end
+
       # Whether the deprecated single-boot-disk options are configured.
       #
       # @return [Boolean] true if any of `autodelete_disk`, `disk_size` or
@@ -294,8 +409,9 @@ module Kitchen
       #
       # @param disks [Hash] the raw `disks` configuration, keyed by disk name
       # @return [Hash{Symbol => Hash}] the normalised disk configuration
-      # @raise [RuntimeError] if a disk name or type is invalid, or more than
-      #   one boot disk is specified
+      # @raise [RuntimeError] if a disk name or type is invalid, if more than
+      #   one boot disk is specified, or if {#assign_boot_disk} finds no disks
+      #   at all and none eligible to boot
       # @api private
       def normalize_disks(disks)
         normalized = disks.each_with_object({}) do |(disk_name, disk_config), memo|
@@ -310,12 +426,15 @@ module Kitchen
       # Applies the disk defaults to one disk entry and validates the result.
       #
       # @param disk_name [String, Symbol] the disk's name, used in error messages
-      # @param disk_config [Hash] the user-supplied configuration for this disk
+      # @param disk_config [Hash, nil] the user-supplied configuration for this
+      #   disk. A bare `disk-name:` in `kitchen.yml` parses to nil rather than
+      #   to an empty hash, and means the same thing: take the defaults.
       # @return [Hash] the disk configuration with defaults applied
       # @raise [RuntimeError] if the disk type is invalid, a local SSD is
       #   marked bootable, or a size is given for a local SSD
       # @api private
       def normalize_disk(disk_name, disk_config)
+        disk_config ||= {}
         normalized = DISK_DEFAULT_CONFIG.merge(disk_config)
 
         unless valid_disk_type?(normalized[:disk_type])
@@ -382,7 +501,8 @@ module Kitchen
       #
       # @return [void]
       # @raise [RuntimeError] if any configured project, zone, region, machine
-      #   type, network, subnet, image or disk setting is invalid
+      #   type, network, subnet, image or disk setting is invalid, or if the
+      #   WinRM transport is in use without `email` set
       def validate!
         raise "Project #{config[:project]} is not a valid project" unless valid_project?
         raise "Either zone or region must be specified" unless config[:zone] || config[:region]
@@ -397,11 +517,13 @@ module Kitchen
         raise "You cannot use autodelete_disk, disk_size or disk_type with the new disks configuration" if old_disk_configuration_present? && new_disk_configuration_present?
         raise "Disk image #{config[:image_name]} is not valid - check your image name and image project" if boot_disk_source_image.nil?
 
+        warn(BUILTIN_ADMINISTRATOR_WARNING) if winrm_transport? && builtin_administrator?
         warn("Both zone and region specified - region will be ignored.") if config[:zone] && config[:region]
         warn("Both image family and name specified - image family will be ignored") if config[:image_family] && config[:image_name]
         warn("Image project not specified - searching current project only") unless config[:image_project]
         warn("Subnet project not specified - searching current project only") if config[:subnet] && !config[:subnet_project]
         warn("Auto-migrate disabled for preemptible instance") if preemptible? && config[:auto_migrate]
+        warn("Auto-migrate disabled for instance with guest accelerators") if guest_accelerators? && config[:auto_migrate]
         warn("Auto-restart disabled for preemptible instance") if preemptible? && config[:auto_restart]
         warn("These configs are deprecated - consider using new disks configuration") if old_disk_configuration_present?
       end
@@ -424,7 +546,8 @@ module Kitchen
 
       # Application default credentials scoped for Compute Engine.
       #
-      # @return [Google::Auth::Credentials] the resolved credentials
+      # @return [Signet::OAuth2::Client] the resolved application default
+      #   credentials
       def authorization
         @authorization ||= Google::Auth.get_application_default(
           [
@@ -434,6 +557,14 @@ module Kitchen
         )
       end
 
+      # Whether the WinRM transport is configured to log in as the built-in
+      # Administrator account.
+      #
+      # @return [Boolean] true if the transport username is `administrator`
+      def builtin_administrator?
+        instance.transport[:username].to_s.casecmp?(BUILTIN_ADMINISTRATOR)
+      end
+
       # Whether the suite's transport is WinRM, implying a Windows guest.
       #
       # @return [Boolean] true when the transport is WinRM
@@ -469,6 +600,7 @@ module Kitchen
       # Runs an API call and reports whether it succeeded, swallowing client
       # errors so callers can use it as a validity predicate.
       #
+      # @param block [Proc] the API call to attempt, called with no arguments
       # @yield the API call to attempt
       # @return [Boolean] true if the call succeeded, false on a client error
       def check_api_call(&block)
@@ -717,16 +849,97 @@ module Kitchen
       # Builds a unique, GCE-legal instance name, falling back to a UUID when
       # the Test Kitchen instance name would make it too long.
       #
+      # Uppercase is folded rather than discarded. GCE disallows it, but it
+      # still carries meaning, and replacing it with hyphens turned an
+      # `inst_name` of `MyTestVM` into `-y-est--` -- a name the user could not
+      # recognise as anything they had typed.
+      #
       # @return [String] the instance name
+      # @raise [RuntimeError] if no legal name can be salvaged
       def generate_server_name
-        name = config[:inst_name] || "tk-#{instance.name.downcase}-#{SecureRandom.hex(3)}"
+        name = (config[:inst_name] || "tk-#{instance.name}-#{SecureRandom.hex(3)}").downcase
 
-        if name.length > MAX_INSTANCE_NAME_LENGTH
+        if name.length > max_server_name_length
           warn("The TK instance name (#{instance.name}) has been removed from the GCE instance name due to size limitations. Consider setting shorter platform or suite names.")
-          name = "tk-#{SecureRandom.uuid}"
+          name = fallback_server_name
         end
 
-        name.gsub(/([^-a-z0-9])/, "-")
+        validated_server_name(name.gsub(/([^-a-z0-9])/, "-"))
+      end
+
+      # Checks a generated instance name against the pattern GCE enforces.
+      #
+      # Substitution cannot fix every name -- a leading underscore becomes a
+      # leading hyphen, which GCE still rejects -- so say so here rather than
+      # letting the API refuse a name the user never wrote.
+      #
+      # @param name [String] the generated name
+      # @return [String] the same name, once it is known to be legal
+      # @raise [RuntimeError] if the name does not match {RESOURCE_NAME_REGEX}
+      # @api private
+      def validated_server_name(name)
+        return name if name.match?(/\A#{RESOURCE_NAME_REGEX}\z/)
+
+        raise "Instance name #{name} is not valid. GCE names must match " \
+              "#{RESOURCE_NAME_REGEX.source} - they start with a lowercase letter, and end " \
+              "with a lowercase letter or a digit."
+      end
+
+      # Longest instance name that still leaves room for every disk named
+      # after it.
+      #
+      # GCE allows {MAX_INSTANCE_NAME_LENGTH} characters for an instance name
+      # and the same for a disk name, and {#create_disks} names each disk
+      # `"<instance>-<disk>"`. Spending the whole budget on the instance is
+      # what let a perfectly legal instance name produce an illegal disk name.
+      #
+      # @return [Integer] the maximum length of a generated instance name
+      # @raise [RuntimeError] if a configured disk name is long enough that
+      #   fewer than {#fallback_server_name_length} characters remain
+      # @api private
+      def max_server_name_length
+        limit = MAX_INSTANCE_NAME_LENGTH - longest_disk_name_suffix
+
+        if limit < fallback_server_name_length
+          raise "Disk name #{longest_disk_name} is too long. GCE allows " \
+                "#{MAX_INSTANCE_NAME_LENGTH} characters for the disk name " \
+                "<instance name>-#{longest_disk_name}, which leaves no room for the instance name."
+        end
+
+        limit
+      end
+
+      # The longest disk name configured, which bounds the instance name.
+      #
+      # @return [String, nil] the longest disk name
+      # @api private
+      def longest_disk_name
+        Array(config[:disks]&.keys).map(&:to_s).max_by(&:length)
+      end
+
+      # Characters the longest disk name costs an instance name, including the
+      # hyphen joining the two.
+      #
+      # @return [Integer] the reserved length
+      # @api private
+      def longest_disk_name_suffix
+        longest_disk_name.nil? ? 0 : longest_disk_name.length + 1
+      end
+
+      # Name used when the Test Kitchen instance name will not fit.
+      #
+      # @return [String] a UUID-based instance name
+      # @api private
+      def fallback_server_name
+        "tk-#{SecureRandom.uuid}"
+      end
+
+      # Length of a {#fallback_server_name}, which is fixed.
+      #
+      # @return [Integer] the fallback name's length
+      # @api private
+      def fallback_server_name_length
+        @fallback_server_name_length ||= fallback_server_name.length
       end
 
       # Builds every disk for the instance, creating standalone persistent
@@ -771,18 +984,65 @@ module Kitchen
           info("Creating a #{LOCAL_SSD_SIZE_GB} GB local ssd as scratch disk (https://cloud.google.com/compute/docs/disks/#localssds).")
           disk.type = "SCRATCH"
         elsif disk.boot
-          info("Creating a #{disk_config[:disk_size]} GB boot disk named #{unique_disk_name} from image #{image_name}...")
+          params.disk_size_gb = disk_size_for_image(disk_config[:disk_size], image_name)
+          info("Creating a #{params.disk_size_gb} GB boot disk named #{unique_disk_name} from image #{image_name}...")
           params.source_image = boot_disk_source_image
           params.disk_name    = unique_disk_name
         else
-          info("Creating a #{disk_config[:disk_size]} GB extra disk named #{unique_disk_name} from image #{disk_config[:custom_image]}...")
-          params.source_image = image_url(disk_config[:custom_image])
+          custom_image        = disk_config[:custom_image]
+          params.source_image = custom_image_url(custom_image)
+          params.disk_size_gb = disk_size_for_image(disk_config[:disk_size], custom_image)
           params.disk_name    = unique_disk_name
+          info("Creating a #{params.disk_size_gb} GB extra disk named #{unique_disk_name} from image #{custom_image}...")
         end
         disk.initialize_params = params
         disk
       end
 
+      # The size to request for a disk cloned from an image.
+      #
+      # GCE refuses to create a disk smaller than the image it is cloned from,
+      # and the driver's own 10 GB default is smaller than many stock images -
+      # every Windows image is 50 GB, and Rocky and CentOS are 20 GB. Rather
+      # than fail the run over a size the user never chose, raise the request
+      # to what the image needs and say so.
+      #
+      # @param requested [Integer, nil] the configured size in gigabytes
+      # @param image [String, nil] the image the disk is cloned from
+      # @return [Integer, nil] the size to request
+      # @api private
+      def disk_size_for_image(requested, image)
+        image_size = image_disk_size_gb(image)
+        return requested if image_size.nil? || (!requested.nil? && requested >= image_size)
+
+        warn("Requested disk size of #{requested} GB is smaller than image #{image} " \
+             "(#{image_size} GB) - creating a #{image_size} GB disk instead.")
+        image_size
+      end
+
+      # The size, in gigabytes, of an image in the image project.
+      #
+      # Memoised per image name, since the boot image is looked up more than
+      # once during a single action.
+      #
+      # @param image [String, nil] the image name
+      # @return [Integer, nil] the image's size, or nil if it cannot be read
+      # @api private
+      def image_disk_size_gb(image)
+        return if image.nil?
+
+        @image_disk_sizes ||= {}
+        return @image_disk_sizes[image] if @image_disk_sizes.key?(image)
+
+        @image_disk_sizes[image] =
+          begin
+            connection.get_image(image_project, image).disk_size_gb
+          rescue Google::Apis::ClientError => e
+            debug("Unable to read the size of image #{image}: #{e.message}")
+            nil
+          end
+      end
+
       # Creates a standalone persistent disk, waits for it to become ready, and
       # returns a reference attaching it to the instance.
       #
@@ -807,21 +1067,28 @@ module Kitchen
         attached_disk
       end
 
-      # Names of the standalone disks this driver created during the current
-      # action, tracked so they can be cleaned up if creation fails.
+      # Names of the standalone disks this driver has created, held in the Test
+      # Kitchen state file rather than in memory.
+      #
+      # These disks bill from the moment GCE creates them, which is before the
+      # instance exists, and the driver's own cleanup cannot be relied on to
+      # remove them: `Interrupt` is not a `StandardError`, so pressing Ctrl-C
+      # during a create skips the rescue entirely. Test Kitchen writes the
+      # state file whatever happens, so recording the names there is what makes
+      # a later `kitchen destroy` able to find them.
       #
       # @return [Array<String>] the created disk names
       def created_disk_names
-        @created_disk_names ||= []
+        state[:created_disks] ||= []
       end
 
-      # Deletes every standalone disk created during a failed create, so a
-      # partial run does not leave billable disks behind.
+      # Deletes every standalone disk this driver created, so a partial run
+      # does not leave billable disks behind.
       #
       # @return [void]
       def delete_created_disks
         created_disk_names.each { |disk_name| delete_disk(disk_name) }
-        created_disk_names.clear
+        state.delete(:created_disks)
       end
 
       # Deletes a standalone persistent disk, tolerating one that is already
@@ -873,13 +1140,44 @@ module Kitchen
         "projects/#{image_project}/global/images/#{image}" if image_exist?(image)
       end
 
+      # URL of a non-boot disk's `custom_image`, which must exist.
+      #
+      # GCE reads a missing `sourceImage` as a request for a blank disk, so an
+      # image the driver cannot resolve would otherwise produce an empty disk
+      # and a successful run -- a test that silently verifies nothing. The boot
+      # disk has been guarded against exactly this in {#validate!} for years.
+      #
+      # The message names the project searched because that is where the
+      # surprise usually is: `custom_image` is resolved in `image_project`, so
+      # booting from a public image such as ubuntu-os-cloud sends the lookup
+      # there rather than to the user's own project.
+      #
+      # @param image [String] the custom image name
+      # @return [String] the image URL
+      # @raise [RuntimeError] if the image does not exist in the image project
+      # @api private
+      def custom_image_url(image)
+        image_url(image) ||
+          raise("Disk image #{image} was not found in project #{image_project} - check the " \
+                "custom_image name, and note that custom images are looked up in image_project.")
+      end
+
       # Resolves the current image name for an image family.
       #
+      # A family the API cannot see is a configuration mistake like any other,
+      # so report it the way {#validate!} reports an unresolvable `image_name`
+      # rather than letting the Google client's own error escape.
+      #
       # @param image_family [String] the image family
       # @return [String] the image name
+      # @raise [RuntimeError] if the family does not exist in the image project
       def image_name_for_family(image_family)
         image = connection.get_image_from_family(image_project, image_family)
         image.name
+      rescue Google::Apis::ClientError => e
+        debug("API error: #{e.message}")
+        raise "Image family #{image_family} is not valid - it was not found in project " \
+              "#{image_project}. Check the family name and image_project."
       end
 
       # Partial URL identifying the machine type in the target zone.
@@ -921,10 +1219,11 @@ module Kitchen
         guest_accelerator_configs
       end
 
-      # The instance metadata, merging the driver's own keys over any the user
-      # configured and adding a WinRM bootstrap script for Windows guests.
+      # The instance metadata: the driver's own keys, overlaid with any the
+      # user configured, plus a WinRM bootstrap script for Windows guests.
       #
-      # @return [Hash{String => String}] the metadata
+      # @return [Hash{String => Object}] the metadata, string-keyed; user
+      #   values keep whatever type `kitchen.yml` gave them
       def metadata
         default_metadata = {
           "created-by" => "test-kitchen",
@@ -939,7 +1238,28 @@ module Kitchen
           end
         end
 
-        config[:metadata].merge(default_metadata)
+        default_metadata.merge(user_metadata(default_metadata.keys))
+      end
+
+      # The user's own metadata, keyed the way the GCE API expects.
+      #
+      # Test Kitchen symbolises every key it loads from `kitchen.yml`, so a
+      # user writing `created-by:` reaches the driver as `:"created-by"` and
+      # never as the string the driver sets itself. Merging the two hashes
+      # untouched therefore sends both spellings of the same key, and GCE
+      # rejects the instance outright with "Metadata has duplicate keys".
+      #
+      # @param driver_keys [Array<String>] keys the driver sets itself, warned
+      #   about when the user replaces one
+      # @return [Hash{String => Object}] the user's metadata, string-keyed
+      # @api private
+      def user_metadata(driver_keys)
+        metadata = config[:metadata].transform_keys(&:to_s)
+
+        overridden = driver_keys & metadata.keys
+        warn("Overriding metadata set by the driver: #{overridden.join(", ")}") unless overridden.empty?
+
+        metadata
       end
 
       # The metadata in the form the GCE API expects.
@@ -1031,16 +1351,24 @@ module Kitchen
         config[:preemptible] ? true : false
       end
 
-      # Whether the instance may live-migrate. Always false when preemptible,
-      # which GCE does not allow to migrate.
+      # Whether the instance may live-migrate. Always false for preemptible
+      # instances and for instances with guest accelerators attached, neither
+      # of which GCE will migrate.
       #
       # @return [Boolean] true if live migration is enabled
       def auto_migrate?
-        return false if preemptible?
+        return false if preemptible? || guest_accelerators?
 
         config[:auto_migrate] ? true : false
       end
 
+      # Whether any guest accelerators are attached.
+      #
+      # @return [Boolean] true if the instance has at least one accelerator
+      def guest_accelerators?
+        !Array(config[:guest_accelerators]).empty?
+      end
+
       # Whether the instance should restart automatically. Always false when
       # preemptible, which GCE does not allow to auto-restart.
       #
@@ -1117,6 +1445,7 @@ module Kitchen
       # logging each status change.
       #
       # @param requested_status [String] the status to wait for
+      # @param block [Proc] called once per poll to re-fetch the resource
       # @yieldreturn [#status] the resource to poll
       # @return [void]
       # @raise [Timeout::Error] if the status is not reached within {#wait_time}

data/lib/kitchen/driver/gce_version.rb

@@ -28,6 +28,6 @@ module Kitchen
     # release. Keep it on one line.
     #
     # @return [String] the gem version
-    GCE_VERSION = "3.0.1"
+    GCE_VERSION = "3.1.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-google
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.1
 platform: ruby
 authors:
 - Test Kitchen Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-23 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-apis-compute_v1
@@ -100,6 +100,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: timeout
   requirement: !ruby/object:Gem::Requirement