The unofficial CloudStack client for Ruby.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Unofficial Ruby CloudStack client

Code Climate Dependency Status Build Status Gem Version Coverage Status

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

Basic Usage

cloud_stack =
  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'


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:


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


$ stacker_bee [OPTIONS]


$ 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",
  "displayname"=>"My VM",


Configuring a client:

cloud_stack =
  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 =
  api_key:    'USER_API_KEY',
  secret_key: 'USER_SECRET_KEY'

root_client =
  api_key:    'ROOT_API_KEY',
  secret_key: 'ROOT_SECRET_KEY'


The URL of your CloudStack instance's URL.

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


my_client =
  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'


my_client =
  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'


my_client =
  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'


my_client =
  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)
    p "CloudStack call: #{env.inspect}"

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

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

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,
    faraday.use Custom::CachingMiddleware, Rails.cache

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

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'



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


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

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


StackerBee is released under the MIT License.