test-kitchen 3.9.1 → 4.1.0

data/lib/kitchen/driver/base.rb

@@ -16,6 +16,7 @@ require_relative "../lazy_hash"
 require_relative "../logging"
 require_relative "../plugin_base"
 require_relative "../shell_out"
+require "time" unless defined?(Time)
 
 module Kitchen
   module Driver
@@ -63,6 +64,24 @@ module Kitchen
         false
       end
 
+      # Reports whether the backing instance is known to be live.
+      #
+      # Drivers that can ask their provider should override this method.
+      # Existing drivers remain compatible by inheriting an unknown status.
+      #
+      # @param state [Hash] mutable instance and driver state
+      # @return [Hash] normalized status data
+      def status(state) # rubocop:disable Lint/UnusedMethodArgument
+        {
+          live: nil,
+          state: "unknown",
+          source: "driver",
+          resource_id: nil,
+          message: "#{self.class} does not support status checks",
+          checked_at: Time.now.utc.iso8601,
+        }
+      end
+
       # Sets the API version for this driver. If the driver does not set this
       # value, then `nil` will be used and reported.
       #

data/lib/kitchen/driver/dummy.rb

@@ -11,6 +11,7 @@
 # limitations under the License.
 
 require_relative "../../kitchen"
+require "time" unless defined?(Time)
 
 module Kitchen
   module Driver
@@ -51,6 +52,32 @@ module Kitchen
         state.delete(:my_id)
       end
 
+      # Reports whether the dummy instance has a generated resource id.
+      #
+      # @param state [Hash] mutable instance and driver state
+      # @return [Hash] normalized status data
+      def status(state)
+        if state[:my_id]
+          {
+            live: true,
+            state: "running",
+            source: "driver",
+            resource_id: state[:my_id],
+            message: "Dummy instance exists",
+            checked_at: Time.now.utc.iso8601,
+          }
+        else
+          {
+            live: false,
+            state: "not_created",
+            source: "driver",
+            resource_id: nil,
+            message: "Dummy instance has no resource id",
+            checked_at: Time.now.utc.iso8601,
+          }
+        end
+      end
+
       private
 
       # Report what action is taking place, sleeping if so configured, and

data/lib/kitchen/driver/proxy.rb

@@ -11,7 +11,7 @@
 # limitations under the License.
 #
 
-require_relative "ssh_base"
+require_relative "base"
 require_relative "../version"
 
 module Kitchen
@@ -23,7 +23,7 @@ module Kitchen
     # the driver was created.
     #
     # @author Seth Chisamore <schisamo@opscode.com>
-    class Proxy < Kitchen::Driver::SSHBase
+    class Proxy < Kitchen::Driver::Base
       plugin_version Kitchen::VERSION
 
       required_config :host
@@ -33,8 +33,11 @@ module Kitchen
 
       # (see Base#create)
       def create(state)
-        # TODO: Once this isn't using SSHBase, it should call `super` to support pre_create_command.
+        super
         state[:hostname] = config[:host]
+        state[:port] = config[:port] if config[:port]
+        state[:username] = config[:username] if config[:username]
+        state[:password] = config[:password] if config[:password]
         reset_instance(state)
       end
 
@@ -48,15 +51,17 @@ module Kitchen
 
       private
 
-      # Resets the non-Kitchen managed instance using by issuing a command
-      # over SSH.
+      # Resets the non-Kitchen managed instance by issuing a command
+      # over the transport.
       #
       # @param state [Hash] the state hash
       # @api private
       def reset_instance(state)
         if (cmd = config[:reset_command])
           info("Resetting instance state with command: #{cmd}")
-          ssh(build_ssh_args(state), cmd)
+          instance.transport.connection(state) do |conn|
+            conn.execute(cmd)
+          end
         end
       end
     end

data/lib/kitchen/errors.rb

@@ -206,6 +206,7 @@ module Kitchen
         Kitchen.logger.debug(line)
       else
         Kitchen.logger.logdev && Kitchen.logger.logdev.public_send(level, line)
+        Kitchen.logger.structured_logdev && Kitchen.logger.structured_logdev.public_send(level, line)
       end
     end
   end

data/lib/kitchen/generator/init.rb

@@ -39,7 +39,7 @@ module Kitchen
       class_option :provisioner,
         type: :string,
         aliases: "-P",
-        default: "chef_infra",
+        default: "shell",
         desc: <<-D.gsub(/^\s+/, "").tr("\n", " ")
           The default Kitchen Provisioner to use
         D

data/lib/kitchen/instance.rb

@@ -17,6 +17,8 @@
 
 require "benchmark" unless defined?(Benchmark)
 require "fileutils" unless defined?(FileUtils)
+require "securerandom" unless defined?(SecureRandom)
+require "time" unless defined?(Time)
 
 module Kitchen
   # An instance of a suite running on a platform. A created instance may be a
@@ -210,11 +212,7 @@ module Kitchen
         raise UserError, "Instance #{to_str} has not yet been created"
       end
 
-      lc = if legacy_ssh_base_driver?
-             legacy_ssh_base_login(state)
-           else
-             transport.connection(state).login_command
-           end
+      lc = transport.connection(state).login_command
 
       debug(%{Login command: #{lc.command} #{lc.arguments.join(" ")} } \
         "(Options: #{lc.options})")
@@ -291,6 +289,46 @@ module Kitchen
       state_file.read[:last_error]
     end
 
+    # Returns the current instance session identifier, if one has been
+    # established.
+    #
+    # @return [String,nil] the current instance session id
+    def current_session_id
+      state_file.read[:instance_session_id]
+    end
+
+    # Returns the path to the text log file for this instance.
+    #
+    # @return [String,nil] the instance text log path
+    def log_path
+      logger.logdev_path
+    end
+
+    # Returns the path to the structured log file for this instance.
+    #
+    # @return [String,nil] the instance structured log path
+    def structured_log_path
+      logger.structured_logdev_path
+    end
+
+    # Returns the path to the state file for this instance.
+    #
+    # @return [String] the instance state file path
+    def state_path
+      state_file.path
+    end
+
+    # Returns normalized liveness status for this instance.
+    #
+    # @param probe [Boolean] whether to probe the transport as well
+    # @return [Hash] normalized status data
+    def status(probe: false)
+      state = state_file.read
+      result = driver_status(state)
+      result[:transport_probe] = transport_probe(state) if probe
+      result
+    end
+
     # Clean up any per-instance resources before exiting.
     #
     # @return [void]
@@ -410,17 +448,14 @@ module Kitchen
     # @return [self] this instance, used to chain actions
     # @api private
     def converge_action
-      banner "Converging #{to_str}..."
       elapsed = action(:converge) do |state|
-        if legacy_ssh_base_driver?
-          provisioner.check_license
-          legacy_ssh_base_converge(state)
-        else
-          provisioner.check_license
-          provisioner.call(state)
-        end
+        banner "Converging #{to_str}..."
+        provisioner.check_license
+        provisioner.call(state)
+      end
+      with_current_action_metadata(:converge) do
+        info("Finished converging #{to_str} #{Util.duration(elapsed.real)}.")
       end
-      info("Finished converging #{to_str} #{Util.duration(elapsed.real)}.")
       self
     end
 
@@ -430,47 +465,28 @@ module Kitchen
     # @return [self] this instance, used to chain actions
     # @api private
     def setup_action
-      banner "Setting up #{to_str}..."
       elapsed = action(:setup) do |state|
-        legacy_ssh_base_setup(state) if legacy_ssh_base_driver?
+        banner "Setting up #{to_str}..."
+      end
+      with_current_action_metadata(:setup) do
+        info("Finished setting up #{to_str} #{Util.duration(elapsed.real)}.")
       end
-      info("Finished setting up #{to_str} #{Util.duration(elapsed.real)}.")
       self
     end
 
-    # returns true, if the verifier is busser
-    def verifier_busser?(verifier)
-      !defined?(Kitchen::Verifier::Busser).nil? && verifier.is_a?(Kitchen::Verifier::Busser)
-    end
-
-    # returns true, if the verifier is dummy
-    def verifier_dummy?(verifier)
-      !defined?(Kitchen::Verifier::Dummy).nil? && verifier.is_a?(Kitchen::Verifier::Dummy)
-    end
-
-    def use_legacy_ssh_verifier?(verifier)
-      verifier_busser?(verifier) || verifier_dummy?(verifier)
-    end
-
     # Perform the verify action.
     #
     # @see Driver::Base#verify
     # @return [self] this instance, used to chain actions
     # @api private
     def verify_action
-      banner "Verifying #{to_str}..."
       elapsed = action(:verify) do |state|
-        # use special handling for legacy driver
-        if legacy_ssh_base_driver? && use_legacy_ssh_verifier?(verifier)
-          legacy_ssh_base_verify(state)
-        elsif legacy_ssh_base_driver?
-          # read ssh options from legacy driver
-          verifier.call(driver.legacy_state(state))
-        else
-          verifier.call(state)
-        end
+        banner "Verifying #{to_str}..."
+        verifier.call(state)
+      end
+      with_current_action_metadata(:verify) do
+        info("Finished verifying #{to_str} #{Util.duration(elapsed.real)}.")
       end
-      info("Finished verifying #{to_str} #{Util.duration(elapsed.real)}.")
       self
     end
 
@@ -488,14 +504,18 @@ module Kitchen
     # @param verb [Symbol] the action to be performed
     # @param output_verb [String] a verb representing the action, suitable for
     #   use in output logging
-    # @yield perform optional work just after action has complted
+    # @yield perform optional work just after action has completed
     # @return [self] this instance, used to chain actions
     # @api private
     def perform_action(verb, output_verb)
-      banner "#{output_verb} #{to_str}..."
-      elapsed = action(verb) { |state| driver.public_send(verb, state) }
-      info("Finished #{output_verb.downcase} #{to_str}" \
-        " #{Util.duration(elapsed.real)}.")
+      elapsed = action(verb) do |state|
+        banner "#{output_verb} #{to_str}..."
+        driver.public_send(verb, state)
+      end
+      with_current_action_metadata(verb) do
+        info("Finished #{output_verb.downcase} #{to_str}" \
+          " #{Util.duration(elapsed.real)}.")
+      end
       yield if block_given?
       self
     end
@@ -520,64 +540,7 @@ module Kitchen
     #   occurred, etc.
     # @api private
     def action(what, &block)
-      state = state_file.read
-      elapsed = Benchmark.measure do
-        synchronize_or_call(what, state, &block)
-      end
-      state[:last_action] = what.to_s
-      state[:last_error] = nil
-      elapsed
-    rescue ActionFailed => e
-      log_failure(what, e)
-      state[:last_error] = e.class.name
-      raise(InstanceFailure, failure_message(what) +
-        "  Please see .kitchen/logs/#{name}.log for more details",
-        e.backtrace)
-    rescue Exception => e # rubocop:disable Lint/RescueException
-      log_failure(what, e)
-      state[:last_error] = e.class.name
-      raise ActionFailed,
-        "Failed to complete ##{what} action: [#{e.message}]", e.backtrace
-    ensure
-      state_file.write(state)
-    end
-
-    # Runs a given action block through a common driver mutex if required or
-    # runs it directly otherwise. If a driver class' `.serial_actions` array
-    # includes the desired action, then the action must be run with a muxtex
-    # lock. Otherwise, it is assumed that the action can happen concurrently,
-    # or fully in parallel.
-    #
-    # @param what [Symbol] the action to be performed
-    # @param state [Hash] a mutable state hash for this instance
-    # @param block [Proc] a block to be called
-    # @api private
-    def synchronize_or_call(what, state)
-      plugin_class = plugin_class_for_action(what)
-      if Array(plugin_class.serial_actions).include?(what)
-        debug("#{to_str} is synchronizing on #{plugin_class}##{what}")
-        self.class.mutexes[plugin_class].synchronize do
-          debug("#{to_str} is messaging #{plugin_class}##{what}")
-          yield(state)
-        end
-      else
-        yield(state)
-      end
-    end
-
-    # Maps the given action to the plugin class associated with the action
-    #
-    # @param what[Symbol] action
-    # @return [Class] Kitchen::Plugin::Base
-    # @api private
-    def plugin_class_for_action(what)
-      {
-        create: driver,
-        setup: transport,
-        converge: provisioner,
-        verify: verifier,
-        destroy: driver,
-      }[what].class
+      action_runner.call(what, &block)
     end
 
     # Writes a high level message for logging and/or output.
@@ -589,97 +552,200 @@ module Kitchen
     # @api private
     def banner(*args)
       Kitchen.logger.logdev && Kitchen.logger.logdev.banner(*args)
+      if Kitchen.logger.structured_logdev
+        Kitchen.logger.with_metadata(logger.metadata) do
+          Kitchen.logger.structured_logdev.banner(*args)
+        end
+      end
       super
     end
 
-    # Logs a failure (message and backtrace) to the instance's file logger
-    # to help with debugging and diagnosing issues without overwhelming the
-    # console output in the default case (i.e. running kitchen with :info
-    # level debugging).
-    #
-    # @param what [String] an action
-    # @param e [Exception] an exception
-    # @api private
-    def log_failure(what, e)
-      return if logger.logdev.nil?
-
-      logger.logdev.error(failure_message(what))
-      Error.formatted_trace(e).each { |line| logger.logdev.error(line) }
+    def action_runner
+      @action_runner ||= ActionRunner.new(self, state_file)
     end
 
-    # Returns a string explaining what action failed, at a high level. Used
-    # for displaying to end user.
-    #
-    # @param what [String] an action
-    # @return [String] a failure message
-    # @api private
-    def failure_message(what)
-      "#{what.capitalize} failed on instance #{to_str}."
+    def with_current_action_metadata(what)
+      state = state_file.read
+      logger.with_metadata(
+        action: what.to_s,
+        action_id: state[:last_action_id],
+        instance_session_id: state[:instance_session_id],
+        kitchen_run_id: state[:last_kitchen_run_id] || Kitchen.run_id
+      ) do
+        yield
+      end
     end
 
-    # Invokes `Driver#converge` on a legacy Driver, which inherits from
-    # `Kitchen::Driver::SSHBase`.
-    #
-    # @param state [Hash] mutable instance state
-    # @deprecated When legacy Driver::SSHBase support is removed, the
-    #   `#converge` method will no longer be called on the Driver.
-    # @api private
-    def legacy_ssh_base_converge(state)
-      warn("Running legacy converge for '#{driver.name}' Driver")
-      # TODO: Document upgrade path and provide link
-      # warn("Driver authors: please read http://example.com for more details.")
-      driver.converge(state)
+    def driver_status(state)
+      if driver.method(:status).arity == 0
+        return unknown_driver_status(
+          "Driver status method does not accept Kitchen state"
+        )
+      end
+
+      normalize_driver_status(driver.status(state))
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      unknown_driver_status(e.message, e.class.name)
     end
 
-    # @return [TrueClass,FalseClass] whether or not the Driver inherits from
-    #   `Kitchen::Driver::SSHBase`
-    # @deprecated When legacy Driver::SSHBase support is removed, the
-    #   `#converge` method will no longer be called on the Driver.
-    # @api private
-    def legacy_ssh_base_driver?
-      driver.class < Kitchen::Driver::SSHBase
+    def normalize_driver_status(status)
+      status = Util.symbolized_hash(status || {})
+      {
+        live: status[:live],
+        state: status[:state] || "unknown",
+        source: status[:source] || "driver",
+        resource_id: status[:resource_id],
+        message: status[:message],
+        checked_at: status[:checked_at] || Time.now.utc.iso8601,
+      }.compact
     end
 
-    # Invokes `Driver#login_command` on a legacy Driver, which inherits from
-    # `Kitchen::Driver::SSHBase`.
-    #
-    # @param state [Hash] mutable instance state
-    # @deprecated When legacy Driver::SSHBase support is removed, the
-    #   `#login_command` method will no longer be called on the Driver.
-    # @api private
-    def legacy_ssh_base_login(state)
-      warn("Running legacy login for '#{driver.name}' Driver")
-      # TODO: Document upgrade path and provide link
-      # warn("Driver authors: please read http://example.com for more details.")
-      driver.login_command(state)
+    def unknown_driver_status(message, error = nil)
+      {
+        live: nil,
+        state: "unknown",
+        source: "driver",
+        error:,
+        message:,
+        checked_at: Time.now.utc.iso8601,
+      }.compact
     end
 
-    # Invokes `Driver#setup` on a legacy Driver, which inherits from
-    # `Kitchen::Driver::SSHBase`.
-    #
-    # @param state [Hash] mutable instance state
-    # @deprecated When legacy Driver::SSHBase support is removed, the
-    #   `#setup` method will no longer be called on the Driver.
-    # @api private
-    def legacy_ssh_base_setup(state)
-      warn("Running legacy setup for '#{driver.name}' Driver")
-      # TODO: Document upgrade path and provide link
-      # warn("Driver authors: please read http://example.com for more details.")
-      driver.setup(state)
+    def transport_probe(state)
+      return not_created_transport_probe if state[:last_action].nil?
+
+      transport.connection(state, &:wait_until_ready)
+      {
+        reachable: true,
+        state: "reachable",
+        source: "transport",
+        message: "Transport connection succeeded",
+        checked_at: Time.now.utc.iso8601,
+      }
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      {
+        reachable: false,
+        state: "unreachable",
+        source: "transport",
+        error: e.class.name,
+        message: e.message,
+        checked_at: Time.now.utc.iso8601,
+      }
+    ensure
+      transport.cleanup! if transport
     end
 
-    # Invokes `Driver#verify` on a legacy Driver, which inherits from
-    # `Kitchen::Driver::SSHBase`.
-    #
-    # @param state [Hash] mutable instance state
-    # @deprecated When legacy Driver::SSHBase support is removed, the
-    #   `#verify` method will no longer be called on the Driver.
-    # @api private
-    def legacy_ssh_base_verify(state)
-      warn("Running legacy verify for '#{driver.name}' Driver")
-      # TODO: Document upgrade path and provide link
-      # warn("Driver authors: please read http://example.com for more details.")
-      driver.verify(state)
+    def not_created_transport_probe
+      {
+        reachable: false,
+        state: "not_created",
+        source: "transport",
+        message: "Instance has not yet been created",
+        checked_at: Time.now.utc.iso8601,
+      }
+    end
+
+    # Coordinates one instance action, including state persistence, plugin
+    # serialization, and failure wrapping.
+    class ActionRunner
+      def initialize(instance, state_file)
+        @instance = instance
+        @state_file = state_file
+      end
+
+      def call(what, &block)
+        state = nil
+        begin
+          state = state_file.read
+        rescue ::StandardError => e
+          log_failure(what, e)
+          raise ActionFailed,
+            "Failed to complete ##{what} action: [#{e.message}]", e.backtrace
+        end
+
+        action_id = new_id
+        session_id = state[:instance_session_id] || new_id
+        instance.logger.with_metadata(
+          action: what.to_s,
+          action_id:,
+          instance_session_id: session_id,
+          kitchen_run_id: Kitchen.run_id
+        ) do
+          elapsed = Benchmark.measure do
+            synchronize_or_call(what, state, &block)
+          end
+          record_attempt(state, what, action_id, session_id)
+          state[:last_action] = what.to_s
+          state[:last_error] = nil
+          elapsed
+        rescue ActionFailed => e
+          log_failure(what, e)
+          record_attempt(state, what, action_id, session_id)
+          state[:last_error] = e.class.name
+          raise(InstanceFailure, failure_message(what) +
+            "  Please see .kitchen/logs/#{instance.name}.log for more details",
+            e.backtrace)
+        rescue ::StandardError => e
+          log_failure(what, e)
+          record_attempt(state, what, action_id, session_id)
+          state[:last_error] = e.class.name
+          raise ActionFailed,
+            "Failed to complete ##{what} action: [#{e.message}]", e.backtrace
+        ensure
+          state_file.write(state)
+        end
+      end
+
+      private
+
+      attr_reader :instance, :state_file
+
+      def synchronize_or_call(what, state)
+        plugin_class = plugin_class_for_action(what)
+        if Array(plugin_class.serial_actions).include?(what)
+          instance.debug("#{instance.to_str} is synchronizing on #{plugin_class}##{what}")
+          instance.class.mutexes[plugin_class].synchronize do
+            instance.debug("#{instance.to_str} is messaging #{plugin_class}##{what}")
+            yield(state)
+          end
+        else
+          yield(state)
+        end
+      end
+
+      def plugin_class_for_action(what)
+        {
+          create: instance.driver,
+          setup: instance.transport,
+          converge: instance.provisioner,
+          verify: instance.verifier,
+          destroy: instance.driver,
+        }[what].class
+      end
+
+      def log_failure(what, e)
+        return if instance.logger.logdev.nil? && instance.logger.structured_logdev.nil?
+
+        [instance.logger.logdev, instance.logger.structured_logdev].compact.each do |logdev|
+          logdev.error(failure_message(what))
+          Error.formatted_trace(e).each { |line| logdev.error(line) }
+        end
+      end
+
+      def failure_message(what)
+        "#{what.capitalize} failed on instance #{instance.to_str}."
+      end
+
+      def record_attempt(state, what, action_id, session_id)
+        state[:instance_session_id] = session_id
+        state[:last_attempted_action] = what.to_s
+        state[:last_action_id] = action_id
+        state[:last_kitchen_run_id] = Kitchen.run_id
+      end
+
+      def new_id
+        SecureRandom.uuid
+      end
     end
 
     # The simplest finite state machine pseudo-implementation needed to manage
@@ -689,7 +755,7 @@ module Kitchen
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class FSM
       # Returns an Array of all transitions to bring an Instance from its last
-      # reported transistioned state into the desired transitioned state.
+      # reported transitioned state into the desired transitioned state.
       #
       # @param last [String,Symbol,nil] the last known transitioned state of
       #   the Instance, defaulting to `nil` (for unknown or no history)

data/lib/kitchen/lazy_hash.rb

@@ -18,7 +18,7 @@
 require "delegate"
 
 module Kitchen
-  # A modifed Hash object that may contain callables as a value which must be
+  # A modified Hash object that may contain callables as a value which must be
   # executed in the context of another object. This allows for delayed
   # evaluation of a hash value while still looking and largely feeling like a
   # normal Ruby Hash.