kitchen-dokken 2.23.6 → 2.23.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c7f5b5652cdde267df1ead2dad29ea1c7e3f642cec4b86f3c5ef4c13612a3f3
-  data.tar.gz: 8b94c596b93899da42069d35faed37d4be565c9af5617839ee84f9e44fcc9a86
+  metadata.gz: a0dffedb0556f642eb7b9011de7ce16d3002b7fc94fc4f99e1f0350a3e593865
+  data.tar.gz: 0542043deb31d066f65640e32faaf45f66c62d6c5e77b8efa569d30dbbfa0ecf
 SHA512:
-  metadata.gz: d48c19a4bdbed503978b68451cded18f2437d2aa0c048d8285344447c4a27503b48937eaf29d93d2fd429316f9c8db240942f09a3333616c939a5cd58555f26d
-  data.tar.gz: 305e81615cc269fdfc685436bbd19b47de69c465006c8ac7b55b42eb8911e4dbfd3e2b36759417347e109c56418176dfa69b5f5136f33669ff2b3e5ffbed4f62
+  metadata.gz: f0717edbd835bdba7ba34d86f051b19427506871cde23003d7cd11c9ccf2fdc32a876d02b32c66fb0b370382648863053b671046d921e04318d5ebf13af0a580
+  data.tar.gz: 7d99975e0a3532d9c62acd42cf84cc258514bb591621d63de40f53f1b814b090cc8d7eac777b7fbd179d7a6b81e1a38ae461e957db6a551bb91fd7a53c98491a

data/lib/kitchen/driver/dokken.rb

@@ -240,17 +240,41 @@ module Kitchen
 
       # Pull the human-readable reason out of a failed build response.
       #
-      # The daemon usually answers with a JSON document carrying an "error"
-      # key, but a proxy or a plain-text 500 does not -- and a JSON::ParserError
-      # raised from inside the rescue clause would bury the real failure.
-      #
       # @param error [Exception] the error docker-api raised
       # @return [String] the daemon's explanation, or the raw response
       def build_error_detail(error)
-        last_line = error.to_s.split("\r\n").last.to_s
-        JSON.parse(last_line)["error"].to_s
+        daemon_message(error.to_s.split("\r\n").last.to_s)
+      end
+
+      # Pull the human-readable reason out of a docker-api error.
+      #
+      # docker-api raises with the daemon's response body as the message, so
+      # what reaches a rescue clause is a JSON document rather than a sentence:
+      # `{"message":"driver failed programming external connectivity ..."}`.
+      # Reporting that verbatim is barely better than reporting nothing.
+      #
+      # @param error [Exception] the error docker-api raised
+      # @return [String] the daemon's explanation, or the raw response
+      def docker_error_detail(error)
+        daemon_message(error.to_s)
+      end
+
+      # The explanation carried in a docker daemon response body.
+      #
+      # Most endpoints answer with a "message" key and the /build stream with
+      # an "error" one. A proxy or a plain-text 500 answers with neither -- and
+      # a JSON::ParserError raised from inside a rescue clause would bury the
+      # very failure it was called on to explain -- so anything unparseable
+      # comes back unchanged.
+      #
+      # @param body [String] a response body
+      # @return [String] the explanation, or the body unchanged
+      def daemon_message(body)
+        parsed = JSON.parse(body)
+        detail = parsed["message"] || parsed["error"]
+        detail.nil? ? body : detail.to_s
       rescue JSON::ParserError, TypeError
-        last_line
+        body
       end
 
       # The Dockerfile for the work image.
@@ -805,7 +829,11 @@ module Kitchen
         with_retries { @image = ::Docker::Image.get(name, { "platform" => oci_platform(config[:platform]) }, docker_connection) }
         with_retries { @image.remove(force: true) }
       rescue ::Docker::Error::DockerError
-        puts "Image #{name} not found. Nothing to delete."
+        # `debug`, not `puts`: this is routine during destroy, and writing
+        # straight to stdout puts it outside kitchen's logging entirely --
+        # it bypasses the log level, never reaches `.kitchen/logs`, and
+        # interleaves with kitchen's own output.
+        debug "Image #{name} not found. Nothing to delete."
       end
 
       # Whether the daemon knows about a container.
@@ -879,7 +907,7 @@ module Kitchen
       # @raise [RuntimeError] if the container could not be created
       def create_container(args, platform: nil)
         with_retries { @container = ::Docker::Container.get(args["name"], {}, docker_connection) }
-      rescue
+      rescue ::Docker::Error::NotFoundError
         with_retries do
           # Merge rather than append: start_runner_container passes config[:env]
           # straight through, so mutating args["Env"] would edit the driver's
@@ -895,7 +923,11 @@ module Kitchen
           end
         rescue ::Docker::Error::DockerError => e
           debug "driver - error :#{e}:"
-          raise "driver - failed to create_container #{args["name"]}"
+          # The daemon's reason used to be dropped here, leaving `kitchen
+          # create` to report a bare "failed to create_container <name>" with
+          # nothing to act on -- the explanation existed, but only for someone
+          # who already knew to re-run at `-l debug`.
+          raise "driver - failed to create_container #{args["name"]}: #{docker_error_detail(e)}"
         end
       end
 
@@ -939,15 +971,35 @@ module Kitchen
       # @raise [Kitchen::ActionFailed] if the container will not stay running
       def run_container(args, platform: nil)
         @container = create_container(args, platform: platform)
-        with_retries do
-          @container.start
-          @container = ::Docker::Container.get(args["name"], {}, docker_connection)
-          wait_running_state(args["name"], true)
-        end
+        start_container!(args["name"])
         assert_running!(args["name"])
         @container
       end
 
+      # Start a container and wait for it to be running.
+      #
+      # `start!`, not `start`: docker-api defines the unsuffixed form as "the
+      # same, but rescue from ServerErrors", so every reason the daemon
+      # refused -- a port already bound, an invalid mount, a capability the
+      # kernel will not grant -- was swallowed on the way past. `with_retries`
+      # then had nothing to retry and `assert_running!` was left to report a
+      # container that "exited immediately" when in truth it had never
+      # started, sending the user off to read `docker logs` output that does
+      # not exist.
+      #
+      # @param name [String] the container name
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if the daemon would not start it
+      def start_container!(name)
+        with_retries do
+          @container.start!
+          @container = ::Docker::Container.get(name, {}, docker_connection)
+          wait_running_state(name, true)
+        end
+      rescue ::Docker::Error::DockerError => e
+        raise ActionFailed, "The #{name} container could not be started: #{docker_error_detail(e)}"
+      end
+
       # Fail the action when a container that has to run is not running.
       #
       # wait_running_state stops polling as soon as `FinishedAt` is set, which
@@ -966,10 +1018,25 @@ module Kitchen
       def assert_running!(name)
         return if container_state["Running"]
 
-        raise ActionFailed,
-          "The #{name} container exited immediately after being started. " \
-          "Its pid 1 did not stay up: check `pid_one_command`, `entrypoint`, " \
-          "and that the image can boot (`docker logs #{name}` shows why)."
+        raise ActionFailed, "The #{name} container is not running. #{not_running_reason(name)}"
+      end
+
+      # Why a container that should be running is not.
+      #
+      # The daemon records its own refusal in `State.Error` and leaves
+      # `FinishedAt` unset, which is a different failure from a pid 1 that
+      # started and exited -- and pointing at `docker logs` for the first kind
+      # sends the user to an empty file.
+      #
+      # @param name [String] the container name
+      # @return [String] a sentence naming the likely cause
+      def not_running_reason(name)
+        daemon_error = container_state["Error"].to_s
+        return "The docker daemon refused to start it: #{daemon_error}" unless daemon_error.empty?
+
+        "Its pid 1 exited immediately (exit code #{container_state["ExitCode"]}): " \
+          "check `pid_one_command`, `entrypoint`, and that the image can boot " \
+          "(`docker logs #{name}` shows why)."
       end
 
       # The current container's `State` payload.

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.6".freeze
+    DOKKEN_VERSION = "2.23.8".freeze
   end
 end

data/lib/kitchen/helpers.rb

@@ -253,17 +253,30 @@ module Dokken
       "#{home_dir}/.dokken/verifier_sandbox/#{instance_name}"
     end
 
-    # A container-safe, collision-free name for this kitchen instance.
+    # A container-safe, collision-free name for a 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.
     #
+    # Defined on the module itself because Kitchen's Provisioner and Verifier
+    # base classes need the same answer but do not mix this module in -- they
+    # used to carry their own copies of these two lines, and three copies of
+    # a container-naming rule is three chances for them to drift apart.
+    #
+    # @param instance [Object] the kitchen instance
     # @return [String] the instance name
-    def instance_name
+    def self.instance_name_for(instance)
       prefix = (Digest::SHA2.hexdigest FileUtils.pwd)[0, 10]
       "#{prefix}-#{instance.name}".downcase
     end
 
+    # (see Dokken::Helpers.instance_name_for)
+    #
+    # @return [String] the instance name
+    def instance_name
+      ::Dokken::Helpers.instance_name_for(instance)
+    end
+
     # The `ExposedPorts` value for the runner container.
     #
     # @return [Hash, nil] a Docker API ExposedPorts hash
@@ -338,10 +351,15 @@ module Dokken
     # each optionally suffixed with `/protocol` and each allowing an
     # inclusive `low-high` container port range.
     #
-    # @param v [String] a port specification
+    # @param v [String, Integer] a port specification
     # @return [Array<Hash>] one entry per container port
-    # @raise [Kitchen::UserError] if a port range is inverted
+    # @raise [Kitchen::UserError] if a port range is inverted or unpairable
     def parse_port(v)
+      # `ports: [8080]` is a perfectly natural thing to write, and YAML hands
+      # it over as an Integer. That used to reach String#split and abort the
+      # create with `undefined method 'split' for an instance of Integer`,
+      # which names a type rather than the line of kitchen.yml at fault.
+      v = v.to_s
       parts = v.split(":")
       case parts.length
       when 3
@@ -377,18 +395,63 @@ module Dokken
           "Invalid port spec #{v.inspect}: no container port"
       end
 
-      port_range = expand_port_range(port_range, v) if port_range.include?("-")
+      container_ports = port_range.include?("-") ? expand_port_range(port_range, v) : [port_range]
       # qualify the port-binding protocol even when it is implicitly tcp #427.
       protocol = "tcp" if protocol.nil?
-      Array(port_range).map do |port|
+      host_ports = expand_host_ports(host_port, container_ports.length, v)
+
+      container_ports.each_with_index.map do |port, i|
         {
           "host_ip" => host_ip,
-          "host_port" => host_port,
+          "host_port" => host_ports[i],
           "container_port" => "#{port}/#{protocol}",
         }
       end
     end
 
+    # Work out the host port that pairs with each container port.
+    #
+    # Docker pairs ranges off one for one -- `8080-8082:9090-9092` publishes
+    # 9090 on 8080, 9091 on 8081 and 9092 on 8082 -- but only the container
+    # side used to be expanded here, so every binding was handed the whole
+    # host range as its `HostPort`. That reads as "any free port in this
+    # range" to the daemon, which meant the mapping was only correct while the
+    # whole range happened to be free, and otherwise came out shifted or
+    # failed outright with "all ports are allocated" rather than naming the
+    # port that was taken.
+    #
+    # @param host_port [String] the host half of the spec
+    # @param count [Integer] how many container ports were asked for
+    # @param spec [String] the whole port spec, for the error message
+    # @return [Array<String>] one host port per container port
+    # @raise [Kitchen::UserError] if the two sides cannot be paired
+    def expand_host_ports(host_port, count, spec)
+      # `ports: '8080'` names no host port at all; the daemon picks one.
+      return Array.new(count, host_port) if host_port.empty?
+
+      unless host_port.include?("-")
+        return [host_port] if count == 1
+
+        raise Kitchen::UserError,
+          "Invalid port spec #{spec.inspect}: a single host port cannot be paired with " \
+          "a range of #{count} container ports. Give a host range of the same size, " \
+          "as in 8080-8082:9090-9092."
+      end
+
+      # A host range against a single container port is docker's "publish this
+      # on any free port in the range". The daemon does the choosing, so the
+      # range is handed over untouched.
+      return [host_port] if count == 1
+
+      host_ports = expand_port_range(host_port, spec)
+      return host_ports.map(&:to_s) if host_ports.length == count
+
+      raise Kitchen::UserError,
+        "Invalid port spec #{spec.inspect}: the host range covers #{host_ports.length} " \
+        "ports and the container range covers #{count}. Docker pairs them off one for " \
+        "one, so both ranges have to be the same size."
+    end
+
     # Expand an inclusive `low-high` container port range.
     #
     # @param range [String] the range, e.g. "8080-8082"
@@ -453,7 +516,12 @@ module Dokken
     def running_inside_docker_desktop?
       Resolv.getaddress "host.docker.internal."
       true
-    rescue
+    # Deliberately every StandardError, spelled out rather than bare. This is
+    # a probe: "can I resolve host.docker.internal" has exactly two useful
+    # answers, and a DNS timeout or a SocketError must be "no" rather than
+    # something that aborts a converge. Listing Resolv::ResolvError as well
+    # would be redundant -- it is a StandardError already.
+    rescue ::StandardError
       false
     end
 
@@ -521,8 +589,7 @@ module Kitchen
       # @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
+        ::Dokken::Helpers.instance_name_for(instance)
       end
     end
   end
@@ -557,8 +624,7 @@ module Kitchen
       # @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
+        ::Dokken::Helpers.instance_name_for(instance)
       end
 
       # Run the verifier against the instance.

data/lib/kitchen/provisioner/dokken.rb

@@ -79,7 +79,17 @@ module Kitchen
         create_sandbox
         write_run_command(run_command)
         instance.transport.connection(state) do |conn|
-          if remote_docker_host? || running_inside_docker?
+          # Gate on what the driver recorded, not on a fresh probe. The driver
+          # already answered this at create time -- it built a data container
+          # or it did not -- and re-deriving the answer here means the two can
+          # disagree. Point DOCKER_HOST somewhere else between `kitchen
+          # create` and `kitchen converge` and they do: this side decides to
+          # upload, the container it would upload through was never created,
+          # and the transport dies on nil several frames down.
+          #
+          # Kitchen::Verifier::Base#call has always gated on the recorded
+          # state; this is the provisioner agreeing with it.
+          unless state[:data_container].nil?
             info("Transferring files to #{instance.to_str}")
             conn.upload(sandbox_dirs, config[:root_path])
           end
@@ -156,6 +166,16 @@ module Kitchen
         # just use the defaults
         config[:chef_log_level] = "warn" if config[:chef_log_level].empty?
         config[:chef_output_format] = "doc" if config[:chef_output_format].empty?
+
+        # ChefBase#chef_args appends `--log_level #{config[:log_level]}` to
+        # whatever base command it is handed, so the parent's flag lands
+        # *after* the `-l` built below. `-l` and `--log_level` are the same
+        # chef-client option and the last occurrence wins, which meant
+        # chef_log_level was parsed, written into the staged run_command, and
+        # then silently overridden by the parent's default of "auto".
+        # Keeping the two in step makes the documented setting the one chef
+        # actually runs at.
+        config[:log_level] = config[:chef_log_level]
       end
 
       private
@@ -204,7 +224,7 @@ module Kitchen
       # @return [String] the container name
       # @api private
       def runner_container_name
-        instance.name.to_s
+        instance_name.to_s
       end
 
       # Empty the sandbox after a converge, keeping the directory itself.

data/lib/kitchen/transport/dokken.rb

@@ -121,6 +121,17 @@ module Kitchen
         # @raise [Kitchen::UserError] if docker_host_url is not tcp:// or unix://
         # @raise [Kitchen::Transport::TransportFailed] if the copy fails
         def upload(locals, remote)
+          # Every route through ssh_endpoint reads the data container out of
+          # state, so being handed none is not a transfer that fails -- it is
+          # a caller that should not have asked. Said plainly here rather than
+          # as `undefined method '[]' for nil` from three frames down.
+          if options[:data_container].nil?
+            raise Kitchen::Transport::TransportFailed,
+              "Cannot upload to #{options[:instance_name]}: no data container was created " \
+              "for this instance. Files are only shipped over ssh when the docker daemon " \
+              "cannot read the local filesystem; otherwise the sandbox is bind-mounted."
+          end
+
           ssh_ip, ssh_port = ssh_endpoint
 
           debug "ssh_ip : #{ssh_ip}"
@@ -477,7 +488,11 @@ module Kitchen
       # @return [TrueClass,FalseClass]
       def docker_for_mac_or_win?
         ::Docker.info(::Docker::Connection.new(config[:docker_host_url], {}))["Name"] == "docker-desktop"
-      rescue
+      # `::StandardError`, spelled out. This method lives inside module
+      # Kitchen, where a bare `StandardError` resolves to
+      # Kitchen::StandardError -- which Excon::Error::Socket is not, so an
+      # unreachable daemon would escape instead of answering "no".
+      rescue ::StandardError
         false
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-dokken
 version: !ruby/object:Gem::Version
-  version: 2.23.6
+  version: 2.23.8
 platform: ruby
 authors:
 - Sean OMeara