cloudstack-cli

KO | EN

gitlite — search

#javascript #python #react #llm #golang #go #android #rust #linux #macos #nodejs #vue #pytorch #ios

(★ 17)

cloudstack-cli is a CloudStack API command line client written in Ruby

cloudstack-cli Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Cloudstack CLI

[![Gem Version](https://badge.fury.io/rb/cloudstack-cli.png)](http://badge.fury.io/rb/cloudstack-cli)

cloudstack-cli is a [CloudStack](http://cloudstack.apache.org/) API command line client written in Ruby.
cloudstack-cli uses the [cloudstack_client](https://github.com/niwo/cloudstack_client) to talk to the CloudStack API.

## Installation

Install the cloudstack-cli gem:

```bash
$ 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:*

```bash
$ 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:*

```bash
$ 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:

```bash
$ cloudstack-cli environment default [environment-name]
```

*List all environments:*

see `cloudstack-cli help environment` for more options.

Example configuration file:

```yaml
# 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, ~/.bash_profile
eval "$(cloudstack-cli completion --shell=bash)"
```

__Note__: use `~/.bashrc` on Ubuntu

## Usage

*Display the cli help:*

```bash
$ cloudstack-cli help
```

*Help for a specific subcommand and command:*

```bash
$ cloudstack-cli vm help
```

```bash
$ 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:*

```bash
$ 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:*

```bash
$ 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):*

```yaml
---
  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:*

```bash
$ 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:*

```bash
$ 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)

```bash
$ 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)

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

## References

-  [Cloudstack API documentation](http://cloudstack.apache.org/docs/api/)
-  This tool was inspired by the Knife extension for Cloudstack: [knife-cloudstack](https://github.com/CloudStack-extras/knife-cloudstack)

## Test

1. Requires the [cloudstack-simulator](https://hub.docker.com/r/cloudstack/simulator/) docker images running on your local machine
2. You need to add the admin secrets to your local cloudstack environment an make it default
3. Currently you need to create a isolated network named "test-network" manually on the simulator
4. Run `bundle exec rake test`

These specs are integration tests and are not executed in GitHub Actions because they require a local simulator and CloudStack credentials.

## 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 that the gem still loads and builds in CI, 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, verifies the gem loads and builds, 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, and if it already exists the workflow reuses that tag.

The release workflow uses RubyGems trusted publishing via GitHub OIDC, so no RubyGems API key secret is required. The gem must already be configured with this repository as a trusted publisher on RubyGems.org.

Typical release flow:

1. Update `lib/cloudstack-cli/version.rb`.
2. Commit and push the version change.
3. Push to `main`.
4. 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

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](https://raw.github.com/niwo/cloudstack-cli/master/LICENSE.txt) file for further details.

cloudstack-cli

cloudstack-cli Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

cloudstack-cli

cloudstack-cli Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README