kitchen-ec2 3.22.10 → 3.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adbbc52b9c77d773ae78ebd08798d629a6781793d0e91ff46fb14eb080c70595
-  data.tar.gz: 8df7160b05b65d0187b24d9525ea458593db0c95cf9cef261683229752ca1cf6
+  metadata.gz: 4b31b976c77faa84d3828219b396b07d52790a806d0b2a0fc72b95f8dabbe548
+  data.tar.gz: 52cb6998a147c6ca43e638f80a16f3b461f3ed25d7999695c42197a1900c34e1
 SHA512:
-  metadata.gz: 956f2322fd4e6bb42ad179c677159be0acb108b30c651c940e95b3c6e266466a548a982f9bb9bcc6edeea3e3ae9734ddc37d80dad14cce80a78c268d733a97ba
-  data.tar.gz: f98fe3846db116988011feefebae241fec7145cbbc49aa45d3e82620c1ba5fa36ae15222125144cf37405d7f373db0c5fbcf32505b62453b9f677e84cfa3c765
+  metadata.gz: 0d57aa3da2611170b0e00e140e9d671c1a7585048020da316c1194d238e9c3fd41ef4ffc62ed1e4375d1862983220cd6c67e48ca25f98777adc677e0d6987f87
+  data.tar.gz: 68faeb3e26106d8df47a4896b7d6f1ef18c3c30cbbfd2d12e1cac6dcd2dddacd208f60d92493647ec19fba347e50f14691c279ad33999bf109a5ca949817e7cc

data/lib/kitchen/driver/aws/instance_generator.rb

@@ -88,7 +88,7 @@ module Kitchen
 
           if config[:security_group_ids].nil? && config[:security_group_filter]
             # => Grab the VPC in the case a Subnet ID rather than Filter was set
-            vpc_id ||= client.describe_subnets(subnet_ids: [config[:subnet_id]]).subnets[0].vpc_id
+            vpc_id ||= security_group_search_vpc_id(client)
             security_groups = []
             filters = [config[:security_group_filter]].flatten
             filters.each do |sg_filter|
@@ -112,7 +112,10 @@ module Kitchen
                       "#{sg_filter.inspect} has neither."
               end
 
-              criteria << { name: "vpc-id", values: [vpc_id] }
+              # Only when a VPC is known. A name or tag has already narrowed the
+              # search, so leaving this off is not the unfiltered request the
+              # check above exists to prevent.
+              criteria << { name: "vpc-id", values: [vpc_id] } if vpc_id
 
               security_group = client.describe_security_groups(filters: criteria).security_groups
 
@@ -243,6 +246,46 @@ module Kitchen
           i
         end
 
+        # The VPC to look for security groups in.
+        #
+        # Security group names are unique only within a VPC, so the search is
+        # scoped to the VPC the instance will launch into. Which VPC that is
+        # depends on how the subnet was chosen:
+        #
+        # - a named `subnet_id` decides it, so the subnet is described for it
+        # - no subnet at all means EC2 launches into the account's default VPC,
+        #   so that is what gets searched
+        #
+        # The second case used to describe a subnet with an ID of nil and then
+        # read `vpc_id` off the empty result, so a `security_group_filter` on
+        # its own -- a documented combination, and the natural one in a default
+        # VPC account -- died with `undefined method 'vpc_id' for nil` before
+        # anything was launched.
+        #
+        # An account with no default VPC returns nil, and the caller then
+        # searches on the name or tag alone.
+        #
+        # @param client [Aws::EC2::Client] the client to query with
+        # @return [String, nil] the VPC ID, or nil when there is no default VPC
+        # @raise [RuntimeError] when a named subnet does not exist, which would
+        #   otherwise surface as the same nil dereference
+        def security_group_search_vpc_id(client)
+          unless config[:subnet_id]
+            default_vpc = client.describe_vpcs(
+              filters: [{ name: "isDefault", values: %w{true} }]
+            ).vpcs.first
+
+            return default_vpc&.vpc_id
+          end
+
+          subnet = client.describe_subnets(subnet_ids: [config[:subnet_id]]).subnets.first
+          unless subnet
+            raise "Subnet #{config[:subnet_id]} not found while resolving security_group_filter."
+          end
+
+          subnet.vpc_id
+        end
+
         # The user data script, base64 encoded as EC2 requires.
         #
         # The configured value is treated as a file path when it names an

data/lib/kitchen/driver/aws/standard_platform/macos.rb

@@ -34,6 +34,24 @@ module Kitchen
             "ec2-user"
           end
 
+          # The AWS account Amazon publishes its macOS AMIs under.
+          #
+          # @return [String]
+          MACOS_OWNER_ID = "628277914472".freeze
+
+          # EC2's architecture values for Mac instances, keyed by the name the
+          # platform string uses.
+          #
+          # EC2 reports a Mac image's architecture as "x86_64_mac" or
+          # "arm64_mac", never the bare "x86_64" or "arm64" every other
+          # platform uses, so an unmapped value matches nothing at all.
+          #
+          # @return [Hash{String => String}]
+          MAC_ARCHITECTURES = {
+            "arm64" => "arm64_mac",
+            "x86_64" => "x86_64_mac",
+          }.freeze
+
           # EC2 image filters that select Amazon's macOS AMIs, which run only on dedicated Mac hosts.
           #
           # A filter is added for {StandardPlatform#architecture} only when one was
@@ -44,11 +62,12 @@ module Kitchen
           # @see StandardPlatform#find_image
           def image_search
             search = {
-              "owner-id" => "100343932686",
+              "owner-id" => MACOS_OWNER_ID,
               "name" => version ? "amzn-ec2-macos-#{version}*" : "amzn-ec2-macos-*",
             }
-            search["architecture"] = architecture if architecture
-            search["architecture"] = "arm64_mac" if architecture == "arm64"
+            if architecture
+              search["architecture"] = MAC_ARCHITECTURES.fetch(architecture, architecture)
+            end
             search
           end
 

data/lib/kitchen/driver/aws/standard_platform.rb

@@ -176,7 +176,7 @@ module Kitchen
         # Detect platform from an image.
         #
         # @param driver [Kitchen::Driver::Ec2] The driver.
-        # @param image [Aws::Ec2::Image] The EC2 Image object.
+        # @param image [Aws::EC2::Image] The EC2 Image object.
         #
         # @return [Kitchen::Driver::Aws::StandardPlatform]
         #
@@ -223,9 +223,9 @@ module Kitchen
         # Used by the default find_image. The default version calls platform_from_image()
         # on each image, and interprets the versions as floats (7 < 7.1 < 8).
         #
-        # @param images [Array[Aws::Ec2::Image]] The list of images to sort
+        # @param images [Array<Aws::EC2::Image>] The list of images to sort
         #
-        # @return [Array[Aws::Ec2::Image]] A sorted list.
+        # @return [Array<Aws::EC2::Image>] A sorted list.
         #
         def sort_by_version(images)
           # 7.1 -> [ img1, img2, img3 ]
@@ -246,6 +246,7 @@ module Kitchen
         # preferences.
         #
         # @param images [Array<Aws::EC2::Image>] the images to reorder
+        # @param block [Proc] the predicate each image is partitioned by
         # @yieldparam image [Aws::EC2::Image] an image to test
         # @yieldreturn [Boolean] true when the image is preferred
         # @return [Array<Aws::EC2::Image>] preferred images first

data/lib/kitchen/driver/ec2.rb

@@ -256,6 +256,72 @@ module Kitchen
 
       # Create an EC2 instance and wait until it can be connected to.
       #
+      # Configuration that cannot possibly work is rejected first, before
+      # anything billable is launched; {#launch_instance} does the real work.
+      #
+      # @param state [Hash] the instance state, updated in place with
+      #   `:server_id`, `:hostname` and any auto-created credentials
+      # @return [void]
+      # @raise [Kitchen::UserError] when the platform is misconfigured such
+      #   that the run could not succeed
+      def create(state)
+        return if state[:server_id]
+
+        # Deliberately checked here rather than inside #launch_instance: that
+        # method rewrites every exception it sees into an "is this AMI available
+        # in this region" message, which would bury this one.
+        assert_powershell_shell_type!
+
+        launch_instance(state)
+      end
+
+      # Refuse to launch a Windows instance that would be driven with a Bourne
+      # shell type.
+      #
+      # Test Kitchen infers `shell_type` from the platform *name*, not from
+      # `os_type`, so a Windows platform named something that does not begin
+      # with "windows" silently ends up as a Bourne host. The provisioner then
+      # generates Bourne commands, WinRM executes them in PowerShell, and the
+      # run fails deep into converge with an error that points nowhere near the
+      # real cause -- typically a `New-Item` complaint that the sandbox
+      # directory already exists.
+      #
+      # Failing here costs the user nothing; letting it through costs them a
+      # billable instance and a confusing converge failure.
+      #
+      # @raise [Kitchen::UserError] when the platform is Windows but its shell
+      #   type is not PowerShell
+      # @return [void]
+      # @see https://github.com/test-kitchen/kitchen-ec2/issues/621
+      def assert_powershell_shell_type!
+        return unless windows_os?
+        return if powershell_shell?
+
+        shell_type = instance.platform.respond_to?(:shell_type) ? instance.platform.shell_type : nil
+
+        raise Kitchen::UserError, <<~MESSAGE
+          Platform '#{instance.platform.name}' sets os_type 'windows' but its shell_type is '#{shell_type}'.
+
+          Test Kitchen infers shell_type from the platform name, so a Windows platform
+          whose name does not begin with 'windows' is treated as a Bourne shell host.
+          Provisioner commands would be generated as Bourne syntax and then executed by
+          PowerShell over WinRM, failing during converge with an unrelated error such as
+          'Cannot create ... because a file or directory with the same name already exists'.
+
+          Set shell_type explicitly on the platform:
+
+            platforms:
+              - name: #{instance.platform.name}
+                os_type: windows
+                shell_type: powershell
+
+          Renaming the platform to start with 'windows' also works, as Test Kitchen then
+          infers both os_type and shell_type from the name.
+        MESSAGE
+      end
+
+      # Request the instance and wait until it can be connected to.
+      #
       # Auto-creates a security group and key pair when none were configured,
       # allocates a dedicated host if `tenancy: host` requires one, requests
       # either an on-demand or a spot instance, then waits for the instance to
@@ -270,9 +336,7 @@ module Kitchen
       # @return [void]
       # @raise [Kitchen::ActionFailed] wrapping whatever went wrong, after
       #   cleaning up
-      def create(state)
-        return if state[:server_id]
-
+      def launch_instance(state)
         update_username(state)
 
         info(Kitchen::Util.outdent!(<<-END)) unless config[:skip_cost_warning]
@@ -389,7 +453,10 @@ module Kitchen
       # @see https://github.com/test-kitchen/kitchen-ec2/issues/606
       def create_failure_message(error)
         message = "Failed to create the EC2 instance: #{error.class}: #{error.message}"
-        return message unless image_related_error?(error)
+        # The hint names the image, so it has nothing to say when there is no
+        # image to name. Without this it rendered as "Check that image  exists"
+        # on exactly the failure where no image was ever resolved.
+        return message unless config[:image_id] && image_related_error?(error)
 
         "#{message} Check that image #{config[:image_id]} exists and is available " \
           "in region #{config[:region]}."
@@ -397,14 +464,19 @@ module Kitchen
 
       # Whether a failure is about the AMI rather than something else entirely.
       #
-      # EC2 reports every image problem with a code beginning "InvalidAMI"; the
-      # message check catches errors raised by the driver itself, which are
-      # plain strings with no code attached.
+      # EC2 reports every image problem with a code beginning "InvalidAMI". The
+      # message check is for errors raised by the driver itself, which are
+      # plain strings with no code attached -- but it only applies to those,
+      # because plenty of AWS errors merely *mention* the AMI while being about
+      # something else. The clearest example is an instance type whose
+      # architecture does not match the image's: its message names the AMI
+      # twice, and the old check duly told the user to go and check whether an
+      # image that exists, exists.
       #
       # @param error [Exception] the underlying failure
       # @return [Boolean]
       def image_related_error?(error)
-        return true if error.respond_to?(:code) && error.code.to_s.start_with?("InvalidAMI")
+        return error.code.to_s.start_with?("InvalidAMI") if error.respond_to?(:code)
 
         error.message.to_s.match?(/\bAMI\b/i)
       end
@@ -429,10 +501,17 @@ module Kitchen
               warn("Received #{e}, instance was probably already destroyed. Ignoring")
             end
           end
-          # If we are going to clean up an automatic security group, we need
-          # to wait for the instance to shut down. This slightly breaks the
-          # subsystem encapsulation, sorry not sorry.
-          if state[:auto_security_group_id] && server && ec2.instance_exists?(state[:server_id])
+          # Two cleanups below cannot succeed while the instance is still
+          # shutting down, so either of them means waiting termination out:
+          # an auto-created security group cannot be deleted while an instance
+          # still references it, and a dedicated host goes on listing a
+          # terminating instance, which blocks its release.
+          #
+          # The host case used to be missing, so a run that supplied its own
+          # `security_group_ids` skipped the wait, found the host still
+          # occupied, and silently left it allocated and billing.
+          if (state[:auto_security_group_id] || state[:allocated_host_id]) &&
+              server && ec2.instance_exists?(state[:server_id])
             wait_log = proc do |attempts|
               c = attempts * config[:retryable_sleep]
               t = config[:retryable_tries] * config[:retryable_sleep]
@@ -468,7 +547,73 @@ module Kitchen
         return unless host_id
 
         host = host_for_id(host_id)
-        deallocate_host(host_id) if host && host_unused?(host)
+        # Already gone, or never usable: nothing to release either way.
+        return if host.nil? || host.state != "available"
+
+        unless host_unused?(host)
+          # Test Kitchen deletes the state file once destroy returns, taking
+          # the host ID with it, so there is no later run that could pick this
+          # up -- say so loudly and give the command to finish the job.
+          error("Dedicated host #{host_id} still has instances on it and was not released. " \
+                "A dedicated host bills from allocation until it is released. Release it with: " \
+                "aws ec2 release-hosts --region #{config[:region]} --host-ids #{host_id}")
+          return
+        end
+
+        deallocate_host(host_id)
+      end
+
+      # EC2 instance states in which the instance still exists as a resource.
+      #
+      # "shutting-down" and "terminated" are left out deliberately. Neither can
+      # be brought back and neither leaves anything to destroy, so counting
+      # them as live would defeat the point of asking.
+      #
+      # @return [Array<String>]
+      LIVE_INSTANCE_STATES = %w{pending running stopping stopped}.freeze
+
+      # Whether the instance Test Kitchen recorded is still there.
+      #
+      # Answers `kitchen list --live` by asking EC2 rather than trusting the
+      # state file, which is the whole point: the state file records what Test
+      # Kitchen last did, not what survived. An instance terminated in the
+      # console, reaped by an account policy, or orphaned by a run that was
+      # killed mid-create all leave a state file claiming the instance exists.
+      #
+      # Kept to a single describe call, since `kitchen list --live` makes one
+      # of these per instance.
+      #
+      # @param state [Hash] the instance state
+      # @return [Hash] status data, normalized by Kitchen::Instance
+      # @see https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_InstanceState.html
+      def status(state)
+        unless state[:server_id]
+          return status_report(
+            live: false,
+            instance_state: "not_created",
+            message: "No EC2 instance has been created for this suite yet"
+          )
+        end
+
+        instance_state = ec2.get_instance(state[:server_id]).state.name
+
+        status_report(
+          live: LIVE_INSTANCE_STATES.include?(instance_state),
+          instance_state: instance_state,
+          resource_id: state[:server_id],
+          message: "EC2 instance #{state[:server_id]} is #{instance_state}"
+        )
+      rescue ::Aws::EC2::Errors::InvalidInstanceIDNotFound
+        # The reconciliation this check exists for: Test Kitchen still believes
+        # it has an instance, and EC2 has never heard of it.
+        status_report(
+          live: false,
+          instance_state: "not_found",
+          resource_id: state[:server_id],
+          message: "EC2 does not know instance #{state[:server_id]}. It was terminated " \
+                   "outside Test Kitchen, or has aged out of EC2's terminated instance list. " \
+                   "Run `kitchen destroy` to clear the stale state."
+        )
       end
 
       # The EC2 image this instance will be created from.
@@ -484,6 +629,14 @@ module Kitchen
           @image = ec2.resource.image(config[:image_id])
           show_chosen_image
 
+        elsif searched_for_image?
+          # A search ran and matched nothing. Saying "specify image_id or
+          # image_search" here sent people to set an option they had already
+          # set, or that the platform sets for them -- the real problem is
+          # that the filters matched no image in this region.
+          raise "The image search for #{desired_platform || instance.platform.name} matched no " \
+                "image in region #{config[:region]}. Set image_id to an AMI, or image_search to " \
+                "filters that match one."
         else
           raise "Neither image_id nor an image_search specified for instance #{instance.name}!" \
                 " Please specify one or the other."
@@ -492,16 +645,33 @@ module Kitchen
         @image
       end
 
+      # Whether an image search ran and came back empty.
+      #
+      # Distinguishes "there was nothing to search for" -- an unrecognized
+      # platform name and no `image_search` -- from "the search matched
+      # nothing", which are different mistakes with different fixes.
+      #
+      # @return [Boolean]
+      def searched_for_image?
+        !config[:image_search].nil? || !desired_platform.nil?
+      end
+
       # The instance type to use when the user did not choose one.
       #
+      # An instance type runs one processor architecture and EC2 rejects a
+      # RunInstances call pairing it with an image built for another, so the
+      # default has to follow the image: t4g is the Graviton counterpart of
+      # t3. Picking t3.micro for every HVM image made every arm64 platform --
+      # "ubuntu-24.04-arm64" and friends, an architecture this driver parses
+      # and searches for -- fail to launch outright.
+      #
       # t3 instances require a hardware-virtualized image, so a paravirtual
       # image falls back to the older t1 family.
       #
-      # @return [String] a free-tier instance type
+      # @return [String] a free-tier instance type matching the image
       def default_instance_type
         @instance_type ||= if image && image.virtualization_type == "hvm"
-                             info("instance_type not specified. Using free tier t3.micro instance ...")
-                             "t3.micro"
+                             hvm_default_instance_type
                            else
                              info("instance_type not specified. Using free tier t1.micro instance since" \
                                   " image is paravirtual (pick an hvm image to use the superior t3.micro!) ...")
@@ -509,6 +679,25 @@ module Kitchen
                            end
       end
 
+      # The free-tier instance type matching a hardware-virtualized image.
+      #
+      # Only arm64 is special-cased. EC2's Mac architectures ("arm64_mac" and
+      # "x86_64_mac") are deliberately not defaulted: they run only on
+      # dedicated Mac hosts, which carry a 24-hour minimum allocation, so
+      # guessing one would be an expensive surprise rather than a convenience.
+      #
+      # @return [String] the instance type to launch
+      def hvm_default_instance_type
+        if image.architecture == "arm64"
+          info("instance_type not specified. Using free tier t4g.micro instance" \
+               " since image is arm64 ...")
+          "t4g.micro"
+        else
+          info("instance_type not specified. Using free tier t3.micro instance ...")
+          "t3.micro"
+        end
+      end
+
       # The platform detected from the image actually being used.
       #
       # This can differ from {#desired_platform}: the user asks for "ubuntu" and
@@ -820,6 +1009,7 @@ module Kitchen
       # @param server [Aws::EC2::Instance] the instance to wait on
       # @param state [Hash] the instance state
       # @param status_msg [String] what is being waited for, for log messages
+      # @param block [Proc] the readiness check polled against the instance
       # @yieldparam aws_instance [Aws::EC2::Instance] the instance being polled
       # @yieldreturn [Boolean] true when the wait is over
       # @return [void]
@@ -1003,9 +1193,15 @@ module Kitchen
         # so it does not matter which agent is installed. Only RAW disks are
         # touched, so a volume that already carries a filesystem is never
         # reformatted.
+        #
+        # GPT, not MBR: an MBR disk cannot address beyond 2 TiB, and
+        # Initialize-Disk does not fail on a larger one -- it caps it, so a
+        # 2600 GB volume came up as a 2 TiB filesystem with the remainder
+        # unreachable and still billed. GPT is supported by every Windows
+        # release this driver can launch.
         "Initializing any uninitialized volumes" >> $logfile
         Get-Disk | Where-Object PartitionStyle -eq 'RAW' |
-          Initialize-Disk -PartitionStyle MBR -PassThru |
+          Initialize-Disk -PartitionStyle GPT -PassThru |
           New-Partition -AssignDriveLetter -UseMaximumSize |
           Format-Volume -FileSystem NTFS -Confirm:$false >> $logfile
 
@@ -1307,6 +1503,28 @@ module Kitchen
 
       private
 
+      # Build a status hash in the shape Kitchen::Instance normalizes.
+      #
+      # `checked_at` is stamped here rather than left out so that the timestamp
+      # reflects when EC2 was actually asked, not when the answer was rendered.
+      #
+      # @param live [Boolean] whether the instance still exists
+      # @param instance_state [String] the EC2 state name, or a driver-level
+      #   one such as "not_created" for the cases EC2 was never asked about
+      # @param message [String] a human-readable explanation
+      # @param resource_id [String, nil] the EC2 instance ID, when there is one
+      # @return [Hash]
+      def status_report(live:, instance_state:, message:, resource_id: nil)
+        {
+          live: live,
+          state: instance_state,
+          source: "driver",
+          resource_id: resource_id,
+          message: message,
+          checked_at: Time.now.utc.iso8601,
+        }
+      end
+
       # Wrap the transport's `connection` method with Instance Connect setup.
       #
       # A pushed Instance Connect key expires after about a minute, so the key

data/lib/kitchen/driver/ec2_version.rb

@@ -19,6 +19,6 @@
 module Kitchen
   module Driver
     # Version string for EC2 Test Kitchen driver
-    EC2_VERSION = "3.22.10".freeze
+    EC2_VERSION = "3.23.1".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-ec2
 version: !ruby/object:Gem::Version
-  version: 3.22.10
+  version: 3.23.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: aws-sdk-ec2