Class: ChefMetal::Driver
- Inherits:
-
Object
- Object
- ChefMetal::Driver
- Defined in:
- lib/chef_metal/driver.rb
Overview
A Driver instance represents a place where machines can be created and found, and contains methods to create, delete, start, stop, and find them.
For AWS, a Driver instance corresponds to a single account. For Vagrant, it is a directory where VM files are found.
How to Make a Driver
To implement a Driver, you must implement the following methods:
-
initialize(driver_url) - create a new driver with the given URL
-
driver_url - a URL representing everything unique about your driver.
But NOT credentials.
-
allocate_machine - ask the driver to allocate a machine to you.
-
ready_machine - get the machine “ready” - wait for it to be booted and
accessible (for example, accessible via SSH transport).
-
stop_machine - stop the machine.
-
destroy_machine - delete the machine.
-
connect_to_machine - connect to the given machine.
Optionally, you can also implement:
-
allocate_machines - allocate an entire group of machines.
-
ready_machines - get a group of machines warm and booted.
-
stop_machines - stop a group of machines.
-
destroy_machines - delete a group of machines.
Additionally, you must create a file named ‘chef_metal/driver_init/<scheme>.rb`, where <scheme> is the name of the scheme you chose for your driver_url. This file, when required, must call ChefMetal.add_registered_driver(<scheme>, <class>). The given <class>.from_url(url, config) will be called with a driver_url and configuration.
All of these methods must be idempotent - if the work is already done, they just don’t do anything.
Instance Attribute Summary collapse
-
#config ⇒ Object
readonly
A configuration hash.
-
#driver_url ⇒ Object
readonly
A URL representing the driver and the place where machines come from.
Class Method Summary collapse
-
.from_url(driver_url, config) ⇒ Object
Override this on specific driver classes.
Instance Method Summary collapse
-
#allocate_machine(action_handler, machine_spec, machine_options) ⇒ Object
Allocate a machine from the PXE/cloud/VM/container driver.
-
#allocate_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Allocate a set of machines.
-
#connect_to_machine(machine_spec, machine_options) ⇒ Object
Connect to a machine without allocating or readying it.
-
#destroy_machine(action_handler, machine_spec, machine_options) ⇒ Object
Delete the given machine (idempotent).
-
#destroy_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Delete machines in batch, in parallel if possible.
-
#driver_options ⇒ Object
Driver configuration.
-
#initialize(driver_url, config) ⇒ Driver
constructor
Inflate a driver from a driver URL.
-
#ready_machine(action_handler, machine_spec, machine_options) ⇒ Object
Ready a machine, to the point where it is running and accessible via a transport.
-
#ready_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Ready machines in batch, in parallel if possible.
-
#stop_machine(action_handler, machine_spec, machine_options) ⇒ Object
Stop the given machine.
-
#stop_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Stop machines in batch, in parallel if possible.
Constructor Details
#initialize(driver_url, config) ⇒ Driver
Inflate a driver from a driver URL.
Parameters
driver_url - the URL to inflate the driver config - a configuration hash. See “config” for a list of known keys.
Returns
A Driver representing the given driver_url.
49 50 51 52 |
# File 'lib/chef_metal/driver.rb', line 49 def initialize(driver_url, config) @driver_url = driver_url @config = config end |
Instance Attribute Details
#config ⇒ Object (readonly)
A configuration hash. These keys may be present:
- :driver_options: a driver-defined object containing driver config.
- :private_keys: a hash of private keys, with a "name" and a "value". Values are either strings (paths) or PrivateKey objects.
- :private_key_paths: a list of paths to directories containing private keys.
- :write_private_key_path: the path to which we write new keys by default.
- :log_level: :debug/:info/:warn/:error/:fatal
- :chef_server_url: url to chef server
- :node_name: username to talk to chef server
- :client_key: path to key used to talk to chef server
86 87 88 |
# File 'lib/chef_metal/driver.rb', line 86 def config @config end |
#driver_url ⇒ Object (readonly)
A URL representing the driver and the place where machines come from. This will be stuffed in machine_spec.location so that the machine can be reinflated. URLs must have a unique scheme identifying the driver class, and enough information to identify the place where created machines can be found. For AWS, this is the account number; for lxc and vagrant, it is the directory in which VMs and containers are.
For example:
-
fog:AWS:123456789012
-
vagrant:/var/vms
-
lxc:
-
docker:
75 76 77 |
# File 'lib/chef_metal/driver.rb', line 75 def driver_url @driver_url end |
Class Method Details
.from_url(driver_url, config) ⇒ Object
Override this on specific driver classes
57 58 59 |
# File 'lib/chef_metal/driver.rb', line 57 def self.from_url(driver_url, config) ChefMetal.from_url(driver_url, config) end |
Instance Method Details
#allocate_machine(action_handler, machine_spec, machine_options) ⇒ Object
Allocate a machine from the PXE/cloud/VM/container driver. This method does not need to wait for the machine to boot or have an IP, but it must store enough information in machine_spec.location to find the machine later in ready_machine.
If a machine is powered off or otherwise unusable, this method may start it, but does not need to wait until it is started. The idea is to get the gears moving, but the job doesn’t need to be done :)
## Parameters action_handler - the action_handler object that is calling this method; this
is generally a driver, but could be anything that can support the
interface (i.e., in the case of the test kitchen metal driver for
acquiring and destroying VMs).
existing_machine - a MachineSpec representing the existing machine (if any).
machine_options - a set of options representing the desired provisioning
state of the machine (image name, bootstrap ssh credentials,
etc.). This will NOT be stored in the machine_spec, and is
ephemeral.
## Returns
Modifies the passed-in machine_spec. Anything in here will be saved back after allocate_machine completes.
123 124 125 |
# File 'lib/chef_metal/driver.rb', line 123 def allocate_machine(action_handler, machine_spec, ) raise "#{self.class} does not implement allocate_machine" end |
#allocate_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Allocate a set of machines. This should have the same effect as running allocate_machine on all machine_specs.
Drivers do not need to implement this; the default implementation calls acquire_machine in parallel.
## Parameters action_handler - the action_handler object that is calling this method; this
is generally a driver, but could be anything that can support the
interface (i.e., in the case of the test kitchen metal driver for
acquiring and destroying VMs).
specs_and_options - a hash of machine_spec -> machine_options representing the
machines to allocate.
parallelizer - an object with a parallelize() method that works like this:
parallelizer.parallelize() do |machine_spec|
allocate_machine(action_handler, machine_spec)
end.to_a
# The to_a at the end causes you to wait until the parallelization is done
This object is shared among other chef-metal actions, ensuring that you do not go over parallelization limits set by the user. Use of the parallelizer to parallelizer machines is not required.
## Block
If you pass a block to this function, each machine will be yielded to you as it completes, and then the function will return when all machines are yielded.
allocate_machines(action_handler, specs_and_options, parallelizer) do |machine_spec|
...
end
224 225 226 227 228 229 230 |
# File 'lib/chef_metal/driver.rb', line 224 def allocate_machines(action_handler, , parallelizer) parallelizer.parallelize() do |machine_spec, | allocate_machine(add_prefix(machine_spec, action_handler), machine_spec, ) yield machine_spec if block_given? machine_spec end.to_a end |
#connect_to_machine(machine_spec, machine_options) ⇒ Object
Connect to a machine without allocating or readying it. This method will NOT make any changes to anything, or attempt to wait.
## Parameters machine_spec - MachineSpec representing this machine.
## Returns
Machine object pointing at the machine, allowing useful actions like setup, converge, execute, file and directory.
166 167 168 |
# File 'lib/chef_metal/driver.rb', line 166 def connect_to_machine(machine_spec, ) raise "#{self.class} does not implement connect_to_machine" end |
#destroy_machine(action_handler, machine_spec, machine_options) ⇒ Object
Delete the given machine (idempotent). Should destroy the machine, returning things to the state before allocate_machine was called.
174 175 176 |
# File 'lib/chef_metal/driver.rb', line 174 def destroy_machine(action_handler, machine_spec, ) raise "#{self.class} does not implement destroy_machine" end |
#destroy_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Delete machines in batch, in parallel if possible.
250 251 252 253 254 255 |
# File 'lib/chef_metal/driver.rb', line 250 def destroy_machines(action_handler, , parallelizer) parallelizer.parallelize() do |machine_spec, | destroy_machine(add_prefix(machine_spec, action_handler), machine_spec, ) yield machine_spec if block_given? end.to_a end |
#driver_options ⇒ Object
Driver configuration. Equivalent to config || {}
91 92 93 |
# File 'lib/chef_metal/driver.rb', line 91 def config[:driver_options] || {} end |
#ready_machine(action_handler, machine_spec, machine_options) ⇒ Object
Ready a machine, to the point where it is running and accessible via a transport. This will NOT allocate a machine, but may kick it if it is down. This method waits for the machine to be usable, returning a Machine object pointing at the machine, allowing useful actions like setup, converge, execute, file and directory.
## Parameters action_handler - the action_handler object that is calling this method; this
is generally a driver, but could be anything that can support the
interface (i.e., in the case of the test kitchen metal driver for
acquiring and destroying VMs).
machine_spec - MachineSpec representing this machine. machine_options - a set of options representing the desired provisioning
state of the machine (image name, bootstrap ssh credentials,
etc.). This will NOT be stored in the machine_spec, and is
ephemeral.
## Returns
Machine object pointing at the machine, allowing useful actions like setup, converge, execute, file and directory.
150 151 152 |
# File 'lib/chef_metal/driver.rb', line 150 def ready_machine(action_handler, machine_spec, ) raise "#{self.class} does not implement ready_machine" end |
#ready_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Ready machines in batch, in parallel if possible.
233 234 235 236 237 238 239 |
# File 'lib/chef_metal/driver.rb', line 233 def ready_machines(action_handler, , parallelizer) parallelizer.parallelize() do |machine_spec, | machine = ready_machine(add_prefix(machine_spec, action_handler), machine_spec, ) yield machine if block_given? machine end.to_a end |
#stop_machine(action_handler, machine_spec, machine_options) ⇒ Object
Stop the given machine.
181 182 183 |
# File 'lib/chef_metal/driver.rb', line 181 def stop_machine(action_handler, machine_spec, ) raise "#{self.class} does not implement stop_machine" end |
#stop_machines(action_handler, specs_and_options, parallelizer) ⇒ Object
Stop machines in batch, in parallel if possible.
242 243 244 245 246 247 |
# File 'lib/chef_metal/driver.rb', line 242 def stop_machines(action_handler, , parallelizer) parallelizer.parallelize() do |machine_spec, | stop_machine(add_prefix(machine_spec, action_handler), machine_spec, ) yield machine_spec if block_given? end.to_a end |