kitchen-dokken 2.23.7 → 2.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9cac8cad07f229a018567a935e33aaa71edaa04c65dd05a38afbcd10bc839e4
-  data.tar.gz: 971a897b24f4a00f224d995f18ae7177712110ed4048d2a9d02fb03fcd8948a4
+  metadata.gz: 1601bf73b8bb5607d0a279d1d06e3cc5779b581616159b320ee6737210b9bd1d
+  data.tar.gz: 7e92f8c54e09f5746905496fa9388b2fe49f0ec8d7a33f63ac461a0f53c07618
 SHA512:
-  metadata.gz: 578aca5a5d479624c15313d7d6695d8ea42f75e5822ed55f3c083bb9b561b5b0e1378fa0e27964b0444cfd93f1db63eb5d6fc3b124ac977683b792735bfae7d2
-  data.tar.gz: 2bf35be1a50b68a4de9ac5e0d8ac674904165a65f730b472b30c488b9c786890d740586fc7189bf21f22d95fe49cb1bcb2be33456ae37bb43b25d144f3c02854
+  metadata.gz: f6fee7ac1a7586664f3e67047ad994a22c059f6782c99e737a1792dd3758c778f1c8bd3c6f79f6fe1406725dad6f3c1b8d297de1fb9630c4e326d67b23de5d2c
+  data.tar.gz: 1604d52bffac5be374ac62f2a509b584ff43303a5b6c98aed2ed0c1fdcdaa8ec9a8fc8ec17c65a8c56679574ff878452e6ee587ca5bf28e12e8a005f6d845d36

data/kitchen-dokken.gemspec

@@ -19,5 +19,5 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "docker-api", ">= 1.33", "< 3"
   spec.add_dependency "kitchen-omnibus-chef", ">= 1.0"
-  spec.add_dependency "test-kitchen", ">= 1.15", "< 5"
+  spec.add_dependency "test-kitchen", ">= 3.0", "< 5"
 end

data/lib/kitchen/driver/dokken.rb

@@ -23,6 +23,7 @@ require "docker"
 require "shellwords" unless defined?(Shellwords)
 require "base64" unless defined?(Base64)
 require_relative "../helpers"
+require_relative "dokken_version"
 
 include Dokken::Helpers
 
@@ -42,6 +43,14 @@ module Kitchen
     #
     # @author Sean OMeara <sean@sean.io>
     class Dokken < Kitchen::Driver::Base
+      kitchen_driver_api_version 2
+
+      # kitchen-dokken's own version, not test-kitchen's. `kitchen diagnose`
+      # is the first thing a bug report carries, and it used to report the
+      # test-kitchen version here -- which says nothing about the plugin the
+      # report is actually about.
+      plugin_version Kitchen::Driver::DOKKEN_VERSION
+
       default_config :api_retries, 20
       default_config :binds, []
       default_config :cap_add, nil
@@ -143,8 +152,65 @@ module Kitchen
         dokken_delete_sandbox
       end
 
+      # (see Base#status)
+      #
+      # `kitchen list --live` asks the driver whether the instance is really
+      # there rather than trusting the last recorded action, which is exactly
+      # the question a docker daemon can answer precisely. Without this the
+      # driver inherited Base's "unknown", so a container that was plainly
+      # `Up` still listed as `unknown`.
+      #
+      # The runner *is* the instance. The chef container is a shared volume
+      # and the data container only exists on the remote-daemon path, so
+      # neither says anything about whether this instance is up.
+      #
+      # Deliberately not wrapped in {#with_retries}: this backs a listing, and
+      # a slow answer is worse than an honest "unknown".
+      #
+      # @param _state [Hash] mutable instance state
+      # @return [Hash] normalized status data
+      def status(_state)
+        container_status(::Docker::Container.get(runner_container_name, {}, docker_connection))
+      rescue ::Docker::Error::NotFoundError
+        { live: false, state: "not created", source: "driver" }
+      # Every other failure -- an unreachable daemon most of all -- is an
+      # unknown rather than an exception. Kitchen would catch it either way,
+      # but it would then report the exception class instead of the daemon
+      # url that could not be reached.
+      rescue ::StandardError => e
+        {
+          live: nil,
+          state: "unknown",
+          source: "driver",
+          message: "could not ask the docker daemon at #{config[:docker_host_url]}: #{e.message}",
+        }
+      end
+
       private
 
+      # Translate a container's `State` into kitchen's status shape.
+      #
+      # @param container [::Docker::Container] the runner container
+      # @return [Hash] normalized status data
+      def container_status(container)
+        state = container.info["State"] || {}
+        running = state["Running"] == true
+
+        status = {
+          # Docker's own vocabulary -- created, running, paused, exited,
+          # restarting, dead -- says more than a boolean, and `kitchen list`
+          # prints it verbatim.
+          live: running,
+          state: state["Status"] || (running ? "running" : "stopped"),
+          source: "driver",
+          resource_id: container.info["Id"],
+        }
+
+        error = state["Error"].to_s
+        status[:message] = error unless error.empty?
+        status
+      end
+
       # Attach DNS settings to a network endpoint configuration, in place.
       #
       # @param endpoint_config [Hash] the EndpointsConfig entry to extend
@@ -240,17 +306,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 +989,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 +1037,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 +1084,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.24.0".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"
@@ -579,8 +629,39 @@ module Kitchen
 
       # 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.
+      # This replaces Kitchen::Verifier::Base#call outright, so it has to be
+      # read against the upstream version it stands in for. It diverges in
+      # three places, and each divergence is deliberate:
+      #
+      # 1. *The upload is gated on the data container.* Files are only shipped
+      #    when the driver built one, which it does exactly when the daemon
+      #    cannot read the host filesystem. Otherwise the sandboxes are
+      #    bind-mounted and are already in place. `init_command` is gated with
+      #    it because for Busser it clears the verifier root, which in
+      #    bind-mount mode is the host sandbox that was just populated.
+      #
+      # 2. *`cleanup_sandbox` is not called*, and must not be. Upstream can
+      #    `rmtree` its sandbox because a stock one is a throwaway
+      #    `Dir.mktmpdir`. Dokken's is a stable per-instance directory that
+      #    the driver bind-mounts into a long-lived container, and a bind
+      #    mount is bound to an inode rather than to a path: removing the
+      #    directory severs it permanently, and the `mkdir_p` in the next
+      #    `create_sandbox` does not restore it. Verified against Docker --
+      #    after an rmtree and a recreate, the host has the file and the
+      #    container cannot see it, until the container itself is replaced.
+      #    Kitchen::Provisioner::Dokken#cleanup_dokken_sandbox is the shape
+      #    that is safe here: empty the directory, keep the inode.
+      #
+      # 3. *`config[:downloads]` is not honoured.* Upstream downloads files
+      #    off the instance after the run command. That cannot work here yet
+      #    for a second reason as well: Transport::Dokken::Connection does not
+      #    implement `download`, so the base class would raise. Wiring both up
+      #    is worth doing, and is the one divergence here that is a gap rather
+      #    than a decision.
+      #
+      # spec/kitchen/verifier_override_contract_spec.rb pins the upstream
+      # facts this reasoning rests on, so that a test-kitchen release which
+      # invalidates any of them fails loudly rather than silently.
       #
       # @param state [Hash] mutable instance state
       # @return [void]

data/lib/kitchen/provisioner/dokken.rb

@@ -18,6 +18,7 @@
 require "kitchen"
 require "kitchen/provisioner/chef_infra"
 require_relative "../helpers"
+require_relative "../driver/dokken_version"
 
 include Dokken::Helpers
 
@@ -35,7 +36,10 @@ module Kitchen
     class Dokken < Kitchen::Provisioner::ChefInfra
       kitchen_provisioner_api_version 2
 
-      plugin_version Kitchen::VERSION
+      # kitchen-dokken's own version. Kitchen::VERSION is test-kitchen's,
+      # so `kitchen diagnose` reported the framework version as the
+      # plugin version for every dokken plugin.
+      plugin_version Kitchen::Driver::DOKKEN_VERSION
 
       default_config :root_path, "/opt/kitchen"
       default_config :chef_binary do |provisioner|
@@ -166,6 +170,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

data/lib/kitchen/transport/dokken.rb

@@ -22,6 +22,7 @@ require "digest/sha1" unless defined?(Digest::SHA1)
 require "open3" unless defined?(Open3)
 require "shellwords" unless defined?(Shellwords)
 require_relative "../helpers"
+require_relative "../driver/dokken_version"
 
 include Dokken::Helpers
 
@@ -45,7 +46,10 @@ module Kitchen
     class Dokken < Kitchen::Transport::Base
       kitchen_transport_api_version 2
 
-      plugin_version Kitchen::VERSION
+      # kitchen-dokken's own version. Kitchen::VERSION is test-kitchen's,
+      # so `kitchen diagnose` reported the framework version as the
+      # plugin version for every dokken plugin.
+      plugin_version Kitchen::Driver::DOKKEN_VERSION
 
       default_config :docker_info do |transport|
         docker_info(transport[:docker_host_url])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-dokken
 version: !ruby/object:Gem::Version
-  version: 2.23.7
+  version: 2.24.0
 platform: ruby
 authors:
 - Sean OMeara
@@ -50,7 +50,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
@@ -60,7 +60,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'