kitchen-ec2 3.22.3 → 3.22.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc2c40634911bf5f8f89a42e04e2bc9e0ea90442390461f49929179e9edd94e0
-  data.tar.gz: 825a61bf6c1db2db9a555b7c53bda74c8c2d56ee69142facedea70512f021aee
+  metadata.gz: 8c45dbb3160767d4ce660a83da145699c8e29f5fbb93b9ccb052ee8c4b8e5eb1
+  data.tar.gz: 8da4c4fdcc43e66e5ae58f722397f8663470b7c34167c3d47ec64219ec99824d
 SHA512:
-  metadata.gz: 99e722e2e64ba7fb67e5e274eb24c37e84b3cfeb93a42532c2060db2481e51f84afc339c81eb1f6cb0b6b7881002479db2d1a5eac852bfc443a27d39a0d14966
-  data.tar.gz: 1ec1e0d25fe8dc48ac3c126b958d7f669257c86e2f0aaa93baf1fb7099ad202e4bcb23ad83e2db630a9997abf09d6717b6a841ae1f1071c6ca546c0f39260f62
+  metadata.gz: 2b035d3317d7134b04811773347768ba33dfd3713ea3726ab124e2bfbc11afa54a23f3bd18f38fc7d01db9b9dd7b8c7d49cfdc4f1e0835e41281f1c6af9d1b4d
+  data.tar.gz: eb00b8d53f41145b6d2deec25c0a840f45be3d5a605907c8f886d52448f667ebcd6496ad279a0f9e82b56938dd1ffbd9a036eb57161e7c3ebef310f883feab08

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

@@ -23,11 +23,26 @@ require "aws-sdk-core/instance_profile_credentials"
 
 module Kitchen
   module Driver
+    # Namespace for the driver's AWS-facing collaborators: the EC2 client
+    # wrapper, the RunInstances payload generator, the platform definitions and
+    # the Instance Connect and SSM Session Manager helpers.
     class Aws
       # A class for creating and managing the EC2 client connection
       #
       # @author Tyler Ball <tball@chef.io>
       class Client
+        # Configure the AWS SDK for this driver's connection settings.
+        #
+        # These settings are applied to the SDK's process-wide configuration
+        # rather than held on this object, so clients built later pick them up.
+        # A nil retry limit is omitted rather than written, so that the SDK's
+        # own default survives.
+        #
+        # @param region [String] the AWS region, e.g. "us-west-2"
+        # @param profile_name [String] shared credentials profile to use
+        # @param http_proxy [String, nil] proxy URL, if any
+        # @param retry_limit [Integer, nil] SDK retry limit, or nil for the default
+        # @param ssl_verify_peer [Boolean] whether to verify TLS peers
         def initialize(
           region,
           profile_name = "default",
@@ -73,15 +88,22 @@ module Kitchen
 
         # check if instance exists, given an id
         # @param id [String] aws instance id
-        # @return boolean
+        # @return [Boolean]
         def instance_exists?(id)
           resource.instance(id).exists?
         end
 
+        # The low-level EC2 client, for API calls with no resource equivalent.
+        #
+        # @return [Aws::EC2::Client]
         def client
           @client ||= ::Aws::EC2::Client.new
         end
 
+        # The EC2 resource interface, for working with instances and images as
+        # objects rather than raw API responses.
+        #
+        # @return [Aws::EC2::Resource]
         def resource
           @resource ||= ::Aws::EC2::Resource.new
         end

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

@@ -1,15 +1,34 @@
 module Kitchen
   module Driver
+    # Namespace for behavior mixed into {Kitchen::Driver::Ec2}.
     module Mixins
+      # Allocation and release of EC2 Dedicated Hosts.
+      #
+      # A dedicated host is physical hardware reserved for one account, required
+      # for `tenancy: host` and for platforms such as macOS. Hosts are billed
+      # from allocation until release regardless of whether an instance is
+      # running on them, so both operations are gated behind explicit config and
+      # failures are fatal rather than warnings.
+      #
+      # Only hosts tagged `ManagedBy: Test Kitchen` are ever considered, so a
+      # user's own dedicated hosts are never allocated to or released.
+      #
+      # This module expects its includer to provide `config`, `ec2` and the
+      # Test Kitchen logging methods; it is mixed into {Kitchen::Driver::Ec2}.
       module DedicatedHosts
-        # check if a suitable dedicated host is available
-        # @return Boolean
+        # Whether any managed host has room for the configured instance type.
+        #
+        # @return [Boolean]
         def host_available?
           !hosts_with_capacity.empty?
         end
 
-        # get dedicated host with capacity for instance type
-        # @return Aws::EC2::Types::Host
+        # Managed hosts with room for the configured instance type.
+        #
+        # T-family hosts report no capacity information and may be
+        # overprovisioned, so a host with no capacity block counts as available.
+        #
+        # @return [Array<Aws::EC2::Types::Host>]
         def hosts_with_capacity
           hosts_managed.select do |host|
             # T-instance hosts do not report available capacity and can be overprovisioned
@@ -18,27 +37,38 @@ module Kitchen
             else
               instance_capacity = host.available_capacity.available_instance_capacity
               capacity_for_type = instance_capacity.detect { |cap| cap.instance_type == config[:instance_type] }
-              capacity_for_type.available_capacity > 0
+              # A host that lists no capacity for this instance type cannot run
+              # one, so treat a missing entry the same as zero rather than
+              # raising on it.
+              !capacity_for_type.nil? && capacity_for_type.available_capacity > 0
             end
           end
         end
 
-        # check if host has no instances running
-        # @param host_id [Aws::EC2::Types::Host] dedicated host
-        # @return Boolean
+        # Whether a host has no instances running on it.
+        #
+        # @param host [Aws::EC2::Types::Host] the host to inspect
+        # @return [Boolean] true when the host can be released
         def host_unused?(host)
           host.instances.empty?
         end
 
-        # get host data for host id
-        # @param host_id [Aws::EC2::Types::Host] dedicated host
-        # @return Array(Aws::EC2::Types::Host)
+        # Look a dedicated host up by ID.
+        #
+        # @param host_id [String] the host ID, e.g. "h-0123456789abcdef0"
+        # @return [Aws::EC2::Types::Host, nil] the host, or nil when EC2 does
+        #   not know it
         def host_for_id(host_id)
-          ec2.client.describe_hosts(host_ids: [host_id])&.first
+          ec2.client.describe_hosts(host_ids: [host_id]).hosts.first
         end
 
-        # get dedicated hosts managed by Test Kitchen
-        # @return Array(Aws::EC2::Types::Host)
+        # Available dedicated hosts that Test Kitchen allocated.
+        #
+        # Filtered on the `ManagedBy` tag so that hosts belonging to the user are
+        # never touched, and on state so that hosts still being provisioned or
+        # already released are ignored.
+        #
+        # @return [Array<Aws::EC2::Types::Host>]
         def hosts_managed
           response = ec2.client.describe_hosts(
             filter: [
@@ -49,8 +79,16 @@ module Kitchen
           response.hosts.select { |host| host.state == "available" }
         end
 
-        # allocate new dedicated host for requested instance type
-        # @return String host id
+        # Allocate a new dedicated host for the configured instance type.
+        #
+        # A `.metal` size occupies a whole host, so it is allocated for that
+        # exact type; every other size can share a host, so the whole instance
+        # family is allocated and EC2 places instances within it.
+        #
+        # @return [String] the new host's ID
+        # @note Terminates the process with `exit!` when allocation is not
+        #   enabled or no availability zone is configured, since an allocated
+        #   host costs money whether or not it is used.
         def allocate_host
           unless allow_allocate_host?
             warn "ERROR: Attempted to allocate dedicated host but need environment variable TK_ALLOCATE_DEDICATED_HOST to be set"
@@ -91,9 +129,12 @@ module Kitchen
           response.host_ids.first
         end
 
-        # deallocate a dedicated host
-        # @param host_id [String] dedicated host id
-        # @return Aws::EC2::Types::ReleaseHostsResult
+        # Release a dedicated host.
+        #
+        # @param host_id [String] the host to release
+        # @return [nil] when the host was released successfully
+        # @note Terminates the process with `exit!` when the release fails, as a
+        #   host that stays allocated keeps accruing charges silently.
         def deallocate_host(host_id)
           info("Deallocating dedicated host #{host_id}")
 
@@ -104,28 +145,32 @@ module Kitchen
           exit!
         end
 
-        # return instance family from type
-        # @param instance_type [String] type in format family.size
-        # @return String instance family
+        # The family part of an instance type.
+        #
+        # @param instance_type [String] a type in "family.size" form, e.g. "m5.large"
+        # @return [String] the family, e.g. "m5"
         def instance_family_from_type(instance_type)
           instance_type.split(".").first
         end
 
-        # return instance size from type
-        # @param instance_type [String] type in format family.size
-        # @return String instance size
+        # The size part of an instance type.
+        #
+        # @param instance_type [String] a type in "family.size" form, e.g. "m5.large"
+        # @return [String] the size, e.g. "large"
         def instance_size_from_type(instance_type)
           instance_type.split(".").last
         end
 
-        # check config, if host allocation is enabled
-        # @return Boolean
+        # Whether the user has opted in to allocating dedicated hosts.
+        #
+        # @return [Boolean]
         def allow_allocate_host?
           config[:allocate_dedicated_host]
         end
 
-        # check config, if host deallocation is enabled
-        # @return Boolean
+        # Whether the user has opted in to releasing dedicated hosts.
+        #
+        # @return [Boolean]
         def allow_deallocate_host?
           config[:deallocate_dedicated_host]
         end

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

@@ -19,13 +19,29 @@ require "aws-sdk-ec2instanceconnect"
 module Kitchen
   module Driver
     class Aws
+      # Pushes short-lived SSH public keys to an instance using EC2 Instance
+      # Connect, so that a connection can be made without a long-lived key pair.
+      #
+      # A pushed key is accepted for roughly sixty seconds, so it is sent again
+      # before each connection rather than once at create time.
       class InstanceConnect
+        # @param config [Hash] the driver config
+        # @param logger [Kitchen::Logger] the logger to report through
         def initialize(config, logger)
           @config = config
           @logger = logger
           @client = ::Aws::EC2InstanceConnect::Client.new(region: config[:region])
         end
 
+        # Push an SSH public key to an instance for a given user.
+        #
+        # @param instance_id [String] the target instance, e.g. "i-0123abcd"
+        # @param username [String] the OS account to authorize the key for
+        # @param public_key [String] the OpenSSH-format public key
+        # @raise [Aws::EC2InstanceConnect::Errors::ServiceError] when the key is
+        #   rejected; there is no usable connection in that case, so the error
+        #   is not swallowed
+        # @return [void]
         def send_ssh_public_key(instance_id, username, public_key)
           @logger.info("Sending SSH public key to instance #{instance_id} for user #{username}")
 

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

@@ -26,18 +26,41 @@ module Kitchen
       #
       # @author Tyler Ball <tball@chef.io>
       class InstanceGenerator
-        attr_reader :config, :ec2, :logger
+        # @return [Hash] the driver config the payload is built from
+        attr_reader :config
 
+        # @return [Kitchen::Driver::Aws::Client] the driver's EC2 client wrapper
+        attr_reader :ec2
+
+        # @return [Kitchen::Logger] the logger to report through
+        attr_reader :logger
+
+        # @param config [Hash] the driver config
+        # @param ec2 [Kitchen::Driver::Aws::Client] the driver's EC2 client wrapper
+        # @param logger [Kitchen::Logger] the logger to report through
         def initialize(config, ec2, logger)
           @config = config
           @ec2 = ec2
           @logger = logger
         end
 
-        # Transform the provided kitchen config into the hash we'll use to create the aws instance
-        # can be passed in null, others need to be omitted if they are null
-        # Some fields can be passed in null, others need to be omitted if they are null
-        # @return [Hash]
+        # Build the RunInstances payload from the driver config.
+        #
+        # Some EC2 fields accept an explicit nil and others must be omitted
+        # entirely, so optional settings are added conditionally rather than
+        # always being present with a nil value.
+        #
+        # Two lookups happen here as a side effect, because both need to resolve
+        # before the payload can be built: a subnet is resolved from
+        # `subnet_filter` (and written back into the config), and security
+        # groups are resolved from `security_group_filter` within that subnet's
+        # VPC. Both are skipped when the corresponding ID is already set.
+        #
+        # @return [Hash] parameters for `Aws::EC2::Resource#create_instances`
+        # @raise [RuntimeError] when a subnet or security group filter matches
+        #   nothing, since launching into an unintended network is worse than
+        #   failing
+        # @see https://docs.aws.amazon.com/sdkforruby/api/Aws/EC2/Resource.html#create_instances-instance_method
         def ec2_instance_data
           # Support for looking up security group id and subnet id using tags.
           vpc_id = nil
@@ -130,21 +153,6 @@ module Kitchen
             i[:tag_specifications] = [instance_tag_spec, volume_tag_spec]
           end
 
-          availability_zone = config[:availability_zone]
-          if availability_zone
-            if /^[a-z]$/i.match?(availability_zone)
-              availability_zone = "#{config[:region]}#{availability_zone}"
-            end
-            i[:placement] = { availability_zone: availability_zone.downcase }
-          end
-          tenancy = config[:tenancy]
-          if tenancy
-            if i.key?(:placement)
-              i[:placement][:tenancy] = tenancy
-            else
-              i[:placement] = { tenancy: }
-            end
-          end
           unless config[:block_device_mappings].nil? || config[:block_device_mappings].empty?
             i[:block_device_mappings] = config[:block_device_mappings]
           end
@@ -177,6 +185,8 @@ module Kitchen
               i[:network_interfaces][0][:ipv_6_address_count] = 1
             end
           end
+          # A bare zone letter is a shorthand for that zone within the
+          # configured region, so "b" in us-west-2 becomes "us-west-2b".
           availability_zone = config[:availability_zone]
           if availability_zone
             if /^[a-z]$/i.match?(availability_zone)
@@ -236,6 +246,18 @@ module Kitchen
           i
         end
 
+        # The user data script, base64 encoded as EC2 requires.
+        #
+        # The configured value is treated as a file path when it names an
+        # existing file, and as inline script content otherwise. Content
+        # containing a null byte is always treated as inline, both because a
+        # path cannot contain one and because `File.file?` would raise on it.
+        #
+        # The result is memoized: the file is read once per driver, not once per
+        # call.
+        #
+        # @return [String, nil] base64 encoded user data, or nil when none is
+        #   configured
         def prepared_user_data
           # If user_data is a file reference, lets read it as such
           return nil if config[:user_data].nil?

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

@@ -23,6 +23,8 @@ module Kitchen
     class Aws
       # Manages AWS Systems Manager Session Manager connections for Test Kitchen
       class SsmSessionManager
+        # @param config [Hash] the driver config
+        # @param logger [Kitchen::Logger] the logger to report through
         def initialize(config, logger)
           @config = config
           @logger = logger
@@ -32,7 +34,13 @@ module Kitchen
           )
         end
 
-        # Check if SSM agent is running on the instance
+        # Whether the SSM agent on an instance has checked in and is reachable.
+        #
+        # Polled while an instance boots, so an API error is reported as "not
+        # ready" rather than raised.
+        #
+        # @param instance_id [String] the instance to check
+        # @return [Boolean] true when the agent is registered and online
         def ssm_agent_available?(instance_id)
           @logger.debug("Checking if SSM agent is available on instance #{instance_id}")
 
@@ -62,7 +70,12 @@ module Kitchen
           end
         end
 
-        # Verify that the AWS CLI session manager plugin is installed
+        # Whether the AWS CLI Session Manager plugin is installed locally.
+        #
+        # The plugin is a separate download from the AWS CLI itself and is
+        # required to open a session.
+        #
+        # @return [Boolean] true when the plugin responds to `--version`
         def session_manager_plugin_installed?
           _output, status = Open3.capture2e("session-manager-plugin", "--version")
           installed = status.success?
@@ -75,7 +88,11 @@ module Kitchen
           end
 
           installed
-        rescue StandardError => e
+        # ::StandardError, not StandardError: this file is nested inside
+        # `module Kitchen`, which defines Kitchen::StandardError. An unqualified
+        # constant resolves to that one, which would let the Errno::ENOENT
+        # raised by a missing plugin escape the check meant to detect it.
+        rescue ::StandardError => e
           @logger.warn("Error checking for session-manager-plugin: #{e.message}")
           false
         end

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

@@ -24,12 +24,23 @@ module Kitchen
           StandardPlatform.platforms["alma"] = self
           StandardPlatform.platforms["almalinux"] = 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 AlmaLinux OS images published by the AlmaLinux 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" => "764336703387",
@@ -39,6 +50,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 [Alma, nil] a platform when the image is AlmaLinux, otherwise nil
           def self.from_image(driver, image)
             return unless /AlmaLinux OS/i.match?(image.name)
 

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

@@ -23,12 +23,23 @@ module Kitchen
         class Amazon < StandardPlatform
           StandardPlatform.platforms["amazon"] = 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 the original Amazon Linux AMIs published by AWS.
+          #
+          # 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" => "137112412989",
@@ -38,10 +49,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 [Amazon, nil] a platform when the image is Amazon Linux, otherwise nil
           def self.from_image(driver, image)
             return unless /amzn-ami/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, "amazon", (Regexp.last_match || [])[1], image.architecture)
           end
         end

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

@@ -23,12 +23,23 @@ module Kitchen
         class Amazon2 < StandardPlatform
           StandardPlatform.platforms["amazon2"] = 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 Linux 2 AMIs published by AWS.
+          #
+          # 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" => "137112412989",
@@ -38,10 +49,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 [Amazon2, nil] a platform when the image is Amazon Linux 2, otherwise nil
           def self.from_image(driver, image)
             return unless /amzn2-ami/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, "amazon2", (Regexp.last_match || [])[1], image.architecture)
           end
         end

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

@@ -23,12 +23,23 @@ module Kitchen
         class Amazon2023 < StandardPlatform
           StandardPlatform.platforms["amazon2023"] = 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 Linux 2023 AMIs published by AWS.
+          #
+          # 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" => "137112412989",
@@ -38,10 +49,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 [Amazon2023, nil] a platform when the image is Amazon Linux 2023, otherwise nil
           def self.from_image(driver, image)
             return unless /al2023-ami/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, "amazon2023", (Regexp.last_match || [])[1], image.architecture)
           end
         end

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

@@ -23,14 +23,31 @@ module Kitchen
         class Centos < StandardPlatform
           StandardPlatform.platforms["centos"] = self
 
+          # The AWS account CentOS publishes its images under. Releases from 8
+          # onwards are published directly rather than through the AWS
+          # Marketplace, so images are found by owner rather than by product.
+          #
+          # @return [String]
           CENTOS_OWNER_ID = "125523088429".freeze
 
-          # default username for this platform's ami
-          # @return [String]
+          # The account EC2 creates on this platform's official AMIs.
+          #
+          # CentOS 8 and earlier ship a "centos" account; Stream 9 moved to the
+          # "ec2-user" convention used by the other EL-family distributions.
+          #
+          # @return [String] the default SSH username
           def username
             version && version.to_f < 9.0 ? "centos" : "ec2-user"
           end
 
+          # EC2 image filters that select CentOS Linux and CentOS Stream 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
             # Version 8+ are published directly, not to the AWS marketplace. Use OWNER ID.
             search = {
@@ -42,6 +59,14 @@ module Kitchen
             search
           end
 
+          # Sort images newest release first.
+          #
+          # CentOS mixes bare majors ("CentOS Stream 9") with dotted releases
+          # ("CentOS 7.9"). A bare major is scored as ".999" so that Stream 9
+          # ranks above 9.0 while still ranking below 10.
+          #
+          # @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)
             # 7.1 -> [ img1, img2, img3 ]
             # 6 -> [ img4, img5 ]
@@ -51,6 +76,14 @@ module Kitchen
               .reverse.flat_map { |_k, v| v }
           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 [Centos, nil] a platform when the image is CentOS, otherwise nil
           def self.from_image(driver, image)
             return unless /centos/i.match?(image.name)