kitchen-dokken 2.23.7 → 2.23.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9cac8cad07f229a018567a935e33aaa71edaa04c65dd05a38afbcd10bc839e4
-  data.tar.gz: 971a897b24f4a00f224d995f18ae7177712110ed4048d2a9d02fb03fcd8948a4
+  metadata.gz: a0dffedb0556f642eb7b9011de7ce16d3002b7fc94fc4f99e1f0350a3e593865
+  data.tar.gz: 0542043deb31d066f65640e32faaf45f66c62d6c5e77b8efa569d30dbbfa0ecf
 SHA512:
-  metadata.gz: 578aca5a5d479624c15313d7d6695d8ea42f75e5822ed55f3c083bb9b561b5b0e1378fa0e27964b0444cfd93f1db63eb5d6fc3b124ac977683b792735bfae7d2
-  data.tar.gz: 2bf35be1a50b68a4de9ac5e0d8ac674904165a65f730b472b30c488b9c786890d740586fc7189bf21f22d95fe49cb1bcb2be33456ae37bb43b25d144f3c02854
+  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.
@@ -899,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
 
@@ -943,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
@@ -970,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.7".freeze
+    DOKKEN_VERSION = "2.23.8".freeze
   end
 end

data/lib/kitchen/helpers.rb

@@ -351,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
@@ -390,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"

data/lib/kitchen/provisioner/dokken.rb

@@ -166,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

metadata

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