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

Methods included from Logging

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

Constructor Details

#initialize(options = {}) ⇒ Instance

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

Options Hash (options):

  • :suite (Suite) —

    the suite (Required)

  • :platform (Platform) —

    the platform (Required)

  • :driver (Driver::Base) —

    the driver (Required)

  • :provisioner (Provisioner::Base) —

    the provisioner

  • :transport (Transport::Base) —

    the transport (Required)

  • :verifier (Verifier) —

    the verifier 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



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/kitchen/instance.rb', line 93

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)
  @transport    = options.fetch(:transport)
  @verifier     = options.fetch(:verifier)
  @logger       = options.fetch(:logger) { Kitchen.logger }
  @state_file   = options.fetch(:state_file)

  setup_driver
  setup_provisioner
  setup_transport
  setup_verifier
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.



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

def mutexes
  @mutexes
end

Instance Attribute Details

#driver ⇒ Driver::Base (readonly) 



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

def driver
  @driver
end

#logger ⇒ Logger (readonly) 



76
77
78
 
# File 'lib/kitchen/instance.rb', line 76

def logger
  @logger
end

#name ⇒ String (readonly) 



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

def name
  @name
end

#platform ⇒ Platform (readonly) 



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

def platform
  @platform
end

#provisioner ⇒ Provisioner::Base (readonly) 



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

def provisioner
  @provisioner
end

#suite ⇒ Suite (readonly) 



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

def suite
  @suite
end

#transport ⇒ Transport::Base (readonly) 



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

def transport
  @transport
end

#verifier ⇒ Verifier (readonly) 



73
74
75
 
# File 'lib/kitchen/instance.rb', line 73

def verifier
  @verifier
end

Class Method Details

.name_for(suite, platform) ⇒ String

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



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.

See Also:



137
138
139
 
# File 'lib/kitchen/instance.rb', line 137

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.

See Also:



126
127
128
 
# File 'lib/kitchen/instance.rb', line 126

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.

See Also:



170
171
172
 
# File 'lib/kitchen/instance.rb', line 170

def destroy
  transition_to(:destroy)
end

#diagnose ⇒ Hash

Returns a Hash of configuration and other useful diagnostic information.



235
236
237
238
239
240
241
242
243
244
 
# File 'lib/kitchen/instance.rb', line 235

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

#diagnose_plugins ⇒ Hash

Returns a Hash of configuration and other useful diagnostic information associated with plugins (such as loaded version, class name, etc.).



250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/kitchen/instance.rb', line 250

def diagnose_plugins
  result = Hash.new
  [:driver, :provisioner, :verifier, :transport].each do |sym|
    obj = send(sym)
    result[sym] = if obj.respond_to?(:diagnose_plugin)
      obj.diagnose_plugin
    else
      :unknown
    end
  end
  result
end

#last_action ⇒ String

Returns the last successfully completed action state of the instance.



266
267
268
 
# File 'lib/kitchen/instance.rb', line 266

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 transport. This could be an SSH command, telnet, or serial console session.

Note This method calls exec and will not return.

See Also:



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/kitchen/instance.rb', line 206

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

  lc = if legacy_ssh_base_driver?
    (state)
  else
    transport.connection(state).
  end

  debug(%{Login command: #{lc.command} #{lc.arguments.join(" ")} } \
    "(Options: #{lc.options})")
  Kernel.exec(*lc.exec_args)
end

#remote_exec(command) ⇒ Object

Executes an arbitrary command on this instance.



226
227
228
229
230
 
# File 'lib/kitchen/instance.rb', line 226

def remote_exec(command)
  transport.connection(state_file.read) do |conn|
    conn.execute(command)
  end
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.

See Also:

  • Driver::Base#setup


148
149
150
 
# File 'lib/kitchen/instance.rb', line 148

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.



184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/kitchen/instance.rb', line 184

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.



115
116
117
 
# File 'lib/kitchen/instance.rb', line 115

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.

See Also:

  • Driver::Base#verify


159
160
161
 
# File 'lib/kitchen/instance.rb', line 159

def verify
  transition_to(:verify)
end