kitchen-ec2 3.22.3 → 3.22.4

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

@@ -23,6 +23,12 @@ module Kitchen
         class Debian < StandardPlatform
           StandardPlatform.platforms["debian"] = self
 
+          # Debian release numbers to their codenames, newest first.
+          #
+          # The order matters: the first entry is the newest known release and
+          # is what an unversioned Debian platform resolves to.
+          #
+          # @return [Hash{Integer => String}]
           DEBIAN_CODENAMES = {
             13 => "trixie",
             12 => "bookworm",
@@ -34,21 +40,43 @@ module Kitchen
             6 => "squeeze",
           }.freeze
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # Debian uses "admin" rather than the "ec2-user" or distribution-named
+          # account most other platforms create.
+          #
+          # @return [String] the default SSH username
           def username
             "admin"
           end
 
+          # The Debian release codename for the requested version.
+          #
+          # Only the major version selects a codename, so a more precise version
+          # such as "12.5" is truncated, with a warning that the extra precision
+          # is being discarded. With no version at all, the newest known release
+          # is used.
+          #
+          # @return [String, nil] the codename, or nil for an unknown version
           def codename
             v = version
-            if v && v.size > 1
+            # Warn only when truncating to the major version actually discards
+            # something. Comparing string forms keeps a version that arrived as
+            # an Integer from warning about itself.
+            if v && v.to_s != v.to_i.to_s
               warn("WARN: Debian version #{version} specified, but searching for #{version.to_i} instead.")
-              v = v.to_i
             end
             v ? DEBIAN_CODENAMES[v.to_i] : DEBIAN_CODENAMES.values.first
           end
 
+          # EC2 image filters that select Debian cloud images.
+          #
+          # A filter is added for {StandardPlatform#architecture} only when one was
+          # requested, so that an unspecified architecture matches any of them.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the value
+          #   or values it must match
+          # @see StandardPlatform#find_image
           def image_search
             search = {}
 
@@ -70,15 +98,26 @@ module Kitchen
             search
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [Debian, nil] a platform when the image is Debian, otherwise nil
           def self.from_image(driver, image)
             return unless /debian/i.match?(image.name)
 
             image.name =~ /\b(\d+|#{DEBIAN_CODENAMES.values.join("|")})\b/i
             version = (Regexp.last_match || [])[1]
             if version&.to_i&.zero?
+              # `to_s`, so that a codename-derived version is the same type as a
+              # version read straight out of the image name. Callers compare and
+              # display these without caring which path produced them.
               version = DEBIAN_CODENAMES.find do |_v, codename|
                 codename == version.downcase
-              end.first
+              end&.first&.to_s
             end
             new(driver, "debian", version, image.architecture)
           end

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

@@ -23,12 +23,23 @@ module Kitchen
         class Fedora < StandardPlatform
           StandardPlatform.platforms["fedora"] = self
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # Used as the SSH username when the transport does not specify one.
+          #
+          # @return [String] the default SSH username
           def username
             "fedora"
           end
 
+          # EC2 image filters that select Fedora Cloud Base images.
+          #
+          # A filter is added for {StandardPlatform#architecture} only when one was
+          # requested, so that an unspecified architecture matches any of them.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the value
+          #   or values it must match
+          # @see StandardPlatform#find_image
           def image_search
             search = {
               "owner-id" => "125523088429",
@@ -38,6 +49,14 @@ module Kitchen
             search
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [Fedora, nil] a platform when the image is Fedora, otherwise nil
           def self.from_image(driver, image)
             return unless /fedora/i.match?(image.name)
 

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

@@ -23,14 +23,31 @@ module Kitchen
         class Freebsd < StandardPlatform
           StandardPlatform.platforms["freebsd"] = self
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # Used as the SSH username when the transport does not specify one.
+          #
+          # @return [String] the default SSH username
           def username
             "ec2-user"
           end
 
+          # The command used to elevate privileges on this platform.
+          #
+          # FreeBSD AMIs do not configure sudo for the default account, so this
+          # is deliberately nil rather than the usual "sudo".
+          #
+          # @return [nil] always
           def sudo_command; end
 
+          # EC2 image filters that select FreeBSD RELEASE images.
+          #
+          # A filter is added for {StandardPlatform#architecture} only when one was
+          # requested, so that an unspecified architecture matches any of them.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the value
+          #   or values it must match
+          # @see StandardPlatform#find_image
           def image_search
             search = {
               "owner-id" => "118940168514",
@@ -40,6 +57,14 @@ module Kitchen
             search
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [Freebsd, nil] a platform when the image is FreeBSD, otherwise nil
           def self.from_image(driver, image)
             return unless /freebsd/i.match?(image.name)
 

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

@@ -19,29 +19,55 @@ module Kitchen
   module Driver
     class Aws
       class StandardPlatform
+        # Amazon's macOS images, which run only on dedicated Mac hosts.
+        #
+        # @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-macos-instances.html
         class MacOS < StandardPlatform
           StandardPlatform.platforms["macos"] = self
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # Used as the SSH username when the transport does not specify one.
+          #
+          # @return [String] the default SSH username
           def username
             "ec2-user"
           end
 
+          # 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
+          # requested, so that an unspecified architecture matches any of them.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the value
+          #   or values it must match
+          # @see StandardPlatform#find_image
           def image_search
             search = {
               "owner-id" => "100343932686",
-              "name" => version ? "amzn-ec2-macos-#{version}*" : "amzn2-ec2-macos-*",
+              "name" => version ? "amzn-ec2-macos-#{version}*" : "amzn-ec2-macos-*",
             }
             search["architecture"] = architecture if architecture
             search["architecture"] = "arm64_mac" if architecture == "arm64"
             search
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [MacOS, nil] a platform when the image is macOS, otherwise nil
           def self.from_image(driver, image)
             return unless /amzn-ec2-macos/i.match?(image.name)
 
-            image.name =~ /\b(\d+(\.\d+[\.\d])?)/i
+            # `(\.\d+)?`, not `(\.\d+[\.\d])?`: the character class matched the
+            # separator that follows the minor version, capturing it into the
+            # version string ("2018.03.") and failing outright when the minor
+            # version was followed by anything but a dot or digit.
+            image.name =~ /\b(\d+(\.\d+)?)/i
             new(driver, "macos", (Regexp.last_match || [])[1], image.architecture)
           end
         end

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

@@ -24,17 +24,38 @@ module Kitchen
           StandardPlatform.platforms["rhel"] = self
           StandardPlatform.platforms["el"] = self
 
+          # Build a Red Hat Enterprise Linux platform.
+          #
+          # This class is registered under both "rhel" and "el", so the name it
+          # was constructed with is discarded and normalized to "rhel".
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver
+          # @param _name [String] the registered name, ignored
+          # @param version [String, nil] the requested version, e.g. "9.4"
+          # @param architecture [String, nil] the requested architecture
           def initialize(driver, _name, version, architecture)
             # rhel = el
             super(driver, "rhel", version, architecture)
           end
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # RHEL only gained the unprivileged "ec2-user" account in 6.4; earlier
+          # releases are logged into as root.
+          #
+          # @return [String] the default SSH username
           def username
             version && version.to_f < 6.4 ? "root" : "ec2-user"
           end
 
+          # EC2 image filters that select Red Hat Enterprise Linux AMIs published by Red Hat.
+          #
+          # A filter is added for {StandardPlatform#architecture} only when one was
+          # requested, so that an unspecified architecture matches any of them.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the value
+          #   or values it must match
+          # @see StandardPlatform#find_image
           def image_search
             search = {
               "owner-id" => "309956199498",
@@ -44,6 +65,14 @@ module Kitchen
             search
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [El, nil] a platform when the image is Red Hat Enterprise Linux, otherwise nil
           def self.from_image(driver, image)
             return unless /rhel/i.match?(image.name)
 
@@ -51,6 +80,15 @@ module Kitchen
             new(driver, "rhel", (Regexp.last_match || [])[1], image.architecture)
           end
 
+          # Sort images newest release first, preferring generally available
+          # releases over betas.
+          #
+          # A Beta AMI carries a higher version number than the current GA
+          # release, so a plain version sort would select it. Betas are pushed
+          # to the back after sorting.
+          #
+          # @param images [Array<Aws::EC2::Image>] the images to sort
+          # @return [Array<Aws::EC2::Image>] the images, best match first
           def sort_by_version(images)
             # First do a normal version sort
             super(images)

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

@@ -19,16 +19,31 @@ module Kitchen
   module Driver
     class Aws
       class StandardPlatform
+        # Rocky Linux images published by the Rocky Enterprise Software
+        # Foundation.
+        #
+        # @see https://rockylinux.org/cloud-images
         class Rocky < StandardPlatform
           StandardPlatform.platforms["rocky"] = self
           StandardPlatform.platforms["rockylinux"] = self
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # Used as the SSH username when the transport does not specify one.
+          #
+          # @return [String] the default SSH username
           def username
             "rocky"
           end
 
+          # EC2 image filters that select Rocky Linux images published by the Rocky project.
+          #
+          # A filter is added for {StandardPlatform#architecture} only when one was
+          # requested, so that an unspecified architecture matches any of them.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the value
+          #   or values it must match
+          # @see StandardPlatform#find_image
           def image_search
             search = {
               "owner-id" => "792107900819",
@@ -38,10 +53,22 @@ module Kitchen
             search
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [Rocky, nil] a platform when the image is Rocky Linux, otherwise nil
           def self.from_image(driver, image)
             return unless /Rocky-/i.match?(image.name)
 
-            image.name =~ /\b(\d+(\.\d+[\.\d])?)/i
+            # `(\.\d+)?`, not `(\.\d+[\.\d])?`: the character class matched the
+            # separator that follows the minor version, capturing it into the
+            # version string ("2018.03.") and failing outright when the minor
+            # version was followed by anything but a dot or digit.
+            image.name =~ /\b(\d+(\.\d+)?)/i
             new(driver, "rocky", (Regexp.last_match || [])[1], image.architecture)
           end
         end

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

@@ -23,12 +23,23 @@ module Kitchen
         class Ubuntu < StandardPlatform
           StandardPlatform.platforms["ubuntu"] = self
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # Used as the SSH username when the transport does not specify one.
+          #
+          # @return [String] the default SSH username
           def username
             "ubuntu"
           end
 
+          # EC2 image filters that select Ubuntu cloud images published by Canonical.
+          #
+          # A filter is added for {StandardPlatform#architecture} only when one was
+          # requested, so that an unspecified architecture matches any of them.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the value
+          #   or values it must match
+          # @see StandardPlatform#find_image
           def image_search
             search = {
               "owner-id" => "099720109477",
@@ -38,6 +49,14 @@ module Kitchen
             search
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [Ubuntu, nil] a platform when the image is Ubuntu, otherwise nil
           def self.from_image(driver, image)
             return unless /ubuntu/i.match?(image.name)
 

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

@@ -23,34 +23,39 @@ module Kitchen
         class Windows < StandardPlatform
           StandardPlatform.platforms["windows"] = self
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # Used as the SSH username when the transport does not specify one.
+          #
+          # @return [String] the default SSH username
           def username
             "administrator"
           end
 
-          # Figure out the right set of names to search for:
+          # EC2 image filters that select Amazon's Windows Server AMIs.
+          #
+          # Windows AMI names encode the release, an optional revision ("R2")
+          # and an optional service pack, and the naming scheme changed with
+          # Server 2016. The requested version is decomposed by
+          # {#windows_version_parts} and turned into whichever set of name
+          # patterns can match it:
+          #
+          #     "windows"          Windows_Server-*-RTM-, -SP*-, -R*_RTM-,
+          #                        -R*_SP*-, and Windows_Server-*-Full-Base-*
+          #     "windows-2012"     Windows_Server-2012-RTM-, -2012-SP*-
+          #     "windows-2012r2"   Windows_Server-2012-R2_RTM-, -R2_SP*-
+          #     "windows-2012sp1"  Windows_Server-2012-SP1-
+          #     "windows-2012r2sp1" Windows_Server-2012-R2_SP1-
+          #     "windows-2016"     Windows_Server-2016-English-Full-Base-*
+          #     "windows-2019"     Windows_Server-2019-English-Full-Base-*
           #
-          # "windows" -> [nil, nil, nil]
-          #   Windows_Server-*-R*_RTM-, Windows_Server-*-R*_SP*-,
-          #   Windows_Server-*-RTM-, Windows_Server-*-SP*-,
-          #   Windows_Server-*-
-          # "windows-2012" -> [2012, 0, nil]
-          #   Windows_Server-2012-RTM-, Windows_Server-2012-SP*-
-          # "windows-2012r2" -> [2012, 2, nil]
-          #   Windows_Server-2012-R2_RTM-, Windows_Server-2012-R2_SP*-
-          # "windows-2012sp1" -> [2012, 0, 1]
-          #   Windows_Server-2012-SP1-
-          # "windows-2012rtm" -> [2012, 0, 0]
-          #   Windows_Server-2012-RTM-
-          # "windows-2012r2sp1" -> [2012, 2, 1]
-          #   Windows_Server-2012-R2_SP1-
-          # "windows-2012r2rtm" -> [2012, 2, 0]
-          #   Windows_Server-2012-R2_RTM-
-          # "windows-2016" -> [2016, 0, nil]
-          #   Windows_Server-2016-
-          # "windows-2019" -> [2019, 0, nil]
-          #   Windows_Server-2019-
+          # A filter is added for {StandardPlatform#architecture} only when one
+          # was requested, so that an unspecified architecture matches any.
+          #
+          # @return [Hash{String => String, Array<String>}] filter name to the
+          #   value or values it must match
+          # @see #windows_name_filter
+          # @see StandardPlatform#find_image
           def image_search
             search = {
               "owner-alias" => "amazon",
@@ -60,6 +65,15 @@ module Kitchen
             search
           end
 
+          # Sort images newest release first.
+          #
+          # Windows versions cannot be compared as numbers -- "2012r2" is newer
+          # than "2012" but older than "2016" -- so each image is reduced to a
+          # [major, revision, service_pack] tuple and those are compared
+          # instead.
+          #
+          # @param images [Array<Aws::EC2::Image>] the images to sort
+          # @return [Array<Aws::EC2::Image>] the images, newest release first
           def sort_by_version(images)
             # 2008r2rtm -> [ img1, img2, img3 ]
             # 2012r2sp1 -> [ img4, img5 ]
@@ -69,6 +83,14 @@ module Kitchen
               .reverse.flat_map { |_version, platform_images| platform_images }
           end
 
+          # Detect this platform from an EC2 image.
+          #
+          # Matching is done on the image name, which is the only reliable signal
+          # EC2 exposes about what an AMI actually contains.
+          #
+          # @param driver [Kitchen::Driver::Ec2] the driver requesting detection
+          # @param image [Aws::EC2::Image] the image to inspect
+          # @return [Windows, nil] a platform when the image is Windows Server, otherwise nil
           def self.from_image(driver, image)
             return unless /Windows/i.match?(image.name)
 
@@ -88,18 +110,25 @@ module Kitchen
 
           protected
 
-          # Turn windows version into [ major, revision, service_pack ]
+          # Decompose a Windows version string into comparable parts.
+          #
+          # A missing revision becomes 0 so that "2012" and "2012r2" order
+          # correctly against each other. A missing service pack stays nil,
+          # which means "any", while an explicit "rtm" becomes 0.
           #
-          # nil -> [ nil, nil, nil ]
-          # 2012 -> [ 2012, 0, nil ]
-          # 2012r2 -> [ 2012, 2, nil ]
-          # 2012r2sp4 -> [ 2012, 2, 4 ]
-          # 2012sp4 -> [ 2012, 0, 4 ]
-          # 2012rtm -> [ 2012, 0, 0 ]
-          # 2016 -> [ 2016, 0, nil ]
-          # 2019 -> [ 2019, 0, nil ]
-          # 1709 -> [ 1709, 0, nil ]
-          # 1803 -> [ 1803, 0, nil ]
+          #     nil        -> [nil,  nil, nil]
+          #     "2012"     -> [2012, 0,   nil]
+          #     "2012r2"   -> [2012, 2,   nil]
+          #     "2012rtm"  -> [2012, 0,   0]
+          #     "2012sp4"  -> [2012, 0,   4]
+          #     "2012r2sp4"-> [2012, 2,   4]
+          #     "2016"     -> [2016, 0,   nil]
+          #
+          # A leading "server-" is stripped first, so that a platform named
+          # "windows-server-2019" behaves like "windows-2019".
+          #
+          # @return [Array(Integer, Integer, Integer), Array(nil, nil, nil)]
+          #   the major version, revision and service pack
           def windows_version_parts
             version = self.version
             if version
@@ -131,6 +160,10 @@ module Kitchen
 
           private
 
+          # Build the AMI name patterns for the requested version.
+          #
+          # @return [String, Array<String>] a single pattern for releases with a
+          #   predictable name, otherwise every pattern that could match
           def windows_name_filter
             major, revision, service_pack = windows_version_parts
             if [2025, 2022, 2019, 2016].include?(major)

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

@@ -99,7 +99,13 @@ module Kitchen
         #
         # Find the best matching image for the given image search.
         #
-        # @return [String] The image ID (e.g. ami-213984723)
+        # The search hash is converted into EC2's filter format, and the results
+        # are ranked by {#sort_images} before the best match is taken.
+        #
+        # @param image_search [Hash{String => String, Array<String>}] EC2 image
+        #   filters, keyed by filter name
+        # @return [String, nil] the image ID (e.g. "ami-213984723"), or nil when
+        #   the search matched nothing
         def find_image(image_search)
           driver.debug("Searching for images matching #{image_search} ...")
           # Convert to ec2 search format (pairs of name+values)
@@ -120,12 +126,18 @@ module Kitchen
         # The list of StandardPlatform objects. StandardPlatforms register
         # themselves with this.
         #
-        # @return Array[Kitchen::Driver::Aws::StandardPlatform]
+        # @return [Array<Kitchen::Driver::Aws::StandardPlatform>]
         #
         def self.platforms
           @platforms ||= {}
         end
 
+        # A human-readable description of this platform.
+        #
+        # Version and architecture are omitted when unknown, so an unqualified
+        # platform reads as just "ubuntu" rather than "ubuntu  ".
+        #
+        # @return [String] e.g. "ubuntu 24.04 x86_64"
         def to_s
           "#{name}#{version ? " #{version}" : ""}#{architecture ? " #{architecture}" : ""}"
         end
@@ -162,6 +174,16 @@ module Kitchen
           nil
         end
 
+        # Split a platform string into its parts.
+        #
+        # The trailing segment is only treated as an architecture when it is one
+        # of {SUPPORTED_ARCHITECTURES}; anything else stays part of the version,
+        # so that a typo surfaces as an unmatched version rather than being
+        # silently discarded.
+        #
+        # @param platform_string [String] e.g. "centos-9-x86_64"
+        # @return [Array(String, String, String)] the platform name, version and
+        #   architecture, any of which except the name may be nil
         def self.parse_platform_string(platform_string)
           platform, version = platform_string.split("-", 2)
 
@@ -203,6 +225,16 @@ module Kitchen
 
         # Not supported yet: aix mac_os_x nexus solaris
 
+        # Move images matching a predicate ahead of those that do not.
+        #
+        # This is a stable partition rather than a sort, so it expresses a
+        # preference without disturbing the ordering established by earlier
+        # preferences.
+        #
+        # @param images [Array<Aws::EC2::Image>] the images to reorder
+        # @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
         def prefer(images, &block)
           # Put the matching ones *before* the non-matching ones.
           matching, non_matching = images.partition(&block)
@@ -211,6 +243,14 @@ module Kitchen
 
         private
 
+        # Rank candidate images, best match first.
+        #
+        # Preferences are applied from weakest to strongest, each one a stable
+        # partition, so the last applied wins: version beats virtualization
+        # type, which beats root device type, and so on down to creation date.
+        #
+        # @param images [Array<Aws::EC2::Image>] the images to rank
+        # @return [Array<Aws::EC2::Image>] the images, best match first
         def sort_images(images)
           # P6: We prefer more recent images over older ones
           images = images.sort_by(&:creation_date).reverse
@@ -230,6 +270,10 @@ module Kitchen
           sort_by_version(images)
         end
 
+        # Log the search results, with the platform detected for each image.
+        #
+        # @param images [Array<Aws::EC2::Image>] the images the search returned
+        # @return [void]
         def show_returned_images(images)
           if images.empty?
             driver.error("Search returned 0 images.")