cloudstack_api

Ruby library for the CloudStack API. Current version uses CloudStack API version 4.3.0 (API Reference)

Installation

Cloudstack library requires Ruby 1.9.3 or later. To install, add this line to your Gemfile and run bundle install:

gem 'cloudstack_api'

Gem was renamed from cloudstack to cloudstack_api to avoid name conflicts with CloudStack trademark.

Configuration

By default module uses configuration from config/cloudstack.yml file. To generate it run:

rake cloudstack:install

This command generates file config/cloudstack.yml which contains configuration for each environment

default: &default
  api_key: xxxxxxxxx
  secret_key: xxxxxxxxx
  api_url: https://your.domain.com/client/api

production:
  <<: *default

development:
  <<: *default

test:
  <<: *default
  api_mode: test

Fill in api_url, api_key and secret_key for each environment or use default template.

You can configure module at runtime if you need:

Cloudstack.configure do |config|
  config.api_key = 'xxxxx'
  config.secret_key = 'xxxxxx'
  config.api_url = 'https://your.domain.com/client/api'
  config.api_mode = 'test' # don't execute any command, just return signed request
end

or set each configuration option separately:

Cloudstack.config.api_key = 'xxxxxx'

Usage

To use library you need to create an instance of Cloudstack::Api class and call it methods:

@api = Cloudstack::Api.new
@api.execute_command('listVirtualMachines', account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')

Last line returns a result hash:

{
  :count => 1,
  :virtualmachine => [
      {
                 :id => "0e061655-d982-4c2d-810e-6f3aa7d2ccde",
               :name => "cloudvds4509",
        :displayname => "cloudvds4509",
            :account => "myuser",
           :domainid => "1bd9a980-0f11-4892-aa0b-7c434dbd6d1c",
             :domain => "core",
            :created => "2014-08-15T15:35:20+0000",
              :state => "Stopped",
           :haenable => true,
...

or false if an error was occured. All error messages stores in an errors method. errors method is a functionality of ActiveModel::Validations module.

@api.errors.messages

returns:

{:base=>["could not find account user in domain 1bd9a980-0f11-4892-aa0b-7c434dbd6d1c"]}

If you prefer to work with exceptions you can use functions with ! suffix. For example:

begin
  @api = Cloudstack::Api.new
  @api.execute_command!('listVirtualMachines', account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')
rescue Exception => e
  puts e.message  # => could not find account myuser in domain 1bd9a980-0f11-4892-aa0b-7c434dbd6d1c
end

Shortcuts for API commands

For writing more readable code, use API commands shortcuts.

@api.list_virtual_machines(account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')

is the same as:

@api.execute_command('listVirtualMachines', account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')

Shortcuts commands is an underscored API commands. For example command deployVirtualMachine has deploy_virtual_machine shortcut method.

Exception raises methods have shotcuts too. Just add ! suffix to it:

begin
  @api.list_virtual_machines!(account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')
rescue Exception => e
  puts e.message  # => could not find account myuser in domain 1bd9a980-0f11-4892-aa0b-7c434dbd6d1c
end

TODO

• Handle async jobs

• Write documentation!!!