stackadmin 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9356c67e44d2b41f466700e39b383e6ddf8599d9
-  data.tar.gz: 90080f91deaa13008ee34454051567d44c1ee291
+  metadata.gz: 1e2ddf654357669ce50978cf4616b55f25244cbf
+  data.tar.gz: 483e8a3ba68b7995367b40af91791b1aca24e5e0
 SHA512:
-  metadata.gz: 7cdf3b9b5f4f8157f00c5d3826ea8643fdae871c4105004e0ae11ec8910b14c1b4a448f1b1c17fdeb61a5c60b85c70837f27d082b6dca0416d7d85c836abb058
-  data.tar.gz: 4925bc36f4ab907e38ee5fc41b4aa2d553fe1b615685d7d26040ffa2e77e2b352bde2bd1604b7f887abf738e5d07e7b28473103e78d866aecfb3c27ec9143ba2
+  metadata.gz: bb485c2bb8ea145d9247945efc5d2a7f8d520e7f9b83c3e810a3508e1fc86a24c10541bcf16cb919c11544a68a216df02ce4fd39b3fc9d01819e6d501726335b
+  data.tar.gz: 33fa85e6175d55f656aacfd9d4eb685bba74eb798663972fef9684f337831f8591c6d211b87afcd16eec659786ac83621eaf57d759d7c690380cc71894ae1480

data/.gitignore

@@ -1 +1,6 @@
 test/.vagrant
+*.gem
+doc
+.yardoc
+.DS_Store
+bin

data/CHANGELOG

@@ -0,0 +1,14 @@
+0.1.1 (2011-03-11)
+==================
+
+New
+---
+- 100% YARD doc coverage
+
+Changes
+-------
+- Added basic README
+
+Fix
+---
+- Switched from vagrant to vagrant-wrapper gem

data/Gemfile

@@ -1,14 +1,13 @@
 source 'https://rubygems.org'
+ruby '2.0.0'
 
-gem 'net-ssh'
-gem 'json'
+gem 'net-ssh', '~> 2.9.2'
+gem 'json', '~> 1.8.2'
 
 group :development do
-  gem 'minitest'
-  gem 'minitest-reporters'
-  gem 'vagrant', git: 'https://github.com/mitchellh/vagrant.git'
-end
-
-group :plugins do
-  gem 'vagrant-s3auth'
+  gem 'minitest', '~> 4.3.2'
+  gem 'minitest-reporters', '~> 0.14.24'
+  gem 'rake', '~> 10.4.2'
+  gem 'vagrant-wrapper', '~> 2.0.2'
+  gem 'yard', '~> 0.8.7.6'
 end

data/Gemfile.lock

@@ -1,119 +1,32 @@
-GIT
-  remote: https://github.com/mitchellh/vagrant.git
-  revision: b2c722ef54e57c9de5cdbe712b27e52faacec5da
-  specs:
-    vagrant (1.7.2)
-      bundler (>= 1.5.2, < 1.8.0)
-      childprocess (~> 0.5.0)
-      erubis (~> 2.7.0)
-      hashicorp-checkpoint (~> 0.1.1)
-      i18n (~> 0.6.0)
-      listen (~> 2.8.0)
-      log4r (~> 1.1.9, < 1.1.11)
-      net-scp (~> 1.1.0)
-      net-sftp (~> 2.1)
-      net-ssh (>= 2.6.6, < 2.10.0)
-      nokogiri (= 1.6.3.1)
-      rb-kqueue (~> 0.2.0)
-      rest-client (>= 1.6.0, < 2.0)
-      wdm (~> 0.1.0)
-      winrm (~> 1.3.0)
-      winrm-fs (~> 0.1.0)
-
 GEM
   remote: https://rubygems.org/
   specs:
     ansi (1.5.0)
-    aws-sdk (1.59.1)
-      aws-sdk-v1 (= 1.59.1)
-    aws-sdk-v1 (1.59.1)
-      json (~> 1.4)
-      nokogiri (>= 1.4.4)
     builder (3.2.2)
-    celluloid (0.16.0)
-      timers (~> 4.0.0)
-    childprocess (0.5.5)
-      ffi (~> 1.0, >= 1.0.11)
-    erubis (2.7.0)
-    ffi (1.9.6)
-    gssapi (1.2.0)
-      ffi (>= 1.0.1)
-    gyoku (1.2.2)
-      builder (>= 2.1.2)
-    hashicorp-checkpoint (0.1.4)
     hashie (3.4.0)
-    hitimes (1.2.2)
-    httpclient (2.6.0.1)
-    i18n (0.6.11)
     json (1.8.2)
-    listen (2.8.5)
-      celluloid (>= 0.15.2)
-      rb-fsevent (>= 0.9.3)
-      rb-inotify (>= 0.9)
-    little-plugger (1.1.3)
-    log4r (1.1.10)
-    logging (1.8.2)
-      little-plugger (>= 1.1.3)
-      multi_json (>= 1.8.4)
-    mime-types (2.4.3)
-    mini_portile (0.6.0)
-    minitest (4.3.2)
+    minitest (4.3.3)
     minitest-reporters (0.14.24)
       ansi
       builder
       minitest (>= 2.12, < 5.0)
       powerbar
-    multi_json (1.10.1)
-    net-scp (1.1.2)
-      net-ssh (>= 2.6.5)
-    net-sftp (2.1.2)
-      net-ssh (>= 2.6.5)
     net-ssh (2.9.2)
-    netrc (0.10.2)
-    nokogiri (1.6.3.1)
-      mini_portile (= 0.6.0)
-    nori (2.4.0)
     powerbar (1.0.12)
       ansi (~> 1.5.0)
       hashie (>= 1.1.0)
-    rb-fsevent (0.9.4)
-    rb-inotify (0.9.5)
-      ffi (>= 0.5.0)
-    rb-kqueue (0.2.3)
-      ffi (>= 0.5.0)
-    rest-client (1.7.2)
-      mime-types (>= 1.16, < 3.0)
-      netrc (~> 0.7)
-    rubyntlm (0.4.0)
-    rubyzip (1.1.7)
-    timers (4.0.1)
-      hitimes
-    uuidtools (2.1.5)
-    vagrant-s3auth (1.0.2)
-      aws-sdk (~> 1.59.1)
-    wdm (0.1.0)
-    winrm (1.3.0)
-      builder (>= 2.1.2)
-      gssapi (~> 1.2)
-      gyoku (~> 1.0)
-      httpclient (~> 2.2, >= 2.2.0.2)
-      logging (~> 1.6, >= 1.6.1)
-      nori (~> 2.0)
-      rubyntlm (~> 0.4.0)
-      uuidtools (~> 2.1.2)
-    winrm-fs (0.1.0)
-      erubis (~> 2.7)
-      logging (~> 1.6, >= 1.6.1)
-      rubyzip (~> 1.1)
-      winrm (~> 1.3.0)
+    rake (10.4.2)
+    vagrant-wrapper (2.0.2)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  json
-  minitest
-  minitest-reporters
-  net-ssh
-  vagrant!
-  vagrant-s3auth
+  json (~> 1.8.2)
+  minitest (~> 4.3.2)
+  minitest-reporters (~> 0.14.24)
+  net-ssh (~> 2.9.2)
+  rake (~> 10.4.2)
+  vagrant-wrapper (~> 2.0.2)
+  yard (~> 0.8.7.6)

data/README.md

@@ -1,2 +1,73 @@
 # stackadmin
 Gem to facilitate administration of Stackato deployments
+
+## Install
+```
+gem install stackadmin
+```
+
+Then, `require 'stackadmin'` in your application.
+
+## Requirements
+- Ruby 2.0.0
+- Target Stackato nodes must be set up for [Passwordless SSH access](http://www.linuxproblem.org/art_9.html).
+
+## Testing
+### The happy path
+```
+bundle install
+bundle exec rake test
+```
+
+That should get everything set up for you. It will spin up a vagrant VM, run all tests, and then destroy the vagrant VM.
+
+Problems? Read on.
+
+### Setting up the test env
+Install your dependencies:
+```
+bundle install
+```
+
+The test environment depends on [Vagrant](http://www.vagrantup.com/) (>= 1.5.1) and [vagrant-s3auth](https://github.com/WhoopInc/vagrant-s3auth).
+
+The Vagrant VM depends on a custom basebox stored in our private S3 bucket.
+
+You should have access credentials stored in the standard environment variables (i.e. `ENV['AWS_ACCESS_KEY_ID']` and `ENV['AWS_SECRET_ACCESS_KEY']`) in order to have Vagrant download the basebox automatically.
+
+To verify that these requirements are met:
+```
+bundle exec rake test:setup_vagrant
+```
+
+To spin up the Vagrant box:
+```
+bundle exec rake test:start_env
+```
+
+To fulfill the passwordless SSH requirement to the `stackato` user in the test env:
+```
+bundle exec rake test:setup_env
+```
+
+That last command assumes that your personal public key is located in `~/.ssh/keys/id_rsa.pub`. If your key is located elsewhere, you can specify the location as follows:
+```
+bundle exec rake test:setup_env['~/.ssh/certs/me.pub']
+```
+where `<pub_key_location>` is the path to your public key.
+
+You can also provide the public key location when using `rake test`:
+```
+bundle exec rake test['~/.ssh/certs/me.pub']
+```
+
+### Run tests
+Currently, all tests are in a single suite:
+```
+bundle exec rake test:run
+```
+
+### Destroy the test env
+```
+bundle exec rake test:destroy_env
+```

data/Rakefile

@@ -1,24 +1,42 @@
 # Encoding: utf-8
 require 'rake/testtask'
+require_relative 'test/helpers/vagrant'
 
 task :default => 'test'
 
 namespace :test do
+  desc 'Setup vagrant'
+  task :setup_vagrant do
+    vagrant = VagrantWrapper.require_or_help_install(">= #{MIN_VAGRANT}")
+    puts "Vagrant v#{vagrant.vagrant_version} found!"
+    raise 'Unable to install "vagrant-s3auth" plugin!' unless vagrant.install_plugin('vagrant-s3auth')
+
+    missing = missing_aws_creds
+    if missing.empty?
+      puts 'S3 credentials found!'
+    else
+      raise "The following environment variables must be defined: #{missing.join(', ')}"
+    end
+  end
+
   desc 'Spin up test env'
   task :start_env  do
-    Dir.chdir('test') { system('bundle exec vagrant up') }
+    Dir.chdir('test') { system("#{VAGRANT} up") }
   end
 
   desc 'Setup test env'
-  task :setup, :pub_key_location do |t, args|
-    pub_key_location = args[:pub_key_location] || File.expand_path('~/.ssh/keys/id_rsa.pub')
+  task :setup_env, :pub_key_location do |_, args|
+    pub_key_location = args[:pub_key_location] || '~/.ssh/keys/id_rsa.pub'
+    pub_key_location = File.expand_path(pub_key_location)
     pub_key = File.open(pub_key_location, 'r').read
-    Dir.chdir('test') { system("vagrant ssh --command 'echo \"#{pub_key}\" | sudo tee -a /home/stackato/.ssh/authorized_keys' > /dev/null") }
+    Dir.chdir('test') do
+      system("#{VAGRANT} ssh --command 'echo \"#{pub_key}\" | sudo tee -a /home/stackato/.ssh/authorized_keys' > /dev/null")
+    end
   end
 
   desc 'Destroy test env'
   task :destroy_env do
-    Dir.chdir('test') { system('bundle exec vagrant destroy --force') }
+    Dir.chdir('test') { system("#{VAGRANT} destroy --force") }
   end
 end
 
@@ -27,11 +45,19 @@ Rake::TestTask.new('test:run') do |t|
 end
 
 desc 'Run all test tasks'
-task :test do
-  %w( start_env setup run destroy_env ).each do |j|
+task :test, :pub_key_location do |_, args|
+  %w( setup_vagrant start_env setup_env run destroy_env ).each do |j|
     job = "test:#{j}"
-    puts "\e[35mRunning #{job}...\e[0m"
-    Rake::Task[job].invoke
+    print "\e[35mRunning #{job}"
+
+    if j == 'setup_env' && !args[:pub_key_location].nil?
+      puts "['#{args[:pub_key_location]}']...\e[0m"
+      Rake::Task[job].invoke(args[:pub_key_location])
+    else
+      puts "...\e[0m"
+      Rake::Task[job].invoke
+    end
+
     puts
   end
 end

data/lib/stackadmin/audit.rb

@@ -7,6 +7,11 @@ require_relative 'net-ssh'
 class Stackadmin
   private
 
+  # SSHes into the target node and populates the instance variables with the
+  # results of the audit
+  #
+  # @param target [String] the hostname, FQDN, or IP address of the target node
+  # @raise [Net::SSH::Exception] if unable to SSH to target
   def audit(target = @id)
     @id = target
     log "Auditing #{@id}"
@@ -25,6 +30,10 @@ class Stackadmin
     end
   end
 
+  # Retrieves the current version designation of the target Stackato node
+  #
+  # @param ssh [Net::SSH::Connection::Session] an ssh session to the target node
+  # @return [String] the target node's installed Stackato version
   def parse_version(ssh)
     cmd = ssh.exec_sc!('kato info | grep Version')
     ver = cmd[:stdout].split.last
@@ -36,6 +45,10 @@ class Stackadmin
     ver
   end
 
+  # Retrieves the current license assigned to the target Stackato node
+  #
+  # @param (see #parse_version)
+  # @return [Hash] the details of the installed license
   def parse_license(ssh)
     license = Hash.new
 
@@ -47,6 +60,10 @@ class Stackadmin
     license
   end
 
+  # Maps the target cluster's nodes into a hash
+  #
+  # @param (see #parse_version)
+  # @return [Hash] the details of each node in the cluster
   def map_nodes(ssh)
     cluster = Hash.new
 
@@ -58,7 +75,11 @@ class Stackadmin
     cluster
   end
 
-  # TODO: It never seems to hit "Marked #{patch} as patched for #{k}"
+  # Audits the installation status of each patch listed in the manifest
+  #
+  # @param (see #parse_version)
+  # @todo It never seems to hit "Marked #{patch} as patched for #{k}"
+  # @todo I don't see how this catches a 'no patches available' state
   def parse_patch_status(ssh)
     # Initialize 'patched' hash for each cluster node
     @nodes.each_value do |node|
@@ -85,6 +106,15 @@ class Stackadmin
     end
   end
 
+  # Parses `kato patch status` into a hash
+  #
+  # @param status [String] the output of `kato patch status`
+  # @return [Hash] list of uninstalled patches with list of nodes
+  # @example Returned Hash
+  #          {
+  #            'patch1' => ['127.0.0.1', '171.234.56.78'],
+  #            'patch2' => ['127.0.0.1']
+  #          }
   def hashify_patch_status(status)
     patches = Hash.new
 
@@ -108,6 +138,11 @@ class Stackadmin
     patches
   end
 
+  # Strips the header info from the output of `kato patch status`
+  #
+  # @param (see #hashify_patch_status)
+  # @return [String] status sans header info
+  # @raise [InvalidPatchStatus] if the given status is invalid
   def strip_header(status)
     log 'Stripping header'
 
@@ -127,6 +162,11 @@ class Stackadmin
     s.join("\n")
   end
 
+  # Strips the footer info from the output of `kato patch status`
+  #
+  # @param (see #hashify_patch_status)
+  # @return [String] status sans footer info
+  # @raise (see #strip_header)
   def strip_footer(status)
     log 'Stripping footer'
 

data/lib/stackadmin/base.rb

@@ -3,20 +3,62 @@
 require 'json'
 require 'open-uri'
 
+# Core class of the Stackadmin gem
+# @!attribute [r] id
+#   @return [String] the hostname/FQDN/IP address of the core Stackato node
+# @!attribute [r] version
+#   @return [String] the version of Stackato installed on the node
+# @!attribute [r] license
+#   @return [Hash] the details of the Stackato license installed on the node
+#   @example Returned Hash
+#            {
+#              'organization' => 'org',
+#              'serial' => 'S0F1E2D3C4D5',
+#              'type' => 'paid',
+#              'memory_limit' => 10,
+#              'expiration' => '2014-12-31'
+#            }
+# @!attribute [r] nodes
+#   @return [Hash] the details of each node in the Stackato cluster
+#   @example Returned Hash
+#            {
+#              '127.0.0.1' => {
+#                roles: ['base', 'core']
+#              },
+#              '171.234.56.78' => {
+#                roles: ['base', 'dea']
+#              }
+#            }
+# @!attribute [r] fresh
+#   @return [Boolean] whether the available node data is from a fresh audit
 class Stackadmin
   attr_reader :id, :version, :license, :nodes, :fresh
 
+  # Initializes a new Stackadmin object
+  # @param target [String] hostname/FQDN/IP address of the target node
+  # @param port [Fixnum] port used to SSH into the target node
+  # @param debug [Boolean] toggles display of debug information
+  # @param yml_file [String, nil] pre-populated YAML file to pull node information from
+  # @return [Stackadmin] new, populated object
+  # @todo All paramaters, -target, should be in an opt[] hash
   def initialize(target, port = 22, debug = false, yml_file = nil)
     @port = port
     @debug = debug
     yml_file ? parse_yaml(target, yml_file) : audit(target)
   end
 
+  # Refresh object data with a fresh audit
+  # @param target [String, nil] optional hostname/FQDN/IP address of the target node
+  # @todo Probably unneccessary? Deprecate?
   def refresh(target = nil)
     @id ||= target
     audit
   end
 
+  # Parse through an SSH config to find possible Stackato hostnames
+  # @param ssh_config [String] path to the SSH config file
+  # @param filter [Array<String>] list of regex strings to filter out of found hostnames
+  # @return [Array<String>] (optionally filtered) list of Stackato hostnames found
   def self.find_instances(ssh_config = '~/.ssh/config', filter = [])
     instances = IO.read(File.expand_path(ssh_config))
                   .scan(/^\s*Host (.*stackato.*)/)
@@ -25,6 +67,9 @@ class Stackadmin
     instances
   end
 
+  # Retrieves patch manifest
+  # @param uri [String, nil] path to the manifest.json
+  # @return [Hash] the patch manifest
   def manifest(uri = nil)
     unless @manifest
       uri ||= "https://get.stackato.com/kato-patch/#{@version}/manifest.json"
@@ -36,6 +81,9 @@ class Stackadmin
 
   private
 
+  # Outputs formatted debug messages to stderr
+  # @param msg [String] debug message to output
+  # @return [String] formatted debug message
   def log(msg)
     $stderr.puts ">> #{msg}" if @debug
   end

data/lib/stackadmin/exceptions.rb

@@ -1,16 +1,29 @@
 class Stackadmin
+  # A general exception class, to act as the ancestor to all other
+  # Stackadmin exception classes.
   class Exception < StandardError
   end
 
+  # This exception is raised when the target node
+  # is not found in the provided YAML file
   class YAMLTargetNotFound < Stackadmin::Exception
   end
 
+  # This exception is raised when the output of a
+  # `kato patch status` call does not follow the
+  # expected template
   class InvalidPatchStatus < Stackadmin::Exception
   end
 
+  # This exception is raised when an invalid flag/option
+  # is used (or an invalid combination of flags/options)
+  # in a `kato` subcommand
   class InvalidFlags < Stackadmin::Exception
   end
 
+  # This exception is raised when a `kato` subcommand
+  # is called that does not follow the subcommand's
+  # prototype
   class InvalidCommand < Stackadmin::Exception
   end
 end

data/lib/stackadmin/net-ssh.rb

@@ -2,15 +2,32 @@
 
 require 'net/ssh'
 
-# Grab exit codes from remote commands
-# Yanked this from http://stackoverflow.com/a/13436242
+# @see http://net-ssh.github.io/net-ssh/classes/Net/SSH/Connection/Session.html Class Net::SSH::Connection::Session docs
 class Net::SSH::Connection::Session
+  # This exception is raised when the ssh call
+  # returns a non-zero exit code
   class CommandFailed < Net::SSH::Exception
   end
 
+  # This exception is raised when the ssh call
+  # is unable to execute
   class CommandExecutionFailed < Net::SSH::Exception
   end
 
+  # A convenience method for executing a command and interacting with it.
+  # @see http://net-ssh.github.io/net-ssh/classes/Net/SSH/Connection/Session.html#method-i-exec-21 Net::SSH::Connection::Session::exec! docs
+  # @see http://stackoverflow.com/a/13436242  Yanked from Stack Overflow
+  # @param command [String] command to execute over the SSH connection
+  # @raise [CommandExecutionFailed] if the command was unable to execute
+  # @raise [CommandFailed] if the command returns a non-zero exit code
+  # @return [Hash] A hash containing the STDOUT, STDERR, exit code & exit signal returned by the command
+  # @example Returned Hash
+  #          {
+  #            stdout: "Distributor ID:\tUbuntu\nDescription:\tUbuntu 12.04.5 LTS\nRelease:\t12.04\nCodename:\tprecise\n",
+  #            stderr: "No LSB modules are available.\n",
+  #            exit_code: 0,
+  #            exit_signal: nil
+  #          }
   def exec_sc!(command)
     stdout_data, stderr_data = '', ''
     exit_code, exit_signal = nil, nil

data/lib/stackadmin/patch.rb

@@ -6,8 +6,27 @@ require_relative 'exceptions'
 require_relative 'audit'
 
 class Stackadmin
-  # Returns hash of hashes: { node1: { installed: [patch1], not_installed: [patch2] }, etc }
-  # TODO: DRY this with ::mark! & ::reinstall! & ::revert!
+  # Installs patch(es) to the targeted Stackato cluster
+  # @param patches [String, Array<String>] the name of the patch (or list of patch names) to install
+  # @param node [nil, String] limit command to this node (given as an IP address)
+  # @param local [Boolean] limit command to the currently targeted Stackadmin node
+  # @param restart [Boolean] set to allow the target node's services to restart after a successful patch install
+  # @param force_update [Boolean] force an update to the patch manifest before installing any patches
+  # @param manifest_file [nil, String] execute the command with this manifest file
+  # @return [Hash] hash of hashes indicating the success status of each patch install to each node
+  # @example Returned Hash
+  #          {
+  #            '127.0.0.1' => {
+  #              installed: ['patch1', 'patch3'],
+  #              not_installed: ['patch2']
+  #            },
+  #            '171.234.56.78' => {
+  #              installed: ['patch1', 'patch2', 'patch3'],
+  #              not_installed: []
+  #            }
+  #          }
+  # @todo DRY this with ::mark! & ::reinstall! & ::revert!
+  # @todo (see #reset!)
   def install!(patches = [], node = nil, local = false, restart = true, force_update = false, manifest_file = nil)
     status = Hash.new
     output = patch('install', patches, node: node, local: local, no_restart: !restart, force_update: force_update, manifest: manifest_file)
@@ -18,8 +37,6 @@ class Stackadmin
       p.gsub!(/\e\[\d+m/, '')    # Strip ASCII color
 
       p.scan(/^Failed installing update (.+?) on (.+?)\.$/).each do |fp|
-        # fp = Array of failed patches
-        # e.g. [["patch1-name", "node1-ip"], ["patch2-name", "node2-ip"]]
         status[fp[1]] = {
           installed: [],
           not_installed: []
@@ -29,7 +46,6 @@ class Stackadmin
       end
 
       p.scan(/^Successfully installed update (.+?) on (.+?)\.$/).each do |sp|
-        # sp = Array of successful patches. See fp example above
         status[sp[1]] = {
           installed: [],
           not_installed: []
@@ -42,11 +58,22 @@ class Stackadmin
     status
   end
 
+  # Marks all of the targeted Stackato cluster's patch updates as uninstalled
+  # @param node [nil, String] limit command to this node (given as an IP address)
+  # @param local [Boolean] limit command to the currently targeted Stackadmin node
+  # @return [Boolean] whether or not the reset was successfully executed
+  # @todo collapse args into opt{}
   def reset!(node = nil, local = false)
     output = patch('reset', [], node: node, local: local)
     output[0][:stdout] =~ /^Updates state reset.$/ ? true : false
   end
 
+  # Updates the patch manifest for the targeted Stackato cluster
+  # @param node [nil, String] limit command to this node (given as an IP address)
+  # @param local [Boolean] limit command to the currently targeted Stackadmin node
+  # @param manifest_file [nil, String] execute the command with this manifest file
+  # @return [Boolean] whether or not the manifest was successfully updated
+  # @todo collapse args into opt{}
   def update!(node = nil, local = false, manifest_file = nil)
     output = v3_action_check('update') do
                patch('update', [], node: node, local: local, manifest: manifest_file)
@@ -55,8 +82,20 @@ class Stackadmin
     output[0][:stdout] =~ /^done!$/ ? true : false
   end
 
+  # Marks patch(es) as installed or uninstalled on the targeted Stackato cluster
+  # @param patches [String, Array<String>] the name of the patch (or list of patch names) to mark
+  # @param mark_installed [Boolean] toggle marking as installed/uninstalled (true/false)
+  # @param node [nil, String] limit command to this node (given as an IP address)
+  # @param local [Boolean] limit command to the currently targeted Stackadmin node
+  # @return [Hash] hash of hashes listing which nodes had which patches successfully marked
+  # @example Returned Hash
+  #          {
+  #            '127.0.0.1' => ['patch1', 'patch2'],
+  #            '171.234.56.78' => ['patch1', 'patch3']
+  #          }
   # Returns hash: { node1: [patch1, patch2], etc }
-  # TODO: DRY this with ::install! & ::reinstall! & ::revert!
+  # @todo DRY this with ::install! & ::reinstall! & ::revert!
+  # @todo (see #reset!)
   def mark!(patches = [], mark_installed = false, node = nil, local = false)
     status = Hash.new
     output = v3_action_check('mark') do
@@ -79,8 +118,12 @@ class Stackadmin
     status
   end
 
-  # Returns hash of hashes: { node1: { installed: [patch1], not_installed: [patch2] }, etc }
-  # TODO: DRY this with ::install! & ::mark! & ::revert!
+  # Reinstalls patch(es) to the targeted Stackato cluster
+  # @param (see #install!)
+  # @return (see #install!)
+  # @example (see #install!)
+  # @todo DRY this with ::install! & ::mark! & ::revert!
+  # @todo (see #reset!)
   def reinstall!(patches = [], node = nil, local = false, restart = true, force_update = false, manifest_file = nil)
     if patches.empty?
       raise InvalidCommand, "kato patch reinstall requires a specific patchname!"
@@ -119,8 +162,24 @@ class Stackadmin
     end
   end
 
-  # Returns hash of hashes: { node1: { reverted: [patch1], not_reverted: [patch2], unable_to_revert: [patch3] }, etc }
-  # TODO: DRY this with ::install! & ::mark!
+  # Revert patch(es) on the targeted Stackato cluster
+  # @param (see #install!)
+  # @return [Hash] hash of hashes indicating whether patches were successfully reverted on each node
+  # @example Returned Hash
+  #          {
+  #            '127.0.0.1' => {
+  #              reverted: [patch1, patch4],
+  #              not_reverted: [patch5],
+  #              unable_to_revert: [patch3]
+  #            },
+  #            '171.234.56.78' => {
+  #              reverted: [patch1, patch2],
+  #              not_reverted: [],
+  #              unable_to_revert: [patch3, patch4, patch5]
+  #            }
+  #          }
+  # @todo DRY this with ::install! & ::mark!
+  # @todo (see #reset!)
   def revert!(patches = [], node = nil, local = false, restart = true, force_update = false, manifest_file = nil)
     status = Hash.new
     output = v3_action_check('revert') do
@@ -161,6 +220,9 @@ class Stackadmin
 
   private
 
+  # Wrapper to throw an InvalidCommand exception on v3-only actions
+  # @param action [String] v3-only action
+  # @raise [InvalidCommand] if the targeted Stackato is not version 3
   def v3_action_check(action)
     if @version.to_i == 3
       yield
@@ -169,14 +231,25 @@ class Stackadmin
     end
   end
 
-  # Args:
-  # - action: string, required
-  # -- subcommand to use for 'kato patch'
-  # - patches: array
-  # -- list of patches to apply with action
-  # -- string accepted, but assumed to denote a single patch
-  # - opts: hash, optional
-  # -- flags/arguments to apply to the kato patch action
+  # Helper method to parse and execute `kato patch` commands
+  # @param action [String] kato patch subcommand to execute
+  # @param patches [String, Array<String>] patch(es) to apply with action
+  # @param opts [Hash] flags/arguments to apply with the action
+  # @option opts [String] :node limit action to this node (given as an IP address)
+  # @option opts [Boolean] :local limit command to the currently targeted Stackadmin node
+  # @option opts [String] :manifest manifest file to use with the action
+  # @option opts [Boolean] :force_update force an update to the patch manifest before executing the action
+  # @option opts [Boolean] :mark_installed true marks the patch(es) as installed, false marks the patch(es) as uninstalled
+  # @option opts [Boolean] :no_restart set to prevent the action from restarting any associated services
+  # @raise [InvalidFlags] if both opts[:local] and opts[:node] are set
+  # @return [Hash] A hash containing the STDOUT, STDERR, exit code & exit signal returned by the action
+  # @example Returned Hash
+  #          {
+  #            stdout: "Updates state reset.\nWARNING: Stackato - no license installed\nUsing 31GB of 4GB (11GB over licensed limit)\nBuy a license: http://www.activestate.com/contact-stackato\n",
+  #            stderr: nil,
+  #            exit_code: 0,
+  #            exit_signal: nil
+  #          }
   def patch(action, patches = [], opts = {})
     raise InvalidFlags, "Can't target both #{opts[:node]} & \"local\"!" if (opts[:node] && opts[:local])
 

data/lib/stackadmin/version.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 
 class Stackadmin
-  VERSION = '0.1.0'
+  # Gem version
+  VERSION = '0.1.1'
 end

data/lib/stackadmin/yaml.rb

@@ -4,6 +4,7 @@ require 'yaml'
 require_relative 'exceptions'
 
 class Stackadmin
+  # @return [String] YAML-formatted target Stackato cluster info
   def to_yaml
     { 'id'      => @id,
       'version' => @version,
@@ -13,6 +14,10 @@ class Stackadmin
 
   private
 
+  # Parses a given YAML file into the current Stackadmin object attributes
+  # @param target [String] the target cluster's 'id'
+  # @param yml_file [String] a path to the YAML file to be parsed
+  # @raise [YAMLTargetNotFound] if given target is not found in the given yml_file
   def parse_yaml(target, yml_file)
     instances = YAML.load(File.read(yml_file))
 

data/stackadmin.gemspec

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stackadmin/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'stackadmin'
+  spec.version       = Stackadmin::VERSION
+  spec.authors       = ['Andres Rojas']
+  spec.email         = ['andres.rojas@mtnsat.com']
+  spec.summary       = 'A helper class for administering Stackato deployments'
+  spec.homepage      = "https://github.com/mtnsat/stackadmin"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'net-ssh'
+  spec.add_dependency 'json'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'minitest-reporters'
+  spec.add_development_dependency 'vagrant-wrapper'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'yard'
+end

data/test/helpers/vagrant.rb

@@ -0,0 +1,31 @@
+# Encoding: utf-8
+
+require 'vagrant-wrapper'
+
+MIN_VAGRANT = '1.5.1'
+VAGRANT = "vagrant --min-ver=#{MIN_VAGRANT}"
+
+class VagrantWrapper
+  def plugin_installed?(plugin)
+    (get_output('plugin list') =~ /^#{plugin} \((\d|\.)+\)$/) ? true : false
+  end
+
+  def install_plugin(plugin)
+    installed = false
+
+    if plugin_installed?(plugin)
+      installed = true
+    else
+      puts "Installing #{plugin}..."
+      output = get_output("plugin install #{plugin}")
+      installed = true if output =~ /^Installed the plugin '#{plugin} \((\d|\.)+\)'!$/
+    end
+
+    puts "#{plugin} installed!" if installed
+    installed
+  end
+end
+
+def missing_aws_creds
+  %w( AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY ) - ENV.keys
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stackadmin
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Andres Rojas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-23 00:00:00.000000000 Z
+date: 2015-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-ssh
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: vagrant
+  name: vagrant-wrapper
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -81,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: vagrant-s3auth
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -95,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -116,6 +116,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- CHANGELOG
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -128,7 +129,9 @@ files:
 - lib/stackadmin/patch.rb
 - lib/stackadmin/version.rb
 - lib/stackadmin/yaml.rb
+- stackadmin.gemspec
 - test/Vagrantfile
+- test/helpers/vagrant.rb
 - test/stackadmin_test.rb
 homepage: https://github.com/mtnsat/stackadmin
 licenses: []
@@ -155,4 +158,6 @@ specification_version: 4
 summary: A helper class for administering Stackato deployments
 test_files:
 - test/Vagrantfile
+- test/helpers/vagrant.rb
 - test/stackadmin_test.rb
+has_rdoc: