Unofficial Ruby CloudStack client

The unofficial CloudStack client for Ruby.

You can install StackerBee with rubygems:

$ gem install stacker_bee

If you are using Bundler add the following to your Gemfile:

gem 'stacker_bee'

And execute:

$ bundle install

cloud_stack = StackerBee::Client.new(
  url:        'http://localhost:8080',
  api_key:    'MY_API_KEY',
  secret_key: 'MY_SECRET_KEY'
)

cloud_stack.list_virtual_machines state: 'Running'
# => [ { id: '48b91ab4...', displayName: '...', ... },
#      { id: '59c02bc5...', displayName: '...', ... },
#      ... ]

cloud_stack.create_volume name: 'MyVolume'

For example, you can use list_virtual_machines instead of listVirtualMachines and affinity_group_id instead of affinitygroupid (if you want to).

For example:

vm = cloud_stack.list_virtual_machines(affinity_group_id: id).first
puts vm[:iso_display_text]

For any endpoint requiring a map parameter, pass in a hash.

cloud_stack.create_tags tags: { type: 'community' }, ...

This will yield a request with the following query string:

...&tags[0].key=type&tags[0].name=type&tags[0].value=community

By default, StackerBee uses the CloudStack 4.2 API, but it doesn't have to. Use a different API version by setting the api_path configuration option to the path of a JSON file containing the response from your CloudStack instance's listApis command.

StackerBee::Client.api_path = '/path/to/your/listApis/response.json'

Usage:

$ stacker_bee [OPTIONS]

Example:

$ stacker_bee -u http://localhost:8080 -a MY_API_KEY -s MY_SECRET_KEY
StackerBee CloudStack REPL
>> list_virtual_machines state: 'Running'
=> [{"id"=>"48b91ab4-dc23-4e24-bc6f-695d58c91087",
  "name"=>"MyVM",
  "displayname"=>"My VM",
  ...
>>

Configuring a client:

cloud_stack = StackerBee::Client.new(
  url:        'http://localhost:8080',
  api_key:    'API_KEY',
  secret_key: 'SECRET_KEY'
)

All configuration parameters set on the StackerBee::Client class are used as defaults for StackerBee::Client instances.

StackerBee::Client.url = 'http://localhost:8080'

user_client = StackerBee::Client.new(
  api_key:    'USER_API_KEY',
  secret_key: 'USER_SECRET_KEY'
)

root_client = StackerBee::Client.new(
  api_key:    'ROOT_API_KEY',
  secret_key: 'ROOT_SECRET_KEY'
)

The URL of your CloudStack instance's URL.

StackerBee::Client.url = 'http://localhost:8080'

Or:

my_client = StackerBee::Client.new(
  url: 'http://localhost:8080'
)

The path of your CloudStack instance's API URL. Defaults to '/client/api/'.

StackerBee::Client.api_path = '/other-path/client/api'

Or:

my_client = StackerBee::Client.new(
  api_path: '/other-path/client/api'
)

The path of your CloudStack instance's URL for console access. Defaults to '/client/console/'.

StackerBee::Client.console_path = '/other-path/client/console'

Or:

my_client = StackerBee::Client.new(
  console_path: '/other-path/client/console'
)

Your CloudStack credentials, i.e. API key and secret key.

StackerBee::Client.api_key    = 'MY_API_KEY'
StackerBee::Client.secret_key = 'MY_SECRET_KEY'

Or:

my_client = StackerBee::Client.new(
  api_key:    'MY_API_KEY',
  secret_key: 'MY_SECRET_KEY'
)

StackerBee can be configured with middleware. It uses it's own middleware stack to implement some of its functionality.

To add a middleware, use the middlewares configuration option. For example:

class StdoutLoggingMiddleware < StackerBee::Middleware::Base
  def call(env)
    app.call(env)
    p "CloudStack call: #{env.inspect}"
  end
end

class PrependedMiddleware < StackerBee::Middleware::Base
  def call(env)
    app.call(env)
  end
end

StackerBee::Client.configuration = {
  middlewares: ->(builder) do
    # Using `before` places the middleware before the default middlewares
    builder.before PrependedMiddleware

    # Using `use` places the middleware after the default middlewares,
    # but before the request is sent to Faraday
    builder.use StdoutLoggingMiddleware
  end
}

StackerBee is built on Faraday and allows you to add Faraday middleware. Here's an example of adding your own middleware.

StackerBee::Client.configuration = {
  faraday_middlewares: ->(faraday) do
    faraday.use Custom::LoggingMiddleware, Logger.new
    faraday.use Custom::CachingMiddleware, Rails.cache
  end
}

StackerBee itself puts some middlewares on Faraday. Any middlewares you add will be placed after these. If you want your middleware to come as the very first, you can use Faraday's builder like faraday.builder.insert 0, MyMiddleware.

You can configure logging by passing in a logger object that adheres to the standard log4* logging conventions

StackerBee::Client.configuration = {
  logger: my_log4x_logger
}

StackerBee supports using SSL. To do so, use an HTTPS URL. In some deployments, CloudStack's SSL certificates don't match the DNS name that StackerBee will use to access it which will cause certificate validation errors. In these cases, if it's not feasible to fix the certificates (which is recommended) setting ssl_verfiy to false will cause StackerBee to ignore certificate validation errors.

StackerBee::Client.configuration = {
  url:        'https://my-cloudstack-server',
  ssl_verify: false # ignore certificate validation errors
}

The StackerBee::Client class can be configured with multiple options at once.

StackerBee::Client.configuration = {
  url:        'http://localhost:8080',
  api_key:    'API_KEY',
  secret_key: 'MY_SECRET_KEY'
}

Running the tests:

$ bundle exec rake

To interact with a real CloudStack server, instead of the recorded responses:

$ cp config.default.yml config.yml

And edit config.yml, specifying the URL and credentials for your CloudStack server. This file is used by the test suite if it exists, but is ignored by git.

This project uses Rubocop to enforce code style.

$ bundle exec rubocop

To create a release, first bump the version in lib/stacker_bee/version.rb, and commit. Then, build the gem and release it to Rubygems with rake release:

$ rake release
stacker_bee 1.2.3 built to pkg/stacker_bee-1.2.3.gem.
Tagged v1.2.3.
Pushed git commits and tags.
Pushed stacker_bee 1.2.3 to rubygems.org.

We use Bundler's gem tasks to manage releases. See the output of rake -T and Bundler's Rubygems documentation for more information.

• Chip Childers for a reference implementation of a CloudStack client in Ruby

StackerBee is released under the MIT License.