elecksee 1.0.22 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3d89dd64aa0c3a0ef232692735c75c415d0a994
+  data.tar.gz: 9b769a6d71ff3efa3320004e31f7bc18453ae66b
+SHA512:
+  metadata.gz: 0eb4a7dc26256da9e8ea791721391cfb89fe0edd041831a798654e6385ea71290070f8a18f8b6ca442cf025ebfba758375d61293a10f49dc5e69e4a3a841e896
+  data.tar.gz: e22ebacc0cabf3108d3ab04365b01c683caf36162155530cf2bfeddcb12a190ff4e2e32b63bf788e767ef6bb8df24c5438385bb11f1193febe881ccbcebc5191

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v1.1.0
+* Update all documentation to yardoc
+* Group classes into logical namespaces
+* Define expected returns for methods
+* Remove calls to lxc-shutdown (not always available)
+* Always attempt in container halt prior to lxc-stop
+* Use lxc-ls for container listing to prevent permission issues
+* Use the Rye library under the hood for container connects
+* Use ChildProcess for shelling out
+
 ## v1.0.22
 * Update underlying implementation for execute
 * Provide better info interpretation

data/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Branches
+
+### `master` branch
+
+The master branch is the current stable released version.
+
+### `develop` branch
+
+The develop branch is the current edge of development.
+
+## Pull requests
+
+* https://github.com/chrisroberts/elecksee/pulls
+
+Please base all pull requests of the `develop` branch. Merges to
+`master` only occur through the `develop` branch. Pull requests
+based on `master` will likely be cherry picked.
+
+## Issues
+
+Need to report an issue? Use the github issues:
+
+* https://github.com/chrisroberts/elecksee/issues

data/README.md

@@ -2,20 +2,57 @@
 
 An LXC library for Ruby
 
-## Usage
+## Basic usage
 
 ```ruby
-require 'elecksee/lxc'
+require 'elecksee'
 
 lxc = Lxc.new('container')
 lxc.start unless lxc.running?
 ```
 
-## Included
+## Permissions
 
-* Container inspect and interaction (`Lxc`)
-* Container cloning (`Lxc::Clone`)
-* Ephemeral containers (`Lxc::Ephemeral`)
+Root access is required for most operations. This library can
+be utilized from a root user but is built to use sudo as required.
+To enable sudo, use:
+
+```ruby
+Lxc.use_sudo = true
+```
+
+If you require a custom sudo for things like rvm, use:
+
+```ruby
+Lxc.use_sudo = 'rvmsudo'
+```
+
+## What's in the box
+
+### Lxc
+
+Container inspection and interaction. Will provide state
+information about the container as well as providing an
+interaction interface for running commands within the
+container and changing its state (stop, start, freeze, thaw).
+
+```ruby
+my_lxc = Lxc.new('my_container')
+puts "Address: #{my_lxc.container_ip}"
+puts "State: #{my_lxc.state}"
+```
+
+### Lxc::Ephemeral
+
+Create ephemeral containers from existing stopped containers. Utilizes
+an overlay filesystem to leave original container untouched. All ephemeral
+resources are removed once the container is halted.
+
+### Lxc::Clone
+
+Make clones of existing stopped containers. Allows for utilizing optional
+storage backends like full copies, overlay directories, virtual block
+device or fs specific like btrfs snapshots.
 
 ### Notes
 

data/elecksee.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.description = 'LXC helpers'
   s.require_path = 'lib'
   s.executables = %w(lxc-awesome-ephemeral)
-  s.add_dependency 'mixlib-shellout'
-  s.add_dependency 'net-ssh'
-  s.files = Dir['**/*']
+  s.add_dependency 'childprocess'
+  s.add_dependency 'rye'
+  s.files = Dir['{bin,lib}/**/**/*'] + %w(elecksee.gemspec README.md CHANGELOG.md LICENSE CONTRIBUTING.md)
 end

data/lib/elecksee/clone.rb

@@ -1,12 +1,7 @@
-%w(
-  helpers/base helpers/options helpers/copies lxc
-  storage/overlay_directory storage/overlay_mount
-  storage/virtual_device
-).each do |path|
-  require "elecksee/#{path}"
-end
+require 'elecksee'
 
 class Lxc
+  # Clone existing containers
   class Clone
 
     include Helpers
@@ -25,9 +20,14 @@ class Lxc
     option :gateway, '-G', :string, :desc => 'Custom gateway'
     option :netmask, '-N', :string, :default => '255.255.255.0', :desc => 'Custom netmask'
 
-    # Hash containing original and new container instances
+    # @return [Hash] original and new container instances
     attr_reader :lxcs
 
+    # Create new instance
+    #
+    # @param args [Hash]
+    # @option args [String] :original existing container name
+    # @option args [String] :new new container name
     def initialize(args={})
       configure!(args)
       @lxcs = {}
@@ -37,31 +37,40 @@ class Lxc
       validate!
     end
 
+    # Create the clone
+    #
+    # @return [Lxc] new clone
     def clone!
       begin
         copy_original
         update_naming(:no_config)
         apply_custom_addressing if ipaddress
-        lxcs[:new]
+        lxc
       rescue Exception
         @created.map(&:destroy)
         raise
       end
     end
-    
+
     private
 
     alias_method :name, :new_name
-    
-    # Returns new lxc instance
+
+    # @return [Lxc] new lxc instance
     def lxc
       lxcs[:new]
     end
 
+    # Add to list of created items
+    #
+    # @param thing [Object] item created
     def created(thing)
       @created << thing
     end
 
+    # Validate current state
+    #
+    # @return [TrueClass]
     def validate!
       unless(lxcs[:original].exists?)
         raise "Requested `original` container does not exist (#{original})"
@@ -72,8 +81,12 @@ class Lxc
       if(lxcs[:original].running?)
         raise "Requested `original` container is current running (#{original})"
       end
+      true
     end
 
+    # Create copy of original container
+    #
+    # @return [TrueClass]
     def copy_original
       copy_init
       if(device)
@@ -86,38 +99,56 @@ class Lxc
         rootfs_dir = copy_fs
       end
       update_rootfs(rootfs_dir)
+      true
     end
 
+    # Initialize container copy (base file copy)
+    #
+    # @return [TrueClass]
     def copy_init
-      directory = CloneDirectory.new(lxcs[:new].name, :dir => File.dirname(lxcs[:original].path.to_s))
+      directory = Storage::CloneDirectory.new(lxcs[:new].name, :dir => File.dirname(lxcs[:original].path.to_s))
       created(directory)
       %w(config fstab).each do |file|
         command("cp '#{lxcs[:original].path.join(file)}' '#{directory.target_path}'", :sudo => true)
       end
+      true
     end
 
+    # Copy into file system directory
+    #
+    # @return [String] path to new rootfs
     def copy_fs
-      directory = CloneDirectory.new(lxcs[:new].name, :dir => File.dirname(lxcs[:original].path.to_s))
+      directory = Storage::CloneDirectory.new(lxcs[:new].name, :dir => File.dirname(lxcs[:original].path.to_s))
       created(directory)
       command("rsync -ax '#{lxcs[:original].rootfs}/' '#{File.join(directory.target_path, 'rootfs')}/'", :sudo => true)
       File.join(directory.target_path, 'rootfs')
     end
 
+    # Copy into new virtual block device
+    #
+    # @return [String] path to new rootfs
     def copy_vbd
-      storage = VirtualDevice.new(lxcs[:new].name, :tmp_dir => '/opt/lxc-vbd')
+      storage = Storage::VirtualDevice.new(lxcs[:new].name, :tmp_dir => '/opt/lxc-vbd')
       created(storage)
       command("rsync -ax '#{lxcs[:original].rootfs}/' '#{storage.target_path}/'", :sudo => true)
       storage.target_path
     end
 
+    # Copy into new LVM partition
+    #
+    # @note not implemented
+    # @todo implement
     def copy_lvm
       raise 'Not implemented'
     end
 
+    # Copy into new btrfs subvolume snapshot
+    #
+    # @return [String] path to new rootfs
+    # @todo remove on failure
     def copy_btrfs
       rootfs_path = lxcs[:new].path.join('rootfs')
       command("btrfs subvolume snapshot '#{lxcs[:original].rootfs}' '#{rootfs_path}'", :sudo => true)
-      # TODO: Remove on failure
       rootfs_path
     end
   end

data/lib/elecksee/ephemeral.rb

@@ -1,18 +1,11 @@
+require 'elecksee'
 require 'securerandom'
 require 'fileutils'
 require 'tmpdir'
 require 'etc'
 
-%w(
-  helpers/base helpers/options helpers/copies lxc
-  storage/overlay_directory storage/overlay_mount
-  storage/virtual_device
-).each do |path|
-  require "elecksee/#{path}"
-end
-
 class Lxc
-
+  # Create ephemeral containers
   class Ephemeral
 
     include Helpers
@@ -34,15 +27,27 @@ class Lxc
     option :tmp_dir, '-T', :string, :default => '/tmp/lxc/ephemerals', :aliases => 'tmp-dir', :desc => 'Directory of ephemeral temp files'
     option :ephemeral_command, '-C', :string, :aliases => 'command'
 
+    # @return [String] name of container
     attr_reader :name
+    # @return [TrueClass, FalseClass] enable CLI output
     attr_reader :cli
+    # @return [String] hostname of container
     attr_reader :hostname
+    # @return [String] path to container
     attr_reader :path
+    # @return [Lxc] instance of ephemeral
     attr_reader :lxc
+    # @return [Storage::OverlayDirectory, Storage::VirtualDevice]
     attr_reader :ephemeral_device
+    # @return [Storage::OverlayMount]
     attr_reader :ephemeral_overlay
+    # @return [Array<Storage::VirtualDevice]
     attr_reader :ephemeral_binds
 
+    # Create new instance
+    #
+    # @param args [Hash]
+    # @option args [TrueClass, FalseClass] :cli enable CLI output
     def initialize(args={})
       configure!(args)
       @cli = args[:cli]
@@ -54,19 +59,34 @@ class Lxc
       @lxc = nil
     end
 
+    # Trap signals to force cleanup
+    #
+    # @return [TrueClass]
     def register_traps
       %w(TERM INT QUIT).each do |sig|
         Signal.trap(sig){ cleanup && raise }
       end
+      true
     end
 
+    # Write output to CLI
+    #
+    # @return [TrueClass, FalseClass]
     def cli_output
       if(cli)
         puts "New ephemeral container started. (#{name})"
         puts "    - Connect using: sudo ssh -i #{ssh_key} root@#{lxc.container_ip(10)}"
+        true
+      else
+        false
       end
     end
 
+    # Start the ephemeral container
+    #
+    # @return [TrueClass]
+    # @note generally should not be called directly
+    # @see start!
     def start_action
       begin
         lxc.start
@@ -83,10 +103,19 @@ class Lxc
       true
     end
 
+    # Create the ephemeral container
+    #
+    # @return [TrueClass]
     def create!
       setup
+      true
     end
 
+    # Start the ephemeral container
+    #
+    # @param args [Symbol] argument list
+    # @return [TrueClass]
+    # @note use :fork to fork startup
     def start!(*args)
       register_traps
       setup
@@ -102,8 +131,12 @@ class Lxc
       else
         start_action
       end
+      true
     end
 
+    # Stop container and cleanup ephemeral items
+    #
+    # @return [TrueClass, FalseClass]
     def cleanup
       lxc.stop
       @ephemeral_overlay.unmount
@@ -120,22 +153,29 @@ class Lxc
 
     private
 
+    # Setup the ephemeral container resources
+    #
+    # @return [TrueClass]
     def setup
       create
       build_overlay
       update_naming
       discover_binds
       apply_custom_networking if ipaddress
+      true
     end
 
+    # Create the overlay
+    #
+    # @return [TrueClass, FalseClass]
     def build_overlay
       if(directory)
-        @ephemeral_device = OverlayDirectory.new(name, :tmp_dir => directory.is_a?(String) ? directory : tmp_dir)
+        @ephemeral_device = Storage::OverlayDirectory.new(name, :tmp_dir => directory.is_a?(String) ? directory : tmp_dir)
       else
-        @ephemeral_device = VirtualDevice.new(name, :size => device, :tmp_fs => !device, :tmp_dir => tmp_dir)
+        @ephemeral_device = Storage::VirtualDevice.new(name, :size => device, :tmp_fs => !device, :tmp_dir => tmp_dir)
         @ephemeral_device.mount
       end
-      @ephemeral_overlay = OverlayMount.new(
+      @ephemeral_overlay = Storage::OverlayMount.new(
         :base => Lxc.new(original).rootfs.to_path,
         :overlay => ephemeral_device.target_path,
         :target => lxc.path.join('rootfs').to_path,
@@ -144,6 +184,9 @@ class Lxc
       @ephemeral_overlay.mount
     end
 
+    # Create the container
+    #
+    # @return [TrueClass]
     def create
       Dir.glob(File.join(lxc_dir, original, '*')).each do |o_path|
         next unless File.file?(o_path)
@@ -152,10 +195,15 @@ class Lxc
       @lxc = Lxc.new(name)
       command("mkdir -p #{lxc.path.join('rootfs')}", :sudo => true)
       update_net_hwaddr
+      true
     end
 
-    # TODO: Discovered binds for ephemeral are all tmpfs for now.
-    # TODO: We should default to overlay mount, make virt dev optional
+    # Discover any bind mounts defined
+    #
+    # @return [TrueClass]
+    # @todo discovered binds for ephemeral are all tmpfs for
+    #   now. should default to overlay mount, make virtual
+    #   device and tmpfs optional
     def discover_binds
       contents = File.readlines(lxc.path.join('fstab')).each do |line|
         parts = line.split(' ')
@@ -163,7 +211,7 @@ class Lxc
           source = parts.first
           target = parts[1].sub(%r{^.+rootfs/}, '')
           container_target = lxc.rootfs.join(target).to_path
-          device = VirtualDevice.new(target.gsub('/', '_'), :tmp_fs => true)
+          device = Storage::VirtualDevice.new(target.gsub('/', '_'), :tmp_fs => true)
           device.mount
           FileUtils.mkdir_p(container_target)
           ephemeral_binds << device
@@ -182,6 +230,8 @@ class Lxc
         contents << "#{bind} #{lxc.rootfs.join(bind)} none bind 0 0\n"
       end
       write_file(lxc.path.join('fstab'), contents.join)
+      true
     end
+
   end
 end

data/lib/elecksee/helpers/copies.rb

@@ -1,17 +1,24 @@
+require 'elecksee'
 require 'tempfile'
 
 class Lxc
   module Helpers
+    # Container related file copy helpers
     module Copies
-
+      # Files requiring name updates
       NAME_FILES = %w(fstab config)
+      # Files requiring hostname updates
       HOSTNAME_FILES = %w(
         rootfs/etc/hostname
         rootfs/etc/hosts
         rootfs/etc/sysconfig/network
         rootfs/etc/sysconfig/network-scripts/ifcfg-eth0
       )
-      
+
+      # Update the rootfs
+      #
+      # @param rootfs_path [String] new rootfs path
+      # @return [TrueClass]
       def update_rootfs(rootfs_path)
         contents = File.readlines(lxc.config.to_s).map do |line|
           if(line.start_with?('lxc.rootfs'))
@@ -21,8 +28,12 @@ class Lxc
           end
         end.join
         write_file(lxc.config, contents)
+        true
       end
 
+      # Update network hardware address
+      #
+      # @return [TrueClass]
       def update_net_hwaddr
         contents = File.readlines(lxc.config).map do |line|
           if(line.start_with?('lxc.network.hwaddr'))
@@ -33,8 +44,14 @@ class Lxc
           end
         end.join
         write_file(lxc.config, contents)
+        true
       end
 
+      # Write file
+      #
+      # @param path [String]
+      # @param contents [String, Array<String>]
+      # @return [TrueClass]
       def write_file(path, contents)
         contents = contents.join if contents.is_a?(Array)
         tmp = Tempfile.new('lxc-copy')
@@ -43,8 +60,14 @@ class Lxc
         command("cp #{tmp.path} #{path}", :sudo => true)
         tmp.unlink
         command("chmod 0644 #{path}", :sudo => true)
+        true
       end
-      
+
+      # Update container names and host names
+      #
+      # @param args [Symbol] argument list
+      # @return [TrueClass]
+      # @note use :no_$FILE where $FILE is the basename to skip
       def update_naming(*args)
         NAME_FILES.each do |file|
           next unless File.exists?(lxc.path.join(file))
@@ -54,16 +77,23 @@ class Lxc
         end
         HOSTNAME_FILES.each do |file|
           next unless File.exists?(lxc.path.join(file))
-          next if args.include?("no_#{file}".to_sym)
+          next if args.include?("no_#{file.split('/').last}".to_sym)
           contents = File.read(lxc.path.join(file)).gsub(original, name)
           write_file(lxc.path.join(file), contents)
         end
+        true
       end
 
+      # Container is Enterprise linux (redhat)
+      #
+      # @return [TrueClass, FalseClass]
       def el_platform?
         lxc.rootfs.join('etc/redhat-release').exist?
       end
-      
+
+      # Apply custom networking files depending on platform
+      #
+      # @return [TrueClass]
       def apply_custom_networking
         if(el_platform?)
           path = lxc.rootfs.join('etc/sysconfig/network-scripts/ifcfg-eth0')
@@ -100,6 +130,7 @@ gateway #{gateway}
 EOF
           write_file(path, content)
         end
+        true
       end
     end
   end

data/lib/elecksee/helpers/options.rb

@@ -1,13 +1,27 @@
+require 'elecksee'
+
 class Lxc
   module Helpers
-
+    # Helper methods for processing CLI options
     module Options
       class << self
+        # Load option helper into included class
+        #
+        # @param klass [Class]
+        # @return [TrueClass]
         def included(klass)
           klass.class_eval do
             class << self
+
+              # @return [Hash] options
               attr_reader :options
-              
+
+              # Define option
+              #
+              # @param name [String] name of option
+              # @param short [String] short flag
+              # @param long [String] long flag
+              # @param args [Hash]
               def option(name, short, type, args={})
                 @options ||= {}
                 @options[name] = args.merge(:short => short, :type => type)
@@ -22,6 +36,9 @@ class Lxc
 
       private
 
+      # Configure instance and validate options
+      #
+      # @param args [Array]
       def configure!(args)
         self.class.options.each do |name, opts|
           argv = args.detect{|k,v| (Array(opts[:aliases]) + Array(opts[:short]) + [name]).include?(k.to_sym)}
@@ -41,6 +58,12 @@ class Lxc
         end
       end
 
+      # Validate option type
+      #
+      # @param arg_name [String]
+      # @param val [Object]
+      # @param type [Symbol] expected type
+      # @return [TrueClass]
       def check_type!(arg_name, val, type)
         valid = false
         case type
@@ -51,7 +74,10 @@ class Lxc
         when :integer
           valid = val.is_a?(Numeric)
         end
-        raise ArgumentError.new "Invalid type provided for #{arg_name}. Expecting value type of: #{type.inspect} Got: #{val.class} -  #{val}" unless valid
+        unless(valid)
+          raise ArgumentError.new "Invalid type provided for #{arg_name}. Expecting value type of: #{type.inspect} Got: #{val.class} -  #{val}"
+        end
+        true
       end
     end
   end