squall 1.0.2 → 1.1.0

data/.gitignore

@@ -3,8 +3,11 @@ pkg/*
 .bundle
 .idea
 *.swp
+*.rbc
 test.rb
 *~
 coverage/
 doc/
 TODO
+Gemfile.lock
+

data/.rbenv-version

@@ -0,0 +1 @@
+1.9.2-p290

data/.rspec

@@ -1,2 +1,2 @@
---format documentation
+--format p
 --color

data/.rvmrc

@@ -1 +1,41 @@
-rvm 1.8.7@squall
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="ruby-1.8.7-p334@squall"
+
+#
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficicent compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+
+  if [[ -s ".rvm/hooks/after_use" ]]
+  then
+    . ".rvm/hooks/after_use"
+  fi
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  if ! rvm --create  "$environment_id"
+  then
+    echo "Failed to create RVM environment ''."
+  fi
+fi
+
+#
+# If you use an RVM gemset file to install a list of gems (*.gems), you can have
+# it be automatically loaded. Uncomment the following and adjust the filename if
+# necessary.
+#
+# filename=".gems"
+# if [[ -s "$filename" ]] ; then
+#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+# fi
+

data/.travis.yml

@@ -1,7 +1,17 @@
-script: "rake spec"
+language: ruby
+script: "bundle exec rake spec"
+notifications:
+  email:
+    recipients:
+      - engineering@internal.site5.com
+    on_success: never
+    on_failure: always
 rvm:
   - 1.8.7
   - 1.9.2
+  - 1.9.3
   - ree
-  - rbx
-  - jruby
+  - rbx-head
+  - rbx-18mode
+  - jruby-18mode
+  - jruby-19mode

data/README.md

@@ -1,69 +1,164 @@
-Squall
-=======
-[![Build Status](http://travis-ci.org/site5/squall.png)](http://travis-ci.org/site5/squall)
+Squall [![Squall Build Status][Build Icon]][Build Status]
+=========================================================
 
+A Ruby library for working with the [OnApp REST API][].
 
-A Ruby library for working with the OnApp REST API
+Squall has been tested on MRI 1.8.7, MRI 1.9.2, MRI 1.9.3 Preview 1,
+Rubinius 2.0.0pre, and JRuby 1.6.2.
 
-[RDoc](http://rdoc.info/github/site5/squall/master/frames)
+Documentation is available in [RDoc][] format.
 
-Confirmed to work with ruby 1.8.7, 1.9.2, Rubinis, REE and JRuby 1.6.0 with OnApp 2.1
+[Build Status]: http://travis-ci.org/site5/squall
+[Build Icon]: https://secure.travis-ci.org/site5/squall.png?branch=master
+[OnApp REST API]: https://help.onapp.com/manual.php?m=2
+[RDoc]: http://rdoc.info/github/site5/squall/master/frames
 
 Install
 -------
 
     gem install squall
+    bundle install
 
+Configuration
+-------------
 
-Usage
------
+You have two main options for configuring Squall.
 
-Configure
+Directly in a config block:
 
     require 'squall'
 
     Squall.config do |c|
-      c.base_uri 'https://onappurl.com'
-      c.username 'username'
-      c.password 'topsecret'
+      c.base_uri 'https://onappurl.com' # Root level URI for OnApp instance
+      c.username 'username' # OnApp username
+      c.password 'topsecret' # OnApp password
+      c.debug true # Toggle HTTParty debugging (prints to $stderr)
     end
 
-Show the info for a VM
+Squall can load configuration from a yaml file:
+
+    # .squall.yml
+    base_uri: 'https://onappurl.com'
+    username: 'username'
+    password: 'topsecret'
+    debug: false
+
+To load it (by default it assumes ~/.squall.yml):
+
+    Squall.config_file(/[path]/[to]/.squall.yml)
+
+It is also possible to change individual configuration settings on the fly.
+
+    Squall.configuration.debug(true)
+
+Note: you will need to re-instantiate all modules after changing Squall's configuration.
+
+Usage
+-----
+
+Show the info for a VM:
 
     vm = Squall::VirtualMachine.new
     vm.show 1
 
-
-Create a new VM
+Create a new VM:
 
     vm = Squall::VirtualMachine.new
 
     params = {
-      :label => 'testmachine', 
-      :hypervisor_id => 5,
-      :hostname => 'testmachine', 
-      :memory => 512, 
-      :cpus => 1,
-      :cpu_shares => 10, 
-      :primary_disk_size => 10
+      :label             => 'testmachine',
+      :hypervisor_id     => 5,
+      :hostname          => 'testmachine',
+      :memory            => 512,
+      :cpus              => 1,
+      :cpu_shares        => 10,
+      :primary_disk_size => 10,
+      :template_id       => 1
     }
 
     vm.create params
 
+Supported Methods
+-----------------
+
+This gem partially implements the OnApp API v2.3.
+
+The following OnApp modules have been added:
+
+* Data store zones
+* Firewall rules
+* Hypervisors
+* Hypervisor zones
+* IP addresses
+* IP address joins
+* Networks
+* Network zones
+* Users
+* User groups
+* Roles
+* Statistics
+* Templates
+* Transactions
+* Virtual machines
+* Whitelists
+
+The following still need to be added:
+
+* Billing plans
+* Currencies
+* Network interfaces
+* Disks
+* Template groups
+* Software licenses
+* Resolvers
+* VM autoscaling
+* Load Balancers
+* CDN edge servers
+* CDN resources
+* CDN edge groups
+* Backups
+* Autobackup Presets
+* Schedules
+* SSH keys
+* Alerts
+* Logs
+* System configuration
+
+Tests
+-----
+
+Squall uses rspec for tests. To run:
 
+    bundle exec rake # Runs all tests
+    bundle exec rspec spec/squall/[module]_spec.rb # Runs tests for a specific module
+
+Squall uses [VCR](https://github.com/myronmarston/vcr) to cache server
+responses to test against. To test via live http connections, pass RERECORD=1
+into test command. NOTE: since OnApp does not currently support a test
+environment this is not recommended unless you know what you're doing, as it
+will destroy live data!
+
+Known issues:
+
+1. VirtualMachine#change_user currently breaks the parser on an invalid
+   user_id  because OnApp returns html instead of JSON
+2. VirtualMachine#create is currently broken in certain cases.  See
+   <https://help.onapp.com/kb_article.php?s=0b397f5b851334cea54da9ddd829bf5f&ref=8181-TYFH-8069>
+3. FirewallRule#edit and #create break the parser by returning invalid JSON
 
 Note on Patches/Pull Requests
-=======
- 
+-----------------------------
+
 * Fork the project.
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a
   future version unintentionally.
 * Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+  (if you want to have your own version, that is fine but bump version in a
+  commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 Copyright
-=======
+---------
 
-Copyright (c) 2011 Site5 LLC. See LICENSE for details.
+Copyright (c) 2012 Site5 LLC. See LICENSE for details.

data/Rakefile

@@ -18,44 +18,15 @@ end
 RSpec::Core::RakeTask.new :spec
 Bundler::GemHelper.install_tasks
 
-desc "Sanitize sensitive info from cassettes"
-task :sanitize_cassettes do
-  yaml = File.join(ENV['HOME'], '.squall.yml')
-  if File.exists?(yaml)
-    config = YAML::load_file(yaml)
-    uri  = URI.parse(config['base_uri']).host
-    user = config['username']
-    pass = config['password']
-
-    path = File.join(File.dirname(__FILE__), 'spec', 'vcr_cassettes')
-    files = Dir.glob("#{path}/**/*.yml")
-    if files.any?
-      files.each do |file|
-        old = File.read(file)
-        # if old.match(/#{uri}|#{user}|#{pass}/)
-          puts "Sanitizing #{file}"
-          old.gsub!(user, 'user')
-          old.gsub!(pass, 'pass')
-          old.gsub!(uri, 'www.example.com')
-          old.gsub!(/_onapp_session=(.*?);/, "_onapp_session=WHAT;")
-          old.gsub!(/- Basic .*/, "- Basic WHAT")
-          File.open(file, 'w') do |f| 
-            f.write old 
-          end 
-        # end 
-      end 
-    else
-      puts "Nothing to sanitize"
-    end 
-  else
-    puts "I can't sanitize without setting up WHM_HASH and WHM_HOST"
-  end 
-end
-
 desc  "Run all specs with rcov"
 RSpec::Core::RakeTask.new(:rcov) do |t|
   t.rcov = true
   t.rcov_opts = %w{--exclude osx\/objc,gems\/,spec\/,features\/}
 end
 
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/squall.rb -I ./lib"
+end
+
 task :default => [:spec]

data/lib/squall/data_store_zone.rb

@@ -0,0 +1,58 @@
+module Squall
+  # OnApp DataStoreZone
+  class DataStoreZone < Base
+    # Returns a list of data store zones
+    def list
+      response = request(:get, "/data_store_zones.json")
+      response.collect { |i| i['data_store_group'] }
+    end
+
+    # Get the details for a data store zone
+    #
+    # ==== Params
+    #
+    # * +id+ - ID of the data store zone
+    def show(id)
+      response = request(:get, "/data_store_zones/#{id}.json")
+      response['data_store_group']
+    end
+
+    # Updates an existing data store zone
+    #
+    # ==== Params
+    #
+    # * +id+ - ID of the data store zone
+    # * +options+ - Params for the data store zone
+    #
+    # ==== Options
+    #
+    # * +label*+ - Label for the data store zone
+    def edit(id, options = {})
+      params.required(:label).validate!(options)
+      response = request(:put, "/data_store_zones/#{id}.json", :query => {:pack => options})
+    end
+
+    # Creates a new DataStoreZone
+    #
+    # ==== Params
+    #
+    # * +options+ - Params for the data store zone
+    #
+    # ==== Options
+    #
+    # * +label*+ - Label for the data store zone
+    def create(options = {})
+      params.required(:label).validate!(options)
+      response = request(:post, "/data_store_zones.json", :query => {:pack => options})
+    end
+
+    # Deletes an existing DataStoreZone
+    #
+    # ==== Params
+    #
+    # * +id+ - ID of the data store zone
+    def delete(id)
+      request(:delete, "/data_store_zones/#{id}.json")
+    end
+  end
+end

data/lib/squall/firewall_rule.rb

@@ -0,0 +1,66 @@
+module Squall
+  # OnApp FirewallRule
+  class FirewallRule < Base
+
+    # Return a list of all firewall rules for a virtual machine
+    #
+    # ==== Params
+    #
+    # * +vm_id*+ - ID of the virtual machine
+    def list(vm_id)
+      response = request(:get, "/virtual_machines/#{vm_id}/firewall_rules.json")
+      response.collect { |firewall_rule| user['firewall_rule'] }
+    end
+
+    # Create a firewall rule for a virtual machine
+    #
+    # ==== Params
+    #
+    # * +vm_id*+ - ID of the virtual machine
+    #
+    # ==== Options
+    #
+    # * +command*+ - DROP or ACCEPT
+    # * +protocol*+ - TCP or UDP
+    # * +network_interface_id*+ - ID of the network interface
+    # * +address+ - IP address or range scope for rule.  Leave blank to apply to all.
+    # * +port+ - Port address for rule
+    #
+    # ==== Example
+    #
+    #   create :command              => "DROP",
+    #          :protocol             => "TCP",
+    #          :network_interface_id => 1
+    def create(vm_id, options={})
+      params.required(:command, :protocol, :network_interface_id).accepts(:address, :port).validate!(options)
+      request(:post, "/virtual_machines/#{vm_id}/firewall_rules.json", default_params(options))
+    end
+
+    # Edit a firewall rule
+    #
+    # ==== Params
+    #
+    # * +vm_id+ - ID of the virtual machine
+    # * +id+ - ID of the firewall rule
+    # * +options+ - Options for the firewall rule.
+    #
+    # ==== Options
+    #
+    # See #create
+    def edit(vm_id, id, options={})
+      params.accepts(:command, :protocol, :network_interface_id, :address, :port).validate!(options)
+      request(:put, "/virtual_machines/#{vm_id}/firewall_rules/#{id}.json", default_params(options))
+    end
+
+    # Delete a firewall rule
+    #
+    # ==== Params
+    #
+    # * +vm_id*+ - ID of the virtual machine
+    # * +id+ - ID of the firewall rule
+    def delete(vm_id, id)
+      request(:delete, "/virtual_machines/#{vm_id}/firewall_rules/#{id}.json")
+    end
+
+  end
+end

data/lib/squall/hypervisor.rb

@@ -2,17 +2,17 @@ module Squall
   # OnApp Hypervisor
   class Hypervisor < Base
 
-    # Returns a list of all Hypervisors
+    # Returns a list of all hypervisors
     def list
       req = request(:get, '/settings/hypervisors.json')
       req.collect { |hv| hv['hypervisor'] }
     end
 
-    # Returns the Hypervisor info as a Hash
+    # Returns the hypervisor info as a hash
     #
-    # ==== Options
+    # ==== Params
     #
-    # * +id+ - The id of the Hypervisor
+    # * +id+ - The id of the hypervisor
     def show(id)
       req = request(:get, "/settings/hypervisors/#{id}.json")
       req.first[1]
@@ -20,41 +20,93 @@ module Squall
 
     # Create a new Hypervisor
     #
+    # ==== Params
+    #
+    # * +options+ - Options for creating the hypervisor
+    #
     # ==== Options
     #
-    # * +options+ - Params for creating the Hypervisor
+    # * +label*+ - Label for the hypervisor
+    # * +ip_address*+ - IP for the hypervisor
+    # * +hypervisor_type*+ - Type of the hypervisor
     #
     # ==== Example
     #
     #   create :label => 'myhv', :ip_address => '127.0.0.1', :hypervisor_type => 'xen'
     def create(options = {})
-      params.required(:label, :ip_address, :hypervisor_type).validate!(options)
+      params.required(:label, :ip_address, :hypervisor_type).accepts(:memory_overhead, :enabled, :hypervisor_group_id, :disable_failover).validate!(options)
       req = request(:post, '/settings/hypervisors.json', default_params(options))
       req.first[1]
     end
 
     # Edit a Hypervisor
     #
-    # ==== Options
+    # ==== Params
     #
+    # * +id*+ - ID of the hypervisor
     # * +options+ - Params for editing the Hypervisor
+    #
+    # ==== Options
+    #
+    # See #create
+    #
     # ==== Example
     #
-    #   edit :label => 'myhv', :ip_address => '127.0.0.1'
+    #   edit 1, :label => 'myhv', :ip_address => '127.0.0.1'
     def edit(id, options ={})
-      params.accepts(:label, :ip_address).validate!(options)
+      params.accepts(:label, :ip_address, :hypervisor_type, :memory_overhead, :enabled, :hypervisor_group_id, :disable_failover).validate!(options)
       request(:put, "/settings/hypervisors/#{id}.json", default_params(options))
     end
 
-    # Reboot a Hypervisor
+    # Reboot a hypervisor
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the hypervisor
     def reboot(id)
       response = request(:get, "/settings/hypervisors/#{id}/rebooting.json")
       response['hypervisor']
     end
 
-    # Delete a Hypervisor
+    # Delete a hypervisor
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the hypervisor
     def delete(id)
       req = request(:delete, "/settings/hypervisors/#{id}.json")
     end
+
+    def virtual_machines(id)
+      response = request(:get, "/settings/hypervisors/#{id}/virtual_machines.json")
+      response.collect { |vm| vm['virtual_machine'] }
+    end
+
+    def data_store_joins(id)
+      response = request(:get, "/settings/hypervisors/#{id}/data_store_joins.json")
+      response.collect { |dsj| dsj['data_store_join'] }
+    end
+
+    def add_data_store_join(id, data_store_id)
+      request(:post, "/settings/hypervisors/#{id}/data_store_joins.json", :query => {:data_store_id => data_store_id})
+    end
+
+    def remove_data_store_join(id, data_store_join_id)
+      request(:delete, "/settings/hypervisors/#{id}/data_store_joins/#{data_store_join_id}.json")
+    end
+
+    def network_joins(id)
+      response = request(:get, "/settings/hypervisors/#{id}/network_joins.json")
+      response.collect { |nj| nj['network_join'] }
+    end
+
+    def add_network_join(id, options)
+      params.required(:network_id, :interface).validate!(options)
+      request(:post, "/settings/hypervisors/#{id}/network_joins.json", :query => {:network_join => options})
+    end
+
+    def remove_network_join(id, network_join_id)
+      request(:delete, "/settings/hypervisors/#{id}/network_joins/#{network_join_id}.json")
+    end
   end
 end