Cloudstack CLI

cloudstack-cli is a CloudStack API command line client written in Ruby. cloudstack-cli uses the cloudstack_client to talk to the CloudStack API.

Installation

Install the cloudstack-cli gem:

$ gem install cloudstack-cli

Setup

Create a cloudstack-cli environment

cloudstack-cli expects to find a configuration file with the API URL and your CloudStack credentials in your home directory named .cloudstack.yml (or .cloudstack-cli.yml). If the file is located elsewhere you can specify the location using the --config-file option.

Create your initial environment, which defines your connection options:

$ cloudstack-cli setup

"cloudstack-cli setup" (or "cloudstack-cli environment add") requires the following options:

The full URL of your CloudStack API, i.e. "https://cloud.local/client/api"
Your API Key (generate it under Accounts > Users if not already available)
Your Secret Key (see above)

Add an additional environment:

$ cloudstack-cli env add production

cloudstack-cli supports multiple environments using the --environment option.

The first environment added is always the default. You can change the default as soon as you have multiple environments:

$ cloudstack-cli environment default [environment-name]

List all environments:

see cloudstack-cli help environment for more options.

Example configuration file:

# default environment
:default: production

# production environment
production:
  :url: "https://my-cloudstack-server/client/api/"
  :api_key: "cloudstack-api-key"
  :secret_key: "cloudstack-api-secret"

# test environment
test:
  :url: "http://my-cloudstack-testserver/client/api/"
  :api_key: "cloudstack-api-key"
  :secret_key: "cloudstack-api-secret"

Shell tab auto-completion

To enable tab auto-completion for cloudstack-cli, add the following lines to your ~/.bash_profile file.

# Bash, ~/.bash_profile
eval "$(cloudstack-cli completion --shell=bash)"

Note: use ~/.bashrc on Ubuntu

Usage

Display the cli help:

$ cloudstack-cli help

Help for a specific subcommand and command:

$ cloudstack-cli vm help

$ cloudstack-cli vm help list

Example: Bootstrapping a server

Bootstraps a server using a template and creating port-forwarding rules for port 22 and 80:

$ cloudstack-cli server create web-01 --template CentOS-7.5-x64 --zone DC1 --offering 2cpu_2gb --port-rules :22 :80

Example: Run any custom API command

Run the "listAlerts" command against the CloudStack API with an argument of type=8:

$ cloudstack-cli command listAlerts type=8

Example: Creating a complete stack of servers

CloudStack CLI does support stack files in YAML or JSON.

An example stackfile could look like this (my_stackfile.yml):

---
  name: "web_stack-a"
  description: "Web Application Stack"
  version: "1.0"
  zone: "DC-ZRH-1"
  group: "my_web_stack"
  keypair: "mykeypair"
  servers:
    - name: "web-d1, web-d2"
      description: "web node"
      template: "CentOS-7-x64"
      offering: "1cpu_1gb"
      networks: "server_network"
      port_rules: ":80, :443"
    - name: "db-01"
      description: "PostgreSQL Master"
      iso: "CentOS-7-x64"
      disk_offering: "Perf Storage"
      disk_size: "5"
      offering: "2cpu_4gb"
      ip_network_list:
        - name: FrontendNetwork
          ip: 10.101.64.42
        - name: BackendNetwork
          ip: 10.102.1.11

Create the stack of servers from the definition above:

$ cloudstack-cli stack create my_stackfile.yml

Hint: You can also parse a stackfile from a URI.

The following command destroys a stack using a definition gathered from a stackfile lying on a Github repository:

$ cloudstack-cli stack destroy https://raw.githubusercontent.com/niwo/cloudstack-cli/master/test/stack_example.json
Destroy the following servers web-001, web-002, db-001? [y/N]: y
Destroy server web-001 : job completed
Destroy server web-002 : job completed
Destroy server db-001 : /
Completed: 2/3 (15.4s)

Example: Sort computing offerings

Sort all computing offerings by CPU and Memory grouped by domain: (root admin privileges required)

$ cloudstack-cli compute_offer sort

Example: Stop all backup routers of a given project

Stop all virtual routers of project named Demo (you could filter by zone too): (this command is helpful if you have to deploy new major release of CloudStack when using redundant routers)

$ cloudstack-cli router list --project Demo --status running --redundant-state BACKUP --command STOP

References

Cloudstack API documentation
This tool was inspired by the Knife extension for Cloudstack: knife-cloudstack

Test

Requires the cloudstack-simulator docker images running on your local machine
You need to add the admin secrets to your local cloudstack environment an make it default
Currently you need to create a isolated network named "test-network" manually on the simulator
Run bundle exec rake test

Automation

GitHub Actions are configured for dependency maintenance and RubyGems releases.

Bundle updates

The Update bundle workflow runs monthly and can also be started manually from the Actions tab. It runs bundle update, verifies the test suite, and opens a pull request with the updated lockfile.

Releases

The Release gem workflow publishes to RubyGems when a tag like v1.6.12 is pushed. It also runs when lib/cloudstack-cli/version.rb changes on main, creates the matching tag automatically, and publishes that version. You can also trigger it manually from the Actions tab with a release tag like v1.6.12; if the tag does not exist yet, the workflow creates it from the selected branch before publishing.

Add the RUBYGEMS_API_KEY repository secret before using the release workflow.

Typical release flow:

Update lib/cloudstack-cli/version.rb.
Commit and push the version change.
Push to main.
GitHub Actions creates the matching tag, verifies the tag matches the gem version, and pushes the release to RubyGems.

If you prefer, you can still create and push the matching tag yourself, for example git tag v1.6.12 && git push origin v1.6.12.

Contributing

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

License

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