cloudstack_client

A CloudStack API client written in Ruby.

Installation

Install the cloudstack_client gem:

$ gem install cloudstack_client

Features

• Access to the whole CloudStack-API from Ruby
• Interactive console for playing with the CloudStack API: cloudstack_client console
• Dynamically builds API methods based on the listApis function of CloudStack
• Command names are converted to match Ruby naming conventions (i.e. ListVirtualMachines becomes list_virtual_machines)
• Accepts Ruby Hash arguments passed to commands as options (i.e. list_all: true becomes listall=true)
• Assure all required arguments are passed
• Removes unsupported arguments and arguments with nil values from commands

Usage

Basic usage

require"cloudstack_client"cs=CloudstackClient::Client.new("https://cloudstack.local/client/api","API_KEY","SECRET_KEY")cs.list_virtual_machines(state: "running").eachdo |vm|
putsvm["name"]end

Advanced Options

Load API definition file from an alternative path and set the version:

cs=CloudstackClient::Client.new("https://cloudstack.local/client/api","API_KEY","SECRET_KEY",{api_path: "~/cloudstack",api_version: "4.15"})

...or load the API definition directly from a file:

cs=CloudstackClient::Client.new("https://cloudstack.local/client/api","API_KEY","API_SECRET",{api_file: "~/cloudstack/4.15.json.gz"})

Pagination and Response Options

When working with paginated responses, you can include the total count in the API response:

# Get paginated results with count informationvms=cs.list_virtual_machines({page: 1,pagesize: 10},{include_count: true})total_count=vms[:count]items=vms[:virtualmachine]# Default behavior (without count)vms=cs.list_virtual_machines(page: 1,pagesize: 10)# Returns just the items array

Using the configuration module

The configuration module of CloudstackClient makes it easy to load CloudStack API settings from configuration files.

Example

require"cloudstack_client"require"cloudstack_client/configuration"# looks for ~/.cloudstack.yml per defaultconfig=CloudstackClient::Configuration.loadcs=CloudstackClient::Client.new(config[:url],config[:api_key],config[:secret_key])

Configuration files

Configuration files support multiple environments (i.e. ~/.cloudstack.yml):

# default environment:default: production# production environmentproduction:
:url: "https://my-cloudstack-server/client/api/":api_key: "cloudstack-api-key":secret_key: "cloudstack-api-secret"# test environmenttest:
:url: "http://my-cloudstack-testserver/client/api/":api_key: "cloudstack-api-key":secret_key: "cloudstack-api-secret"

Configuration options

You can pass options as 4th argument in CloudstackClient::Client.new. All its keys are optional.

options={symbolize_keys: true,# pass symbolize_names: true in JSON#parse for Cloudstack responses, default: falsehost: 'localhost',# custom host header to be used in Net::Http. May be useful when Cloudstack is set up locally via docker (i.e. Cloudstack-simulator), default: parsed from config[:url] via Net::Httpread_timeout: 10,# timeout in seconds of a connection to the Cloudstack, default: 60request_retries: 3# number of attempts for HTTP requests before raising a ConnectionError, default: 1 (no retries). Uses incremental back-off between attempts.}cs=CloudstackClient::Client.new(config[:url],config[:api_key],config[:secret_key],options)

For a single call you can override defaults on the second hash (client options), without changing the client instance:

cs.deploy_virtual_machine({zoneid: "...",serviceofferingid: "...",templateid: "..."},async_timeout: 600,async_poll_interval: 5)

Interactive Console

cloudstack_client comes with an interactive console.

Example

$ cloudstack_client console -e prod
prod >> list_virtual_machines

Development

Generate or update API definitions

New API definitions can be generated using the list_apis command.

Example

# running against a CloudStack 4.15 API endpoint:
$ cloudstack_client list_apis > data/4.15.json
$ gzip data/4.15.json

GitHub Actions

This repository includes GitHub Actions workflows for:

• Running tests and gem build on every push and pull request (CI)
• Publishing the gem to RubyGems when a GitHub Release is published (Release)

To enable publishing, add this repository secret:

• RUBYGEMS_AUTH_TOKEN: your RubyGems API key with push permissions

The release workflow checks that CloudstackClient::VERSION is greater than the latest version on RubyGems before building, then uses the rubygems environment to publish.

References

• Apache CloudStack API documentation

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

Released under the MIT License. See the LICENSE file for further details.