kitchen-google 3.0.2 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bb68767fd70358c97f209575379ad984b9aab4fd4b3f0377cf1e77b5167796a
-  data.tar.gz: 83f5317efdf99856679a51a88a95c5d5601dc220989285c54e5771b290b90393
+  metadata.gz: 915d1d94065a49854c4c040df37b17d4a1e6853bbffd4872bb6e94d255e070bf
+  data.tar.gz: ab9bbf5503260572daf07e281d7087db57110b27ef25fc47f1879cfcc8a1e75d
 SHA512:
-  metadata.gz: 59c12a1a8494f2c99df3a5ddb5b68bcb34fde00815e3ed25df084b4e1cb7b96057f030486350870b694ac2cd827fdffc47f94a421c7586118d9338dc7c5870e7
-  data.tar.gz: 5e1f05a0b84feab76831418aeff5b5900d84a8285fbe3bf0b7b9c046ec958e9e6d46027bb47e493842c3e84f91d2398f094f23058b6f97b82be23a06b86e36bd
+  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.
       #
@@ -105,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.
       #
@@ -173,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)
@@ -182,20 +198,28 @@ 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))
 
-        # GCE starts billing for the instance as soon as the insert is
-        # accepted, so record it before waiting on the operation. Anything that
-        # goes wrong from here on can then be torn down by the rescue below,
-        # and by `kitchen destroy` if the process does not survive to run it.
-        state[:server_name] = server_name
-        state[:zone]        = zone
-
         wait_for_operation(operation)
 
         state[:hostname] = ip_address_for(server_instance(server_name))
@@ -220,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.
+      #
+      # 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.
       #
-      # Does nothing when the state file records no server, or when the
-      # instance no longer exists in GCE.
+      # 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
@@ -317,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|
@@ -333,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])
@@ -405,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]
@@ -449,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(
           [
@@ -502,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)
@@ -750,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
@@ -809,10 +989,11 @@ module Kitchen
           params.source_image = boot_disk_source_image
           params.disk_name    = unique_disk_name
         else
-          params.disk_size_gb = disk_size_for_image(disk_config[:disk_size], disk_config[:custom_image])
-          info("Creating a #{params.disk_size_gb} 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
@@ -886,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
@@ -952,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.
@@ -1000,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",
@@ -1018,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.
@@ -1204,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.2"
+    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.2
+  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