Squall

A Ruby library for working with the OnApp REST API.

Squall has been tested on MRI versions 1.9.2, 1.9.3, 2.0.0 and 1.9-compatible JRuby.

Documentation is available in TomDoc format.

Install

To install Squall using Bundler:

echo "gem 'squall'" >> Gemfile
bundle install

To install Squall globally using RubyGems:

gem install squall

Configuration

You have two main options for configuring Squall.

Directly in a config block:

require 'squall'

Squall.config do |c|
  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 HTTP/Faraday debugging (prints to $stderr)
end

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:

vm = Squall::VirtualMachine.new

params = {
  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
Disks

The following still need to be added:

Billing plans
Currencies
Network interfaces
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 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:

VirtualMachine#change_user currently breaks the parser on an invalid user_id because OnApp returns html instead of JSON
VirtualMachine#create is currently broken in certain cases.
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)
Send me a pull request. Bonus points for topic branches.