chef-metal 0.10.2 → 0.11.beta

data/lib/chef_metal/{provider.rb → driver.rb}

@@ -1,60 +1,70 @@
 module ChefMetal
   #
-  # A Provider instance represents a place where machines can be created and found,
+  # 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 Provider instance corresponds to a single account.
+  # 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 Provider
+  # == How to Make a Driver
   #
-  # To implement a Provider, you must implement the following methods:
+  # 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 provider.
+  # - 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.
-  # - delete_machine - delete 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.
-  # - resource_created - a hook to tell you when a resource associated with your
-  #                      provider has been created.
+  # - 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/provider_init/<scheme>.rb`,
+  # 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
+  # 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.
   #
-  class Provider
+  class Driver
     #
-    # Inflate a driver from node information; we don't want to force the
-    # driver to figure out what the driver really needs, since it varies
-    # from driver to driver.
+    # Inflate a driver from a driver URL.
     #
-    # ## Parameters
+    # == Parameters
     # driver_url - the URL to inflate the driver
+    # config - a configuration hash.  See "config" for a list of known keys.
     #
-    # ## Returns
-    # A Provider representing the given driver_url.
-    def initialize(driver_url)
-      # We do not save it ... it's up to the driver to extract whatever information
-      # it wants.
+    # == Returns
+    # A Driver representing the given driver_url.
+    #
+    def initialize(driver_url, config)
+      @driver_url = driver_url
+      @config = config
+    end
+
+    #
+    # Override this on specific driver classes
+    #
+    def self.from_url(driver_url, config)
+      ChefMetal.from_url(driver_url, config)
     end
 
     #
     # A URL representing the driver and the place where machines come from.
-    # This will be stuffed in attributes in the node so that the node 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.
+    # This will be stuffed in machine_spec.location['driver_url'] 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
@@ -62,15 +72,31 @@ module ChefMetal
     # - lxc:
     # - docker:
     #
-    def driver_url
-      raise "#{self.class} does not implement driver_url"
+    attr_reader :driver_url
+
+    # 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
+    attr_reader :config
+
+    #
+    # Driver configuration. Equivalent to config[:driver_options] || {}
+    #
+    def driver_options
+      config[:driver_options] || {}
     end
 
     #
-    # Allocate a machine from the PXE/cloud/VM/container provider.  This method
+    # 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 node['normal']['driver_output'] to find
-    # the machine later in ready_machine.
+    # 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
@@ -78,7 +104,7 @@ module ChefMetal
     #
     # ## Parameters
     # action_handler - the action_handler object that is calling this method; this
-    #        is generally a provider, but could be anything that can support the
+    #        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).
     #
@@ -86,13 +112,13 @@ module ChefMetal
     #
     # 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 node, and is
+    #                   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 to the node.
+    # back after allocate_machine completes.
     #
     def allocate_machine(action_handler, machine_spec, machine_options)
       raise "#{self.class} does not implement allocate_machine"
@@ -107,17 +133,21 @@ module ChefMetal
     #
     # ## Parameters
     # action_handler - the action_handler object that is calling this method; this
-    #        is generally a provider, but could be anything that can support the
+    #        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.
     #
-    def ready_machine(action_handler, machine_spec)
+    def ready_machine(action_handler, machine_spec, machine_options)
       raise "#{self.class} does not implement ready_machine"
     end
 
@@ -133,7 +163,7 @@ module ChefMetal
     # Machine object pointing at the machine, allowing useful actions like setup,
     # converge, execute, file and directory.
     #
-    def connect_to_machine(machine_spec)
+    def connect_to_machine(machine_spec, machine_options)
       raise "#{self.class} does not implement connect_to_machine"
     end
 
@@ -141,14 +171,14 @@ module ChefMetal
     # Delete the given machine (idempotent).  Should destroy the machine,
     # returning things to the state before allocate_machine was called.
     #
-    def delete_machine(action_handler, machine_spec)
-      raise "#{self.class} does not implement delete_machine"
+    def destroy_machine(action_handler, machine_spec, machine_options)
+      raise "#{self.class} does not implement destroy_machine"
     end
 
     #
     # Stop the given machine.
     #
-    def stop_machine(action_handler, machine_spec)
+    def stop_machine(action_handler, machine_spec, machine_options)
       raise "#{self.class} does not implement stop_machine"
     end
 
@@ -158,21 +188,22 @@ module ChefMetal
 
     #
     # Allocate a set of machines.  This should have the same effect as running
-    # allocate_machine on all nodes.
+    # allocate_machine on all machine_specs.
     #
-    # Providers do not need to implement this; the default implementation
+    # Drivers do not need to implement this; the default implementation
     # calls acquire_machine in parallel.
     #
-    # ## Parameter
+    # ## Parameters
     # action_handler - the action_handler object that is calling this method; this
-    #        is generally a provider, but could be anything that can support the
+    #        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).
-    # nodes - a list of nodes representing the nodes to acquire.
+    # 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(nodes) do |node|
-    #     allocate_machine(action_handler, node)
+    #   parallelizer.parallelize(specs_and_options) 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
     #
@@ -180,60 +211,53 @@ module ChefMetal
     # not go over parallelization limits set by the user.  Use of the parallelizer
     # to parallelizer machines is not required.
     #
-    def allocate_machines(action_handler, machine_specs, parallelizer)
-      parallelizer.parallelize(machine_specs) do |machine_spec|
-        allocate_machine(add_prefix(machine_spec, action_handler), machine_spec)
+    # ## 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
+    #
+    def allocate_machines(action_handler, specs_and_options, parallelizer)
+      parallelizer.parallelize(specs_and_options) do |machine_spec, machine_options|
+        allocate_machine(add_prefix(machine_spec, action_handler), machine_spec, machine_options)
         yield machine_spec if block_given?
-        machine
+        machine_spec
       end.to_a
     end
 
     # Acquire machines in batch, in parallel if possible.
-    def acquire_machines(action_handler, machine_specs, parallelizer)
-      parallelizer.parallelize(machine_specs) do |machine_spec|
-        machine = acquire_machine(add_prefix(machine_spec, action_handler), machine_spec)
-        yield machine_spec, machine if block_given?
+    def ready_machines(action_handler, specs_and_options, parallelizer)
+      parallelizer.parallelize(specs_and_options) do |machine_spec, machine_options|
+        machine = ready_machine(add_prefix(machine_spec, action_handler), machine_spec, machine_options)
+        yield machine if block_given?
         machine
       end.to_a
     end
 
     # Stop machines in batch, in parallel if possible.
-    def stop_machines(action_handler, nodes_json, parallelizer)
-      parallelizer.parallelize(machine_specs) do |machine_spec|
-        stop_machine(add_prefix(machine_spec, action_handler), machine_spec)
+    def stop_machines(action_handler, specs_and_options, parallelizer)
+      parallelizer.parallelize(specs_and_options) do |machine_spec, machine_options|
+        stop_machine(add_prefix(machine_spec, action_handler), machine_spec, machine_options)
         yield machine_spec if block_given?
       end.to_a
     end
 
     # Delete machines in batch, in parallel if possible.
-    def delete_machines(action_handler, machine_specs, parallelizer)
-      parallelizer.parallelize(machine_specs) do |machine_spec|
-        delete_machine(add_prefix(machine_spec, action_handler), machine_spec)
+    def destroy_machines(action_handler, specs_and_options, parallelizer)
+      parallelizer.parallelize(specs_and_options) do |machine_spec, machine_options|
+        destroy_machine(add_prefix(machine_spec, action_handler), machine_spec, machine_options)
         yield machine_spec if block_given?
       end.to_a
     end
 
-    #
-    # Provider notification that happens at the point a machine resource is declared
-    # (after all properties have been set on it)
-    #
-    def resource_created(machine)
-    end
-
     protected
 
-    def save_node(provider, node, chef_server)
-      # Save the node and create the client.  TODO strip automatic attributes first so we don't race with "current state"
-      ChefMetal.inline_resource(provider) do
-        chef_node node['name'] do
-          chef_server chef_server
-          raw_json node
-        end
-      end
-    end
-
-    def add_prefix(node_json, action_handler)
-      AddPrefixActionHandler.new(action_handler, "[#{node_json['name']}] ")
+    def add_prefix(machine_spec, action_handler)
+      AddPrefixActionHandler.new(action_handler, "[#{machine_spec.name}] ")
     end
   end
 end

data/lib/chef_metal/machine.rb

@@ -1,19 +1,27 @@
 module ChefMetal
   class Machine
-    def initialize(node)
-      @node = node
+    def initialize(machine_spec)
+      @machine_spec = machine_spec
     end
 
-    attr_reader :node
+    attr_reader :machine_spec
+
+    def name
+      machine_spec.name
+    end
+
+    def node
+      machine_spec.node
+    end
 
     # Sets up everything necessary for convergence to happen on the machine.
     # The node MUST be saved as part of this procedure.  Other than that,
     # nothing is guaranteed except that converge() will work when this is done.
-    def setup_convergence(action_handler, machine_resource)
+    def setup_convergence(action_handler)
       raise "setup_convergence not overridden on #{self.class}"
     end
 
-    def converge(action_handler, chef_server)
+    def converge(action_handler)
       raise "converge not overridden on #{self.class}"
     end
 

data/lib/chef_metal/machine/basic_machine.rb

@@ -3,8 +3,8 @@ require 'chef_metal/machine'
 module ChefMetal
   class Machine
     class BasicMachine < Machine
-      def initialize(node, transport, convergence_strategy)
-        super(node)
+      def initialize(machine_spec, transport, convergence_strategy)
+        super(machine_spec)
         @transport = transport
         @convergence_strategy = convergence_strategy
       end
@@ -13,18 +13,18 @@ module ChefMetal
       attr_reader :convergence_strategy
 
       # Sets up everything necessary for convergence to happen on the machine.
-      # The node MUST be saved as part of this procedure.  Other than that,
+      # The machine_spec MUST be saved as part of this procedure.  Other than that,
       # nothing is guaranteed except that converge() will work when this is done.
-      def setup_convergence(action_handler, machine_resource)
-        convergence_strategy.setup_convergence(action_handler, self, machine_resource)
+      def setup_convergence(action_handler)
+        convergence_strategy.setup_convergence(action_handler, self)
       end
 
-      def converge(action_handler, chef_server)
-        convergence_strategy.converge(action_handler, self, chef_server)
+      def converge(action_handler)
+        convergence_strategy.converge(action_handler, self)
       end
 
       def execute(action_handler, command, options = {})
-        action_handler.perform_action "run '#{command}' on #{node['name']}" do
+        action_handler.perform_action "run '#{command}' on #{machine_spec.name}" do
           result = transport.execute(command, options)
           result.error!
           result
@@ -41,7 +41,7 @@ module ChefMetal
 
       def download_file(action_handler, path, local_path)
         if files_different?(path, local_path)
-          action_handler.perform_action "download file #{path} on #{node['name']} to #{local_path}" do
+          action_handler.perform_action "download file #{path} on #{machine_spec.name} to #{local_path}" do
             transport.download_file(path, local_path)
           end
         end
@@ -52,7 +52,7 @@ module ChefMetal
           if options[:ensure_dir]
             create_dir(action_handler, dirname_on_machine(path))
           end
-          action_handler.perform_action "write file #{path} on #{node['name']}" do
+          action_handler.perform_action "write file #{path} on #{machine_spec.name}" do
             transport.write_file(path, content)
           end
         end
@@ -63,7 +63,7 @@ module ChefMetal
           if options[:ensure_dir]
             create_dir(action_handler, dirname_on_machine(path))
           end
-          action_handler.perform_action "upload file #{local_path} to #{path} on #{node['name']}" do
+          action_handler.perform_action "upload file #{local_path} to #{path} on #{machine_spec.name}" do
             transport.upload_file(local_path, path)
           end
         end

data/lib/chef_metal/machine/unix_machine.rb

@@ -4,7 +4,7 @@ require 'digest'
 module ChefMetal
   class Machine
     class UnixMachine < BasicMachine
-      def initialize(node, transport, convergence_strategy)
+      def initialize(machine_spec, transport, convergence_strategy)
         super
 
         @tmp_dir = '/tmp'
@@ -18,7 +18,7 @@ module ChefMetal
       # Delete file
       def delete_file(action_handler, path)
         if file_exists?(path)
-          action_handler.perform_action "delete file #{path} on #{node['name']}" do
+          action_handler.perform_action "delete file #{path} on #{machine_spec.name}" do
             transport.execute("rm -f #{path}").error!
           end
         end
@@ -61,7 +61,7 @@ module ChefMetal
 
       def create_dir(action_handler, path)
         if !file_exists?(path)
-          action_handler.perform_action "create directory #{path} on #{node['name']}" do
+          action_handler.perform_action "create directory #{path} on #{machine_spec.name}" do
             transport.execute("mkdir -p #{path}").error!
           end
         end
@@ -72,17 +72,17 @@ module ChefMetal
         if attributes[:mode] || attributes[:owner] || attributes[:group]
           current_attributes = get_attributes(path)
           if attributes[:mode] && current_attributes[:mode].to_i != attributes[:mode].to_i
-            action_handler.perform_action "change mode of #{path} on #{node['name']} from #{current_attributes[:mode].to_i} to #{attributes[:mode].to_i}" do
+            action_handler.perform_action "change mode of #{path} on #{machine_spec.name} from #{current_attributes[:mode].to_i} to #{attributes[:mode].to_i}" do
               transport.execute("chmod #{attributes[:mode].to_i} #{path}").error!
             end
           end
           if attributes[:owner] && current_attributes[:owner] != attributes[:owner]
-            action_handler.perform_action "change group of #{path} on #{node['name']} from #{current_attributes[:owner]} to #{attributes[:owner]}" do
+            action_handler.perform_action "change group of #{path} on #{machine_spec.name} from #{current_attributes[:owner]} to #{attributes[:owner]}" do
               transport.execute("chown #{attributes[:owner]} #{path}").error!
             end
           end
           if attributes[:group] && current_attributes[:group] != attributes[:group]
-            action_handler.perform_action "change group of #{path} on #{node['name']} from #{current_attributes[:group]} to #{attributes[:group]}" do
+            action_handler.perform_action "change group of #{path} on #{machine_spec.name} from #{current_attributes[:group]} to #{attributes[:group]}" do
               transport.execute("chgrp #{attributes[:group]} #{path}").error!
             end
           end