Unofficial Ruby CloudStack client

The unofficial CloudStack client for Ruby.

Installation

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

Basic Usage

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'

Features

Idomatic Ruby formatting for names

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]

Handling 'map' parameters

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

Configurable API Version

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'

CloudStack REPL

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",
  ...
>>

Configuration

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'
)

URL

The URL of your CloudStack instance's URL.

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

Or:

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

API path

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'
)

Console path

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'
)

Keys

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'
)

Middleware

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
}

Faraday Middleware

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.

Logging

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
}

SSL and ssl_verify

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
}

Bulk Configuration

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'
}

Contributing

Testing

Running the tests:

$ bundle exec rake

Testing against CloudStack

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.

Coding Style

This project uses Rubocop to enforce code style.

$ bundle exec rubocop

Releasing

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.

Thanks to

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

License

StackerBee is released under the MIT License.