A Ruby library for working with the OnApp REST API
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
squall.gemspec

README.md

Squall Squall Build Status

A Ruby library for working with the OnApp REST API.

Squall has been tested on MRI versions 1.9.3, 2.0.0, 2.1.2 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:

  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.
  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)
  • Send me a pull request. Bonus points for topic branches.

Copyright

Copyright (c) 2010-2014 Site5.com. See LICENSE for details.