kitchen-dokken 2.23.2 → 2.23.4

data/lib/kitchen/driver/dokken_version.rb

@@ -18,6 +18,6 @@
 module Kitchen
   module Driver
     # Version string for Dokken Kitchen driver
-    DOKKEN_VERSION = "2.23.2".freeze
+    DOKKEN_VERSION = "2.23.4".freeze
   end
 end

data/lib/kitchen/helpers.rb

@@ -1,30 +1,65 @@
+# Shared behaviour for the kitchen-dokken driver, provisioner and transport.
+#
+# Each of those three plugins mixes this in (at the top level, so the methods
+# also land on Object) and supplies the small contract the helpers depend on:
+# `config`, `instance`, `self[]`, `info` and `debug`.
 module Dokken
+  # @see Kitchen::Driver::Dokken
+  # @see Kitchen::Provisioner::Dokken
+  # @see Kitchen::Transport::Dokken
   module Helpers
+    require "digest" unless defined?(Digest)
+    require "fileutils" unless defined?(FileUtils)
     # https://stackoverflow.com/questions/517219/ruby-see-if-a-port-is-open
     require "socket" unless defined?(Socket)
     require "timeout" unless defined?(Timeout)
+    require "tmpdir" unless defined?(Dir.mktmpdir)
     require "resolv" unless defined?(Resolv)
 
+    # How long to wait for a TCP connect before calling a port closed.
+    PORT_PROBE_TIMEOUT = 1
+
+    # Check whether something is accepting TCP connections at `ip:port`.
+    #
+    # Used by the transport to pick a reachable address for the data
+    # container's sshd. Every failure mode -- refused, unroutable,
+    # unresolvable, timed out -- is a "no" rather than an exception, because
+    # the caller's job is to try the next candidate address, not to abort.
+    #
+    # @param ip [String] an address or hostname to probe
+    # @param port [String, Integer] the TCP port to probe
+    # @return [Boolean] true when the connection was accepted
     def port_open?(ip, port)
-      begin
-        Timeout.timeout(1) do
-          s = TCPSocket.new(ip, port)
-          s.close
-          return true
-        rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ENETDOWN
-          return false
-        end
-      rescue Timeout::Error
+      Timeout.timeout(PORT_PROBE_TIMEOUT) do
+        TCPSocket.new(ip, port).close
+        true
+      rescue SystemCallError, SocketError, IOError
+        false
       end
+    rescue Timeout::Error
       false
     end
 
+    # The public half of the throwaway keypair baked into the data image.
+    #
+    # It is deliberately published: the data container is only reachable on
+    # the local docker network for the life of one kitchen run, and shipping
+    # a fixed key avoids generating one per instance.
+    #
+    # @return [String] an OpenSSH `authorized_keys` line
     def insecure_ssh_public_key
       <<~EOF
         ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCoJwyW7qNhw+NTuOjC4+RVpESl+JBXebXzB7JqxRgKAbymq6B39azEAiNx5NzHkWcQmOyQNhFpKFSAufegcXRS4ctS1LcElEoXe9brDAqKEBSkmnXYfZXMNIG0Enw4+5W/rZxHFCAlsUSAHYtYZEs+3CgbIWuHhZ95C8UC6nGLWHNZOjcbsYZFrnFfO0qg0ene2w8LKhxqj5X0MRSdCIn1IwyxIbl5NND5Yk1Hx8JKsJtTiNTdxssiMgmM5bvTbYQUSf8pbGrRI30VQKBgQ8/UkidZbaTfvzWXYpwcDUERSbzEYCvkUytTemZIv6uhpPxqkfjl6KEOOml/iGqquPEr test-kitchen-rsa
       EOF
     end
 
+    # The private half of the throwaway keypair.
+    #
+    # Written to disk 0600 by the transport just before it shells out to
+    # rsync or scp. See {#insecure_ssh_public_key} for why a fixed key is
+    # acceptable here.
+    #
+    # @return [String] a PEM-encoded RSA private key
     def insecure_ssh_private_key
       <<~EOF
         -----BEGIN RSA PRIVATE KEY-----
@@ -57,6 +92,15 @@ module Dokken
       EOF
     end
 
+    # The Dockerfile used to build the data image.
+    #
+    # The data image exists to hold the kitchen and verifier sandboxes and
+    # serve them over ssh, for the cases where the daemon cannot see the
+    # local filesystem: a remote docker host, or kitchen itself running in a
+    # container.
+    #
+    # @param registry [String, nil] a registry to pull the base image from
+    # @return [String] the Dockerfile contents
     def data_dockerfile(registry)
       from = "almalinux:9"
       if registry
@@ -88,6 +132,10 @@ module Dokken
       EOF
     end
 
+    # Build and tag the data image, unless it is already present.
+    #
+    # @param registry [String, nil] a registry to pull the base image from
+    # @return [void]
     def create_data_image(registry)
       return if ::Docker::Image.exist?(data_image)
 
@@ -104,6 +152,9 @@ module Dokken
       i.tag("repo" => repo(data_image), "tag" => tag(data_image), "force" => true)
     end
 
+    # Work out which docker daemon to talk to when the user has not said.
+    #
+    # @return [String] a docker host URL
     def default_docker_host
       if ENV["DOCKER_HOST"]
         ENV["DOCKER_HOST"]
@@ -117,15 +168,39 @@ module Dokken
       end
     end
 
+    # Fetch and cache the daemon's `/info` payload.
+    #
+    # The cache is keyed by host because the driver, provisioner and
+    # transport each resolve their own `:docker_info` default, and a
+    # kitchen.yml may point them at different daemons.
+    #
+    # @param docker_host [String] the docker host URL to query
+    # @return [Hash] the daemon's info payload
     def docker_info(docker_host)
       ::Docker.url = docker_host
 
-      @docker_info ||= ::Docker.info
-    rescue Excon::Error::Socket
-      puts "kitchen-dokken could not connect to the docker host at #{default_docker_host}. Is docker running?"
-      exit!
+      # Keyed by host: the driver, provisioner and transport each resolve
+      # their own :docker_info default and a kitchen.yml may point them at
+      # different daemons. A single memo would hand the second caller the
+      # first daemon's payload, which is what remote_docker_host? keys its
+      # whole local-vs-remote decision off.
+      @docker_info ||= {}
+      @docker_info[docker_host] ||= ::Docker.info
+    rescue Excon::Error::Socket => e
+      # Deliberately a UserError rather than `exit!`. This runs from inside a
+      # `default_config` block, so an `exit!` here takes the whole kitchen
+      # process down mid-resolve: no error banner, no `.kitchen/logs`, and
+      # every other instance in the run abandoned without being destroyed.
+      # A UserError is the failure mode Test Kitchen already knows how to
+      # report, and it leaves the memo empty so a later caller can retry.
+      raise Kitchen::UserError,
+        "kitchen-dokken could not connect to the docker host at #{docker_host}. " \
+        "Is docker running? (#{e.class}: #{e.message})"
     end
 
+    # Create the kitchen and verifier sandbox directories on the host.
+    #
+    # @return [void]
     def dokken_create_sandbox
       info("Creating kitchen sandbox at #{dokken_kitchen_sandbox}")
       FileUtils.mkdir_p(dokken_kitchen_sandbox, mode: 0o755)
@@ -134,22 +209,25 @@ module Dokken
       FileUtils.mkdir_p(dokken_verifier_sandbox, mode: 0o755)
     end
 
+    # Remove the kitchen and verifier sandbox directories from the host.
+    #
+    # `rm_rf` already tolerates a path that is not there, so a sandbox that
+    # was never created -- or that a previous destroy already removed -- is a
+    # no-op rather than an error. The Errno::ENOENT rescues that used to wrap
+    # these calls could never fire.
+    #
+    # @return [void]
     def dokken_delete_sandbox
       info("Deleting kitchen sandbox at #{dokken_kitchen_sandbox}")
-      begin
-        FileUtils.rm_rf(dokken_kitchen_sandbox)
-      rescue Errno::ENOENT
-        debug("Cannot delete #{dokken_kitchen_sandbox}. Does not exist")
-      end
+      FileUtils.rm_rf(dokken_kitchen_sandbox)
 
       info("Deleting verifier sandbox at #{dokken_verifier_sandbox}")
-      begin
-        FileUtils.rm_rf(dokken_verifier_sandbox)
-      rescue Errno::ENOENT
-        debug("Cannot delete #{dokken_verifier_sandbox}. Does not exist")
-      end
+      FileUtils.rm_rf(dokken_verifier_sandbox)
     end
 
+    # The home directory, in a form docker will accept in a bind mount spec.
+    #
+    # @return [String] an absolute path
     def home_dir
       # while dokken_binds avoid invalid bind mount spec "C:/Users/..." error by
       # remote docker host virtual box shared folder on boot2docker created by docker-machine in Windows
@@ -161,23 +239,41 @@ module Dokken
       Dir.home
     end
 
+    # Where the provisioner stages files for this instance.
+    #
+    # @return [String] an absolute path on the host
     def dokken_kitchen_sandbox
       "#{home_dir}/.dokken/kitchen_sandbox/#{instance_name}"
     end
 
+    # Where the verifier stages files for this instance.
+    #
+    # @return [String] an absolute path on the host
     def dokken_verifier_sandbox
       "#{home_dir}/.dokken/verifier_sandbox/#{instance_name}"
     end
 
+    # A container-safe, collision-free name for this kitchen instance.
+    #
+    # The working directory is hashed into the prefix so that the same suite
+    # in two checkouts does not fight over one set of containers.
+    #
+    # @return [String] the instance name
     def instance_name
       prefix = (Digest::SHA2.hexdigest FileUtils.pwd)[0, 10]
       "#{prefix}-#{instance.name}".downcase
     end
 
+    # The `ExposedPorts` value for the runner container.
+    #
+    # @return [Hash, nil] a Docker API ExposedPorts hash
     def exposed_ports
       coerce_exposed_ports(config[:ports])
     end
 
+    # Network creation options for the dokken network.
+    #
+    # @return [Hash] options for `POST /networks/create`
     def network_settings
       if self[:ipv6]
         {
@@ -193,10 +289,17 @@ module Dokken
       end
     end
 
+    # The `PortBindings` value for the runner container.
+    #
+    # @return [Hash, nil] a Docker API PortBindings hash
     def port_bindings
       coerce_port_bindings(config[:ports])
     end
 
+    # Normalise a `ports:` setting into a Docker API ExposedPorts hash.
+    #
+    # @param v [Hash, Array<String>, String, nil] the configured ports
+    # @return [Hash, nil] an ExposedPorts hash, or nil to omit the key
     def coerce_exposed_ports(v)
       case v
       when Hash, nil
@@ -208,6 +311,10 @@ module Dokken
       end
     end
 
+    # Normalise a `ports:` setting into a Docker API PortBindings hash.
+    #
+    # @param v [Hash, Array<String>, String, nil] the configured ports
+    # @return [Hash, nil] a PortBindings hash, or nil to omit the key
     def coerce_port_bindings(v)
       case v
       when Hash, nil
@@ -225,6 +332,15 @@ module Dokken
       end
     end
 
+    # Parse one docker-style port spec into its component bindings.
+    #
+    # Accepts `container`, `host:container` and `host_ip:host:container`,
+    # each optionally suffixed with `/protocol` and each allowing an
+    # inclusive `low-high` container port range.
+    #
+    # @param v [String] a port specification
+    # @return [Array<Hash>] one entry per container port
+    # @raise [Kitchen::UserError] if a port range is inverted
     def parse_port(v)
       parts = v.split(":")
       case parts.length
@@ -240,14 +356,28 @@ module Dokken
         host_ip = ""
         host_port = ""
         container_port = parts[0]
+      else
+        # Without this the case fell through leaving container_port nil and
+        # the user got `undefined method 'split' for nil` from the line below.
+        # An IPv6 host address is how this gets hit in the wild:
+        # "[::1]:8500:8500" splits on ":" into five parts, not three.
+        raise Kitchen::UserError,
+          "Invalid port spec #{v.inspect}: expected container, host:container " \
+          "or host_ip:host:container. An IPv6 host address cannot be used here."
       end
+      # `split` drops trailing empty fields, so several plausible typos leave
+      # nil where a port should be and only fail further down with an error
+      # naming a type instead of a port: "/" splits to [], "8080-" to
+      # ["8080"], "-" to []. Each of those used to surface as
+      # `undefined method 'include?' for nil` or `comparison of Integer with
+      # nil failed` in front of a user who simply mistyped kitchen.yml.
       port_range, protocol = container_port.split("/")
-      if port_range.include?("-")
-        port_range = container_port.split("-")
-        port_range.map!(&:to_i)
-        Chef::Log.fatal("FATAL: Invalid port range! #{container_port}") if port_range[0] > port_range[1]
-        port_range = (port_range[0]..port_range[1]).to_a
+      if port_range.nil? || port_range.empty?
+        raise Kitchen::UserError,
+          "Invalid port spec #{v.inspect}: no container port"
       end
+
+      port_range = expand_port_range(port_range, v) if port_range.include?("-")
       # qualify the port-binding protocol even when it is implicitly tcp #427.
       protocol = "tcp" if protocol.nil?
       Array(port_range).map do |port|
@@ -259,18 +389,67 @@ module Dokken
       end
     end
 
+    # Expand an inclusive `low-high` container port range.
+    #
+    # @param range [String] the range, e.g. "8080-8082"
+    # @param spec [String] the whole port spec, for the error message
+    # @return [Array<Integer>] every port in the range
+    # @raise [Kitchen::UserError] if either end is missing or not a number,
+    #   or if the range is inverted
+    def expand_port_range(range, spec)
+      low, high = range.split("-")
+
+      unless numeric_port?(low) && numeric_port?(high)
+        raise Kitchen::UserError,
+          "Invalid port range #{range.inspect} in port spec #{spec.inspect}: " \
+          "expected two port numbers separated by a dash, as in 8080-8082"
+      end
+
+      low = low.to_i
+      high = high.to_i
+
+      if low > high
+        raise Kitchen::UserError,
+          "Invalid port range #{range.inspect} in port spec #{spec.inspect}: " \
+          "the low port must not be greater than the high port"
+      end
+
+      (low..high).to_a
+    end
+
+    # @param value [String, nil] a candidate port number
+    # @return [Boolean] whether it is a bare, non-empty run of digits
+    def numeric_port?(value)
+      !value.nil? && value.match?(/\A\d+\z/)
+    end
+
+    # Whether the daemon is somewhere that cannot see the local filesystem.
+    #
+    # Docker Desktop and Boot2Docker are reached over tcp but share the
+    # host's files, so they count as local no matter what the URL says.
+    #
+    # @return [Boolean] true when the sandbox must be shipped over ssh
     def remote_docker_host?
-      return false if config[:docker_info]["OperatingSystem"].include?("Docker Desktop")
-      return false if config[:docker_info]["OperatingSystem"].include?("Boot2Docker")
+      # Podman and some rootless daemons omit OperatingSystem entirely, so
+      # coerce before matching rather than calling #include? on nil.
+      operating_system = config[:docker_info].to_h["OperatingSystem"].to_s
+      return false if operating_system.include?("Docker Desktop")
+      return false if operating_system.include?("Boot2Docker")
       return true if /^tcp:/.match?(config[:docker_host_url])
 
       false
     end
 
+    # Whether kitchen itself is running inside a container.
+    #
+    # @return [Boolean] true when running in Docker
     def running_inside_docker?
       File.file?("/.dockerenv")
     end
 
+    # Whether kitchen is running inside Docker Desktop specifically.
+    #
+    # @return [Boolean] true when `host.docker.internal` resolves
     def running_inside_docker_desktop?
       Resolv.getaddress "host.docker.internal."
       true
@@ -278,14 +457,23 @@ module Dokken
       false
     end
 
+    # Where the verifier stages files for this instance.
+    #
+    # @return [String] an absolute path on the host
     def sandbox_path
       "#{Dir.home}/.dokken/verifier_sandbox/#{instance_name}"
     end
 
+    # The entries staged in the verifier sandbox, for upload.
+    #
+    # @return [Array<String>] absolute paths
     def sandbox_dirs
       Dir.glob(File.join(sandbox_path, "*"))
     end
 
+    # Create the verifier sandbox directory if it is missing.
+    #
+    # @return [void]
     def create_sandbox
       info("Creating kitchen sandbox in #{sandbox_path}")
       unless ::Dir.exist?(sandbox_path)
@@ -293,25 +481,45 @@ module Dokken
       end
     end
 
+    # The path the kitchen sandbox is mounted at inside the container.
+    #
+    # @return [String] an absolute path inside the container
     def resolved_root_path
       instance.provisioner[:root_path] || "/opt/kitchen"
     end
   end
 end
 
+# Redirect the stock Test Kitchen sandboxes into ~/.dokken.
+#
+# Every dokken container bind-mounts (or rsyncs) these directories, so they
+# have to live at a stable, per-instance path that the docker daemon can see
+# -- not in the random tmpdir the base classes would otherwise use.
 module Kitchen
   module Provisioner
+    # @see Dokken::Helpers
     class Base
+      # Create the kitchen sandbox under ~/.dokken.
+      #
+      # @return [void]
       def create_sandbox
         info("Creating kitchen sandbox in #{sandbox_path}")
         FileUtils.mkdir_p(sandbox_path, mode: 0o755)
       end
 
+      # Where the provisioner stages files for this instance.
+      #
       # this MUST be named 'sandbox_path' because ruby.
+      #
+      # @return [String] an absolute path on the host
       def sandbox_path
         "#{Dir.home}/.dokken/kitchen_sandbox/#{instance_name}"
       end
 
+      # A container-safe, collision-free name for this kitchen instance.
+      #
+      # @return [String] the instance name
+      # @see Dokken::Helpers#instance_name
       def instance_name
         prefix = (Digest::SHA2.hexdigest FileUtils.pwd)[0, 10]
         "#{prefix}-#{instance.name}".downcase
@@ -320,9 +528,16 @@ module Kitchen
   end
 end
 
+# Redirect the stock verifier sandbox into ~/.dokken, and teach the verifier
+# to upload it when the daemon cannot read the host filesystem.
 module Kitchen
+  # @see Kitchen::Verifier::Base
   module Verifier
+    # @see Dokken::Helpers
     class Base
+      # Create the verifier sandbox under ~/.dokken.
+      #
+      # @return [void]
       def create_sandbox
         info("Creating kitchen sandbox in #{sandbox_path}")
         unless ::Dir.exist?(sandbox_path)
@@ -330,15 +545,30 @@ module Kitchen
         end
       end
 
+      # Where the verifier stages files for this instance.
+      #
+      # @return [String] an absolute path on the host
       def sandbox_path
         "#{Dir.home}/.dokken/verifier_sandbox/#{instance_name}"
       end
 
+      # A container-safe, collision-free name for this kitchen instance.
+      #
+      # @return [String] the instance name
+      # @see Dokken::Helpers#instance_name
       def instance_name
         prefix = (Digest::SHA2.hexdigest FileUtils.pwd)[0, 10]
         "#{prefix}-#{instance.name}".downcase
       end
 
+      # Run the verifier against the instance.
+      #
+      # Files are only uploaded when the driver built a data container, which
+      # it does exactly when the daemon cannot read the host filesystem.
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if the transport fails
       def call(state)
         create_sandbox
         instance.transport.connection(state) do |conn|

data/lib/kitchen/provisioner/dokken.rb

@@ -22,7 +22,15 @@ require_relative "../helpers"
 include Dokken::Helpers
 
 module Kitchen
+  # @see Kitchen::Provisioner::Dokken
   module Provisioner
+    # Provisioner for the dokken driver.
+    #
+    # Unlike its ChefInfra parent this provisioner never installs chef: the
+    # driver mounts /opt/chef into the runner from a volume container built
+    # from the requested image, so all that is left to do here is stage the
+    # sandbox and run the client.
+    #
     # @author Sean OMeara <sean@sean.io>
     class Dokken < Kitchen::Provisioner::ChefInfra
       kitchen_provisioner_api_version 2
@@ -63,6 +71,10 @@ module Kitchen
       default_config :clean_dokken_sandbox, true
 
       # (see Base#call)
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if the transport fails
       def call(state)
         create_sandbox
         write_run_command(run_command)
@@ -98,6 +110,9 @@ module Kitchen
       # super in that case so the parent's own check_license runs. We test
       # for both because a partial drop-in shim may define
       # license_acceptance_id without pulling in license-acceptance.
+      #
+      # @return [void]
+      # @raise [LicenseAcceptance::LicenseNotAcceptedError] if declined
       def check_license
         return super unless respond_to?(:license_acceptance_id, true) && defined?(LicenseAcceptance)
 
@@ -119,11 +134,17 @@ module Kitchen
         config[:chef_license] ||= acceptor.acceptance_value
       end
 
+      # Normalise the chef command-line settings before they are assembled.
+      #
+      # @return [void]
       def validate_config
         # check if we have an space for the user provided options
         # or add it if not to avoid issues
+        # Assign rather than String#prepend: config values can be frozen
+        # literals, and mutating them in place edits the user's kitchen.yml
+        # data for the rest of the run.
         unless config[:chef_options].start_with? " "
-          config[:chef_options].prepend(" ")
+          config[:chef_options] = " #{config[:chef_options]}"
         end
 
         # strip spaces from all other options
@@ -139,29 +160,57 @@ module Kitchen
 
       private
 
+      # The chef-client invocation staged into the sandbox as `run_command`.
+      #
       # patching Kitchen::Provisioner::ChefInfra#run_command
+      #
+      # @return [String] a shell command line
+      # @api private
       def run_command
         validate_config
-        cmd = config[:chef_binary]
+
+        # Build into a fresh String: appending straight onto
+        # config[:chef_binary] rewrote the configured binary path, so asking
+        # for the command twice returned the arguments twice over.
+        #
+        # :profile_ruby and :slow_resource_report are deliberately not handled
+        # here -- ChefInfra#chef_args already appends both, and adding them a
+        # second time produced a duplicated (and unseparated) flag.
+        cmd = +""
+        cmd << config[:chef_binary]
         cmd << config[:chef_options].to_s
         cmd << " -l #{config[:chef_log_level]}"
         cmd << " -F #{config[:chef_output_format]}"
         cmd << " -c #{File.join(config[:root_path], "client.rb")}"
         cmd << " -j #{File.join(config[:root_path], "dna.json")}"
-        cmd << "--profile-ruby" if config[:profile_ruby]
-        cmd << "--slow-report" if config[:slow_resource_report]
 
         chef_cmd(cmd)
       end
 
+      # Stage the converge command in the kitchen sandbox.
+      #
+      # Writing a script and running `sh run_command` keeps the command line
+      # short enough for `docker exec`, which the full chef invocation is not.
+      #
+      # @param command [String] the shell command line to stage
+      # @return [void]
+      # @api private
       def write_run_command(command)
         File.write("#{dokken_kitchen_sandbox}/run_command", command, mode: "wb")
       end
 
+      # The container the converge runs in.
+      #
+      # @return [String] the container name
+      # @api private
       def runner_container_name
         instance.name.to_s
       end
 
+      # Empty the sandbox after a converge, keeping the directory itself.
+      #
+      # @return [void]
+      # @api private
       def cleanup_dokken_sandbox
         return if sandbox_path.nil?