Class: Kitchen::Instance

Inherits:
Object
  • Object
show all
Includes:
Logging
Defined in:
lib/kitchen/instance.rb

Overview

An instance of a suite running on a platform. A created instance may be a local virtual machine, cloud instance, container, or even a bare metal server, which is determined by the platform's driver.

Author:

Defined Under Namespace

Classes: FSM

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Instance

Creates a new instance, given a suite and a platform.

Parameters:

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

    configuration for a new suite

Options Hash (options):

  • :suite (Suite) —

    the suite (**Required)

  • :platform (Platform) —

    the platform (**Required)

  • :driver (Driver::Base) —

    the driver (**Required)

  • :provisioner (Provisioner::Base) —

    the provisioner (**Required)

  • :busser (Busser) —

    the busser logger (Required)

  • :logger (Logger) —

    the instance logger (default: Kitchen.logger)

  • :state_file (StateFile) —

    the state file object to use when tracking instance state (Required)

Raises:

  • (ClientError) —

    if one or more required options are omitted



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/kitchen/instance.rb', line 80

def initialize(options = {})
  validate_options(options)

  @suite        = options.fetch(:suite)
  @platform     = options.fetch(:platform)
  @name         = self.class.name_for(@suite, @platform)
  @driver       = options.fetch(:driver)
  @provisioner  = options.fetch(:provisioner)
  @busser       = options.fetch(:busser)
  @logger       = options.fetch(:logger) { Kitchen.logger }
  @state_file   = options.fetch(:state_file)

  setup_driver
  setup_provisioner
end

Class Attribute Details

.mutexes ⇒ Object

Returns the value of attribute mutexes.



34
35
36
 
# File 'lib/kitchen/instance.rb', line 34

def mutexes
  @mutexes
end

Instance Attribute Details

#busser ⇒ Busser (readonly)

Returns busser object for instance to manage the busser installation on this instance.

Returns:

  • (Busser) —

    busser object for instance to manage the busser installation on this instance



61
62
63
 
# File 'lib/kitchen/instance.rb', line 61

def busser
  @busser
end

#driver ⇒ Driver::Base (readonly)

Returns driver object which will manage this instance's lifecycle actions.

Returns:

  • (Driver::Base) —

    driver object which will manage this instance's lifecycle actions



52
53
54
 
# File 'lib/kitchen/instance.rb', line 52

def driver
  @driver
end

#logger ⇒ Logger (readonly)

Returns the logger for this instance.

Returns:

  • (Logger) —

    the logger for this instance



64
65
66
 
# File 'lib/kitchen/instance.rb', line 64

def logger
  @logger
end

#name ⇒ String (readonly)

Returns name of this instance.

Returns:

  • (String) —

    name of this instance



48
49
50
 
# File 'lib/kitchen/instance.rb', line 48

def name
  @name
end

#platform ⇒ Platform (readonly)

Returns the target platform configuration.

Returns:

  • (Platform) —

    the target platform configuration



45
46
47
 
# File 'lib/kitchen/instance.rb', line 45

def platform
  @platform
end

#provisioner ⇒ Provisioner::Base (readonly)

Returns provisioner object which will the setup and invocation instructions for configuration management and other automation tools.

Returns:

  • (Provisioner::Base) —

    provisioner object which will the setup and invocation instructions for configuration management and other automation tools



57
58
59
 
# File 'lib/kitchen/instance.rb', line 57

def provisioner
  @provisioner
end

#suite ⇒ Suite (readonly)

Returns the test suite configuration.

Returns:

  • (Suite) —

    the test suite configuration



42
43
44
 
# File 'lib/kitchen/instance.rb', line 42

def suite
  @suite
end

Class Method Details

.name_for(suite, platform) ⇒ Object 



36
37
38
 
# File 'lib/kitchen/instance.rb', line 36

def name_for(suite, platform)
  "#{suite.name}-#{platform.name}".gsub(/_/, '-').gsub(/\./, '')
end

Instance Method Details

#converge ⇒ self

TODO:

rescue Driver::ActionFailed and return some kind of null object to gracfully stop action chaining

Converges this running instance.

Returns:

  • (self) —

    this instance, used to chain actions

See Also:



118
119
120
 
# File 'lib/kitchen/instance.rb', line 118

def converge
  transition_to(:converge)
end

#create ⇒ self

TODO:

rescue Driver::ActionFailed and return some kind of null object to gracfully stop action chaining

Creates this instance.

Returns:

  • (self) —

    this instance, used to chain actions

See Also:



107
108
109
 
# File 'lib/kitchen/instance.rb', line 107

def create
  transition_to(:create)
end

#destroy ⇒ self

TODO:

rescue Driver::ActionFailed and return some kind of null object to gracfully stop action chaining

Destroys this instance.

Returns:

  • (self) —

    this instance, used to chain actions

See Also:



151
152
153
 
# File 'lib/kitchen/instance.rb', line 151

def destroy
  transition_to(:destroy)
end

#diagnose ⇒ Hash

Returns a Hash of configuration and other useful diagnostic information.

Returns:

  • (Hash) —

    a diagnostic hash



199
200
201
202
203
204
205
206
 
# File 'lib/kitchen/instance.rb', line 199

def diagnose
  result = Hash.new
  [:state_file, :driver, :provisioner, :busser].each do |sym|
    obj = send(sym)
    result[sym] = obj.respond_to?(:diagnose) ? obj.diagnose : :unknown
  end
  result
end

#last_action ⇒ Object 



208
209
210
 
# File 'lib/kitchen/instance.rb', line 208

def last_action
  state_file.read[:last_action]
end

#login ⇒ Object

Logs in to this instance by invoking a system command, provided by the instance's driver. This could be an SSH command, telnet, or serial console session.

Note This method calls exec and will not return.

See Also:



187
188
189
190
191
192
193
194
 
# File 'lib/kitchen/instance.rb', line 187

def 
   = driver.(state_file.read)
  command, *args = .cmd_array
  options = .options

  debug("Login command: #{command} #{args.join(' ')} (Options: #{options})")
  Kernel.exec(command, *args, options)
end

#setup ⇒ self

TODO:

rescue Driver::ActionFailed and return some kind of null object to gracfully stop action chaining

Sets up this converged instance for suite tests.

Returns:

  • (self) —

    this instance, used to chain actions

See Also:



129
130
131
 
# File 'lib/kitchen/instance.rb', line 129

def setup
  transition_to(:setup)
end

#test(destroy_mode = :passing) ⇒ self

TODO:

rescue Driver::ActionFailed and return some kind of null object to gracfully stop action chaining

Tests this instance by creating, converging and verifying. If this instance is running, it will be pre-emptively destroyed to ensure a clean slate. The instance will be left post-verify in a running state.

Parameters:

  • destroy_mode (Symbol) (defaults to: :passing) —

    strategy used to cleanup after instance has finished verifying (default: :passing)

Returns:

  • (self) —

    this instance, used to chain actions



165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/kitchen/instance.rb', line 165

def test(destroy_mode = :passing)
  elapsed = Benchmark.measure do
    banner "Cleaning up any prior instances of #{to_str}"
    destroy
    banner "Testing #{to_str}"
    verify
    destroy if destroy_mode == :passing
  end
  info "Finished testing #{to_str} #{Util.duration(elapsed.real)}."
  self
ensure
  destroy if destroy_mode == :always
end

#to_str ⇒ Object 



96
97
98
 
# File 'lib/kitchen/instance.rb', line 96

def to_str
  "<#{name}>"
end

#verify ⇒ self

TODO:

rescue Driver::ActionFailed and return some kind of null object to gracfully stop action chaining

Verifies this set up instance by executing suite tests.

Returns:

  • (self) —

    this instance, used to chain actions

See Also:



140
141
142
 
# File 'lib/kitchen/instance.rb', line 140

def verify
  transition_to(:verify)
end