- What is cloudmonkey?
What is cloudmonkey?
- Usable as a command line tool and interactive shell
- All commands are lowercase unlike API
- Api Discovery using sync feature, with build time api precaching for failsafe sync
- Raw api execution support
- Auto-completion via double <tab>
- Reverse search using Ctrl+R
- Emacs compatible keybindings
- Pipeable output
- Unix shell execution
- Support to handle async jobs using user defined blocking or non-blocking way
- Tabular or JSON output with filtering of table columns
- Colored output
- Api parameter value completion (based on predication, fuzzy results may fail sometimes)
cloudmonkey requires Python 2.5 or above and has following dependencies:
Platform independent installation
For installing any Python package, pip is recommended: http://www.pip-installer.org/en/latest/installing.html
Thought a clean upgrade is recommended:
RHEL/CentOS 6.x (internet access required for python eggs repository)
or if pip available (pip is recommended)
Or, if pip is not available
Building from source code withing source code
cloudmonkey is moved to a separate git repo
more info @ https://git-wip-us.apache.org/repos/asf?p=cloudstack.git;a=commit;h=6f84e74a68d78705a06fe58f7927f42f61453a16
cloudmonkey reads configuration from ~/.cloudmonkey/config which is it's config file in user's home directory/.cloudmonkey.
Further it logs in ~/.cloudmonkey/log, stores history in ~/.cloudmonkey/history and caches discovered apis in ~/.cloudmonkey/cache. Only the log and history files can be custom paths and can be configured by setting appropriate file paths in ~/.cloudmonkey/config or by command:
The following configuration parameters can be configured by using the 'set' command in cloudmonkey:
IP or resolvable domain of management server
Api server port, 8080 is encouraged over 8096
Specifies http or https
Specifies the absolute path to the api on the specified host
Timeout interval for polling async commands
User api key
User secret key
Enable coloured output, set to false to disable
Line based, JSON, or tabular output, set to default or json or table
Poll for async commands, making it false will cause cloudmonkey to return jobid
Tries to predict api for listing a parameter value for an api, experimental may fail
First set your host, port, apikey and secretkey using set. Api and Secret keys can be created via CloudStack management server UI, Accounts->Users->Generate keys.
Make sure your management server is running, discover and sync/pull latest apis:
The sync command in cloudmonkey pull a list of apis which are accessible to your user role, along with help docs etc. and stores the cache in ~/.cloudmonkey/cache. This allows cloudmonkey to be adaptable to changes in mgmt server, so in case the sysadmin enables a plugin such as Nicira NVP for that user role, the users can get those changes. New verbs and grammar (DSL) rules are created on the fly. A failsafe precache is bundled with the distribution but users are
Note: This features requires ApiDiscovery plugin to be enabled at the management server and it is enabled by default starting ACS 4.1 version.
Try autocompletion using tabbing:
Help for any command can be obtained using help <cmd> or ?<cmd> or <cmd> --help or <cmd> -h, examples:
A typical help doc for an api will list all available acceptable arguments and required arguments.
Example help for listUsers api:
You may enable tabular listing and even choose set of column fields, this allows you to create your own field using the filter param which takes in comma separated argument. If argument has a space, put them under double quotes. The create table will have the same sequence of field filters provided. If your present cli does not have this, pl. upgrade cloudmonkey: pip install --upgrade cloudmonkey
To enable tabular output:
Tabular output comes with filtering, using filter parameter you can ask cloudmonkey to filter particular columns (like select field of mysql).
JSON output formats cloudmonkey's output into pretty generated JSON documents. Filtering may also be used to limit the result set. Even with filtering, a valid JSON document is generated and may be saved into an external file and processed with your favorite programming language. If your present cli does not have this, pl. upgrade cloudmonkey: pip install --upgrade cloudmonkey
To enable json output:
Emacs style key handling
Ctrl+a (start of the line)
Ctrl+e (end of the line)
Ctlr+w (remove one word from back)
Ctrl+u (remove whole line) etc.
Ctrl+R etc. If it does not work and also any issue with tab completion it's probably a readline issue on your env. If autocompletion using tabs does not work for you, pl. open an issue on jira, issues.a.o
By default cloudmonkey logs in ~/.cloudmonkey_log which can be changed using the set command:
One can tail the log to keep track on what's happening:
Using as a command line tool
Use cloudmonkey as a command line tool, by passing args to cloudmonkey. Example:
It can also take in list of commands from a file and interpret them, for example:
The follow example illustrates how one can use cloudmonkey to automate their deployments, this one deploys a basic zone:
Arguments can be passed to an api command using the syntax; <cmd> <verb> key1=value1 etc.
By default cloudmonkey's lexical parser parses like shlex and split by spaces.
If values have spaces, one can put them under quotes, like:
Some api accept array or maps as their arguments, in that case use arg0.key=value syntax. For example, while creating network offering:
Text processing using pipes
Text processing is very easy, one can pipe the data and call their favourite text processors, be it awk, sed or grep.
Automation using shell
Automation can be done using shell or ! followed by shell commands. For example:
For example if one has to create 100 users, one can execute cloudmonkey with args in a loop:
Raw API execution
Use the special command api to send a raw api. It does not do autocompletion and assumes the user knows what he's trying to do.
In latest version, we can directly call a raw api on the shell with parameters, example:
Async Job execution
There are two kinds of apis in CloudStack, one are blocking or synchronous and other one is non-blocking or asynchronous. By default for async apis like deploying a vm ec. are polled by cloudmonkey, one can set cloudmonkey not to poll or wait till the api is finished using:
This causes an async command in cloudmonkey to return a jobid which can be used to poll the completion of that command. This is particularly useful if one wants to starts a lot of VMs without having to wait for the commands to complete. The job can be polled using query async job command, like:
A fuzzy implementation of parameter completion for an api is an experimental feature (a full proof feature would require annotations on each api cmd), this lets user complete a param on tabbing. It can be enabled by setting paramcompletion to true. At present it only works for only those params which accept a uuid.
0. Unicode support
1. Bash/zsh completion (example: https://github.com/bobthecow/git-flow-completion/)
cloudmonkey was named after the beloved mascot of Apache CloudStack.
Author: The Apache CloudStack Team <email@example.com>
Maintainer: Rohit Yadav <firstname.lastname@example.org>