Class: Kitchen::Verifier::Base

Inherits:
Plugin::Base
  • Object
show all
Includes:
Configurable, Logging
Defined in:
lib/kitchen/verifier/base.rb

Overview

Base class for a verifier.

Author:

Direct Known Subclasses

Busser, Dummy, Shell

Instance Attribute Summary

Attributes included from Configurable

#instance

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Logging

#banner, #debug, #error, #fatal, #info, #warn

Methods included from Configurable

#[], #bourne_shell?, #calculate_path, #config_keys, #diagnose, #diagnose_plugin, #finalize_config!, included, #name, #powershell_shell?, #remote_path_join, #unix_os?, #verify_dependencies, #windows_os?

Constructor Details

#initialize(config = {}) ⇒ Base

Creates a new Verifier object using the provided configuration data which will be merged with any default configuration.

Parameters:

  • config (Hash) (defaults to: {}) —

    provided verifier configuration



58
59
60
 
# File 'lib/kitchen/verifier/base.rb', line 58

def initialize(config = {})
  init_config(config)
end

Class Method Details

.kitchen_verifier_api_version(version) ⇒ Object

Sets the API version for this verifier. If the verifier does not set this value, then nil will be used and reported.

Sets the API version for this verifier

Examples:

setting an API version


module Kitchen
  module Verifier
    class NewVerifier < Kitchen::Verifier::Base

      kitchen_verifier_api_version 2

    end
  end
end

Parameters:

  • version (Integer, String) —

    a version number



221
222
223
 
# File 'lib/kitchen/verifier/base.rb', line 221

def self.kitchen_verifier_api_version(version)
  @api_version = version
end

Instance Method Details

#call(state) ⇒ Object

Runs the verifier on the instance.

Parameters:

  • state (Hash) —

    mutable instance state

Raises:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/kitchen/verifier/base.rb', line 66

def call(state)
  create_sandbox

  instance.transport.connection(state) do |conn|
    conn.execute(install_command)
    conn.execute(init_command)
    info("Transferring files to #{instance.to_str}")
    conn.upload(sandbox_dirs, config[:root_path])
    debug("Transfer complete")
    conn.execute(prepare_command)

    begin
      conn.execute(run_command)
    ensure
      # Retrieval is best-effort: a file we could not fetch must not
      # fail an otherwise successful verify, and must never replace
      # an error already in flight from the run command. A transport
      # that cannot download at all is a bug, not a missing file, so
      # it still raises when there is no verify error to protect.
      run_error = $!
      begin
        info("Downloading files from #{instance.to_str}")
        config[:downloads].to_h.each do |remotes, local|
          debug("Downloading #{Array(remotes).join(", ")} to #{local}")
          conn.download(remotes, local)
        end
        debug("Download complete")
      rescue => ex
        raise unless run_error || ex.is_a?(Kitchen::Transport::TransportFailed)

        warn("Failed to download files from #{instance.to_str}: #{ex.message}")
      end
    end
  end
rescue Kitchen::Transport::TransportFailed => ex
  raise ActionFailed, ex.message
ensure
  cleanup_sandbox
end

#cleanup_sandbox ⇒ Object

Deletes the sandbox path. Without calling this method, the sandbox path will persist after the process terminates. In other words, cleanup is explicit. This method is safe to call multiple times.



117
118
119
120
121
122
123
124
125
126
 
# File 'lib/kitchen/verifier/base.rb', line 117

def cleanup_sandbox
  # Check the ivar, not #sandbox_path, which raises rather than
  # returning nil when the sandbox was never created. This runs from
  # an ensure block, so raising here would mask the error that kept
  # #create_sandbox from finishing.
  return if @sandbox_path.nil?

  debug("Cleaning up local sandbox in #{sandbox_path}")
  FileUtils.rmtree(sandbox_path)
end

#create_sandbox ⇒ Object

Creates a temporary directory on the local workstation into which verifier related files and directories can be copied or created. The contents of this directory will be copied over to the instance before invoking the verifier's run command. After this method completes, it is expected that the contents of the sandbox is complete and ready for copy to the remote instance.

Note: any subclasses would be well advised to call super first when overriding this method, for example:

Examples:

overriding #create_sandbox


class MyVerifier < Kitchen::Verifier::Base
  def create_sandbox
    super
    # any further file copies, preparations, etc.
  end
end


146
147
148
149
150
151
 
# File 'lib/kitchen/verifier/base.rb', line 146

def create_sandbox
  @sandbox_path = Dir.mktmpdir("#{instance.name}-sandbox-")
  File.chmod(0755, sandbox_path)
  info("Preparing files for transfer")
  debug("Creating local sandbox in #{sandbox_path}")
end

#doctor(state) ⇒ Boolean

Check system and configuration for common errors.

Parameters:

  • state (Hash) —

    mutable instance state

Returns:

  • (Boolean) —

    Return true if a problem is found.



110
111
112
 
# File 'lib/kitchen/verifier/base.rb', line 110

def doctor(state)
  false
end

#init_command ⇒ String

Generates a command string which will perform any data initialization or configuration required after the verifier software is installed but before the sandbox has been transferred to the instance. If no work is required, then nil will be returned.

Returns:

  • (String) —

    a command string



166
 
# File 'lib/kitchen/verifier/base.rb', line 166

def init_command; end

#install_command ⇒ String

Generates a command string which will install and configure the verifier software on an instance. If no work is required, then nil will be returned.

Returns:

  • (String) —

    a command string



158
 
# File 'lib/kitchen/verifier/base.rb', line 158

def install_command; end

#prepare_command ⇒ String

Generates a command string which will perform any commands or configuration required just before the main verifier run command but after the sandbox has been transferred to the instance. If no work is required, then nil will be returned.

Returns:

  • (String) —

    a command string



174
 
# File 'lib/kitchen/verifier/base.rb', line 174

def prepare_command; end

#run_command ⇒ String

Generates a command string which will invoke the main verifier command on the prepared instance. If no work is required, then nil will be returned.

Returns:

  • (String) —

    a command string



181
 
# File 'lib/kitchen/verifier/base.rb', line 181

def run_command; end

#sandbox_dirs ⇒ String

Returns the list of items in the sandbox directory

Returns:

  • (String) —

    the absolute path of sandbox directory files



198
199
200
 
# File 'lib/kitchen/verifier/base.rb', line 198

def sandbox_dirs
  Util.list_directory(sandbox_path)
end

#sandbox_path ⇒ String

Returns the absolute path to the sandbox directory or raises an exception if #create_sandbox has not yet been called.

Returns:

  • (String) —

    the absolute path to the sandbox directory

Raises:

  • (ClientError) —

    if the sandbox directory has not yet been created by calling #create_sandbox



189
190
191
192
193
 
# File 'lib/kitchen/verifier/base.rb', line 189

def sandbox_path
  @sandbox_path ||= raise ClientError, "Sandbox directory has not yet " \
     "been created. Please run #{self.class}#create_sandbox before " \
     "trying to access the path."
end