Class: Kitchen::Instance

Inherits:

Object

Object
Kitchen::Instance

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:

Fletcher Nichol [email protected]

Defined Under Namespace

Classes: FSM

Class Attribute Summary collapse

.mutexes ⇒ Hash private
A hash of mutxes, arranged by Driver class names.

Instance Attribute Summary collapse

#busser ⇒ Busser readonly
Busser object for instance to manage the busser installation on this instance.
#driver ⇒ Driver::Base readonly
Driver object which will manage this instance's lifecycle actions.
#logger ⇒ Logger readonly
The logger for this instance.
#name ⇒ String readonly
Name of this instance.
#platform ⇒ Platform readonly
The target platform configuration.
#provisioner ⇒ Provisioner::Base readonly
Provisioner object which will the setup and invocation instructions for configuration management and other automation tools.
#suite ⇒ Suite readonly
The test suite configuration.

Class Method Summary collapse

.name_for(suite, platform) ⇒ String
Generates a name for an instance given a suite and platform.

Instance Method Summary collapse

#converge ⇒ self
Converges this running instance.
#create ⇒ self
Creates this instance.
#destroy ⇒ self
Destroys this instance.
#diagnose ⇒ Hash
Returns a Hash of configuration and other useful diagnostic information.
#initialize(options = {}) ⇒ Instance constructor
Creates a new instance, given a suite and a platform.
#last_action ⇒ String
Returns the last successfully completed action state of the instance.
#login ⇒ Object
Logs in to this instance by invoking a system command, provided by the instance's driver.
#remote_exec(command) ⇒ Object
Executes an arbitrary command on this instance.
#setup ⇒ self
Sets up this converged instance for suite tests.
#test(destroy_mode = :passing) ⇒ self
Tests this instance by creating, converging and verifying.
#to_str ⇒ String
Returns a displayable representation of the instance.
#verify ⇒ self
Verifies this set up instance by executing suite tests.

Methods included from Logging

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

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

# File 'lib/kitchen/instance.rb', line 88

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 ⇒ `Hash`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of mutxes, arranged by Driver class names.

Returns:

(Hash) —
a hash of mutxes, arranged by Driver class names



37
38
39

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

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



69
70
71

# File 'lib/kitchen/instance.rb', line 69

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



60
61
62

# File 'lib/kitchen/instance.rb', line 60

def driver
  @driver
end

#logger ⇒ `Logger` (readonly)

Returns the logger for this instance.

Returns:

(Logger) —
the logger for this instance



72
73
74

# File 'lib/kitchen/instance.rb', line 72

def logger
  @logger
end

#name ⇒ `String` (readonly)

Returns name of this instance.

Returns:

(String) —
name of this instance



56
57
58

# File 'lib/kitchen/instance.rb', line 56

def name
  @name
end

#platform ⇒ `Platform` (readonly)

Returns the target platform configuration.

Returns:

(Platform) —
the target platform configuration



53
54
55

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

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



65
66
67

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

def provisioner
  @provisioner
end

#suite ⇒ `Suite` (readonly)

Returns the test suite configuration.

Returns:

(Suite) —
the test suite configuration



50
51
52

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

def suite
  @suite
end

Class Method Details

.name_for(suite, platform) ⇒ `String`

Generates a name for an instance given a suite and platform.

Parameters:

suite (Suite, #name) —
a Suite
platform (Platform, #name) —
a Platform

Returns:

(String) —
a normalized, consistent name for an instance



44
45
46

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

def name_for(suite, platform)
  "#{suite.name}-#{platform.name}".gsub(%r{[_,/]}, "-").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:

Driver::Base#converge



129
130
131

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

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:

Driver::Base#create



118
119
120

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

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:

Driver::Base#destroy



162
163
164

# File 'lib/kitchen/instance.rb', line 162

def destroy
  transition_to(:destroy)
end

#diagnose ⇒ `Hash`

Returns a Hash of configuration and other useful diagnostic information.

Returns:

(Hash) —
a diagnostic hash

# File 'lib/kitchen/instance.rb', line 222

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 ⇒ `String`

Returns the last successfully completed action state of the instance.

Returns:

(String) —
a named action which was last successfully completed



234
235
236

# File 'lib/kitchen/instance.rb', line 234

def last_action
  state_file.read[:last_action]
end

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:

Driver::LoginCommand
Driver::Base#login_command

# File 'lib/kitchen/instance.rb', line 198

def login
  state = state_file.read
  if state[:last_action].nil?
    raise UserError, "Instance #{to_str} has not yet been created"
  end

  login_command = driver.login_command(state)
  cmd, *args = login_command.cmd_array
  options = login_command.options

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

#remote_exec(command) ⇒ `Object`

Executes an arbitrary command on this instance.

Parameters:

command (String) —
a command string to execute



215
216
217

# File 'lib/kitchen/instance.rb', line 215

def remote_exec(command)
  driver.remote_command(state_file.read, command)
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:

Driver::Base#setup



140
141
142

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

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

# File 'lib/kitchen/instance.rb', line 176

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 ⇒ `String`

Returns a displayable representation of the instance.

Returns:

(String) —
an instance display string



107
108
109

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

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:

Driver::Base#verify



151
152
153

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

def verify
  transition_to(:verify)
end

Class: Kitchen::Instance

Overview

Defined Under Namespace

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Logging

Constructor Details

#initialize(options = {}) ⇒ Instance

Class Attribute Details

.mutexes ⇒ Hash

Instance Attribute Details

#busser ⇒ Busser (readonly)

#driver ⇒ Driver::Base (readonly)

#logger ⇒ Logger (readonly)

#name ⇒ String (readonly)

#platform ⇒ Platform (readonly)

#provisioner ⇒ Provisioner::Base (readonly)

#suite ⇒ Suite (readonly)

Class Method Details

.name_for(suite, platform) ⇒ String

Instance Method Details

#converge ⇒ self

#create ⇒ self

#destroy ⇒ self

#diagnose ⇒ Hash

#last_action ⇒ String

#login ⇒ Object

#remote_exec(command) ⇒ Object

#setup ⇒ self

#test(destroy_mode = :passing) ⇒ self

#to_str ⇒ String

#verify ⇒ self

#initialize(options = {}) ⇒ `Instance`

.mutexes ⇒ `Hash`

#busser ⇒ `Busser` (readonly)

#driver ⇒ `Driver::Base` (readonly)

#logger ⇒ `Logger` (readonly)

#name ⇒ `String` (readonly)

#platform ⇒ `Platform` (readonly)

#provisioner ⇒ `Provisioner::Base` (readonly)

#suite ⇒ `Suite` (readonly)

.name_for(suite, platform) ⇒ `String`

#converge ⇒ `self`

#create ⇒ `self`

#destroy ⇒ `self`

#diagnose ⇒ `Hash`

#last_action ⇒ `String`

#login ⇒ `Object`

#remote_exec(command) ⇒ `Object`

#setup ⇒ `self`

#test(destroy_mode = :passing) ⇒ `self`

#to_str ⇒ `String`

#verify ⇒ `self`