Class: Kitchen::Provisioner::Base

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

Overview

Base class for a provisioner.

Author:

Direct Known Subclasses

Dummy, External, 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

Constructs a new provisioner by providing a configuration hash.

Parameters:

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

    initial provided configuration



62
63
64
 
# File 'lib/kitchen/provisioner/base.rb', line 62

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

Class Method Details

.kitchen_provisioner_api_version(version) ⇒ Object

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

Sets the API version for this provisioner

Examples:

setting an API version


module Kitchen
  module Provisioner
    class NewProvisioner < Kitchen::Provisioner::Base

      kitchen_provisioner_api_version 2

    end
  end
end

Parameters:

  • version (Integer, String) —

    a version number



259
260
261
 
# File 'lib/kitchen/provisioner/base.rb', line 259

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

Instance Method Details

#call(state) ⇒ Object

Runs the provisioner on the instance.

rubocop:disable Metrics/AbcSize

Parameters:

  • state (Hash) —

    mutable instance state

Raises:



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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/kitchen/provisioner/base.rb', line 71

def call(state)
  create_sandbox

  instance.transport.connection(state) do |conn|
    config[:uploads].to_h.each do |locals, remote|
      debug("Uploading #{Array(locals).join(", ")} to #{remote}")
      conn.upload(locals.to_s, remote)
    end

    # Check if we need to upload script (for Windows SSH or other scenarios requiring script upload)
    transport_config = instance.transport.instance_variable_get(:@config)
    debug("Windows OS: #{windows_os?} and Transport config: #{transport_config.inspect}")
    if windows_os? && transport_config && transport_config[:name] == "ssh"
      prepare_install_script
      # Run the init command to create the kitchen tmp directory
      conn.execute(encode_for_powershell(init_command))
      remote_script_path = remote_path_join(resolve_remote_path(config[:root_path]), "install_script.ps1")
      if install_script_path
        debug("Uploading install script to #{remote_script_path}")
        conn.upload(install_script_path, remote_script_path)
        debug("Executing install script with #{run_script_command(remote_script_path)}")
        conn.execute(run_script_command(remote_script_path))
      end
    else
      # For all other scenarios, execute install command directly
      debug("Executing install command: #{install_command}")
      conn.execute(install_command)
    end

    # The install script will remove the kitchen tmp directory, hence creating it again.
    conn.execute(init_command)
    info("Transferring files to #{instance.to_str}")
    conn.upload(sandbox_dirs, resolve_remote_path(config[:root_path]))
    debug("Transfer complete")
    debug("Executing prepare command: #{prepare_command}")
    conn.execute(prepare_command)
    debug("Executing run command: #{run_command}")
    begin
      conn.execute_with_retry(
        encode_for_powershell(run_command),
        config[:retry_on_exit_code],
        config[:max_retries],
        config[:wait_for_retry]
      )
    ensure
      # Retrieval is best-effort: a file we could not fetch must not
      # fail an otherwise successful converge, 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 converge 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

#check_license ⇒ Object

Certain products that Test Kitchen uses to provision require accepting a license to use. Overwrite this method in the specific provisioner to implement this check.



153
 
# File 'lib/kitchen/provisioner/base.rb', line 153

def check_license; 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.



232
233
234
235
236
237
238
 
# File 'lib/kitchen/provisioner/base.rb', line 232

def cleanup_sandbox
  return if sandbox_path.nil?

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

#create_sandbox ⇒ Object

Creates a temporary directory on the local workstation into which provisioner related files and directories can be copied or created. The contents of this directory will be copied over to the instance before invoking the provisioner'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 MyProvisioner < Kitchen::Provisioner::Base
  def create_sandbox
    super
    # any further file copies, preparations, etc.
  end
end


203
204
205
206
207
208
 
# File 'lib/kitchen/provisioner/base.rb', line 203

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) ⇒ Object

Check system and configuration for common errors.

Parameters:

  • state (Hash) —

    mutable instance state



146
147
148
 
# File 'lib/kitchen/provisioner/base.rb', line 146

def doctor(state)
  false
end

#init_command ⇒ String

Generates a command string which will perform any data initialization or configuration required after the provisioner 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



168
 
# File 'lib/kitchen/provisioner/base.rb', line 168

def init_command; end

#install_command ⇒ String

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

Returns:

  • (String) —

    a command string



160
 
# File 'lib/kitchen/provisioner/base.rb', line 160

def install_command; end

#prepare_command ⇒ String

Generates a command string which will perform any commands or configuration required just before the main provisioner 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



176
 
# File 'lib/kitchen/provisioner/base.rb', line 176

def prepare_command; end

#run_command ⇒ String

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

Returns:

  • (String) —

    a command string



183
 
# File 'lib/kitchen/provisioner/base.rb', line 183

def run_command; end

#sandbox_dirs ⇒ String

Returns the list of items in the sandbox directory

Returns:

  • (String) —

    path of items in the sandbox directory



225
226
227
 
# File 'lib/kitchen/provisioner/base.rb', line 225

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 no yet been created by calling #create_sandbox



216
217
218
219
220
 
# File 'lib/kitchen/provisioner/base.rb', line 216

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