Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
What is cloudmonkey?
Features
Installation
Requirements
Platform independent installation
RHEL/CentOS 6.x (internet access required for python eggs repository)
Ubuntu/Debian
Building from source code
Configuration
Usage
Getting started
Getting help
Management server profiles
Tabular output
JSON output
Filtering output
Emacs style key handling
Reverse Searching
Debug log
Using as a command line tool
Argument passing
Text processing using pipes
Automation using shell
Raw API execution
Async Job execution
Parameter completion
About
What is cloudmonkey?
cloudmonkey is a command line interface (CLI) tool for CloudStack written in Python. cloudmonkey can be use both as an
interactive shell and as a command line tool which simplifies CS configuration and management. It is unofficially distributed by
community maintained distribution at the cheese shop http://pypi.python.org/pypi/cloudmonkey/ as well as within the git repository in
tools/cli/. It can be used with Apache CloudStack 4.0-incubating and above.
Features
Usable as a command line tool and interactive shell
Management server profiles: select, customize and use different server profiles using
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
Unicode support
Api parameter value completion
Installation
Requirements
cloudmonkey requires Python 2.6 or above and has following dependencies:
readline
requests
Pygments
prettytable
argcomplete
To upgrade:
Ubuntu/Debian
Configuration
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:
$ cloudmonkey
> set history_file /usr/share/cloudmonkey_history
> set log_file /var/log/cloudmonkey
[core]
profile = local
asyncblock = true
paramcompletion = true
history_file = /Users/bhaisaab/.cloudmonkey/history
log_file = /Users/bhaisaab/.cloudmonkey/log
cache_file = /Users/bhaisaab/.cloudmonkey/cache
[ui]
color = true
prompt = >
display = default
[local]
url = http://localhost:8080/client/api
username = admin
password = password
apikey =
secretkey =
timeout = 3600
expires = 600
The following configuration parameters can be configured by using the 'set' command in cloudmonkey:
url Management server API url (it should contain full url with protocol, port etc and paths) http://localhost:8080/client/api
timeout Timeout interval for polling async commands 3600
verifysslcert Enables/Disables SSL certification verification when making HTTP calls (per server profile) true
display Line based, JSON, or tabular output, set to default or json or table default
asyncblock Poll for async commands, making it false will cause cloudmonkey to return jobid true
paramcompletion Tries to predict api for listing a parameter value for an api, experimental may fail true
Note: If both username/password and apikey/secretkey are set (i.e. have non-empty values), apikey and secretkey are used while making HTTP
API calls.
Usage
Getting started
By default cloudmonkey will create 'local' server profile when it will start.
First set the management server API url, apikey and secretkey etc.
Api and Secret keys can be created via CloudStack management server UI, Accounts->Users->Generate keys.
One can also use username and password though use of keys is recommended. CloudMonkey first tries to
authenticate using apikey/secret key if provided, then if port specified in the URL is 8096 cloudmonkey
assumes user is trying to use integration port and if both of them don't qualify i.e. keys are not provided and
port is not 8096 we try to authenticate with username and password.
Make sure your management server is running, discover and sync/pull latest apis:
> sync
500 APIs discovered and cached
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.
Getting help
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.
[local]
url = http://localhost:8080/client/api
username = admin
password = password
apikey =
secretkey =
timeout = 3600
expires = 600
To create a new server profile, one can use: set profile <profile-name> and this will create a new server profile
config section in ~/.cloudmonkey/config and use the above default values. Using set command on params
such as url, username, password etc. will set these values for the currently selected profile only. Note: profile
names cannot be whitespace/blank '', core or ui.
Tabular output
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:
Examples:
Tabular output comes with filtering, using filter parameter you can ask cloudmonkey to filter particular columns (like select field of mysql).
JSON output
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:
> set display json
Examples:
Filtering output
CloudMonkey can filter output based on keys. Starting 5.3.0, filter is supported for all display outputs (json, default and table) and autocompletion
works as well.
id = ef33f4a0-e7cf-11e3-a8a4-005056867a67
firstname = admin
lastname = cloud
username = admin
================================================================================
id = d052dfb3-828c-4fa3-9e72-75f4795bb554
firstname =
lastname =
username =
Reverse Searching
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
Debug log
By default cloudmonkey logs in ~/.cloudmonkey_log which can be changed using the set command:
It can also take in list of commands from a file and interpret them, for example:
$ cat file-with-cmds
list users
list zones
$ cloudmonkey < file-with-cmds
The follow example illustrates how one can use cloudmonkey to automate their deployments, this one deploys a basic zone:
#!/bin/bash
cli=cloudmonkey
dns_ext=8.8.8.8
dns_int=10.147.28.6
gw=10.147.28.1
nmask=255.255.255.0
hpvr=XenServer
pod_start=10.147.28.225
pod_end=10.147.28.234
vlan_start=10.147.28.235
vlan_end=10.147.28.254
Argument passing
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:
For example if one has to create 100 users, one can execute cloudmonkey with args in a loop:
In latest version, we can directly call a raw api on the shell with parameters, example:
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:
Parameter completion
Starting 5.3.0 version, parameter implementation works well for api arguments which are of uuid and boolean types. It can be enabled by setting
paramcompletion to true. To automatically find out how to get values for a api arg it uses two heuristics (list apis and most likely related list api) so
it is quite possible there are corner cases where this may fail. Whenever a list api is called or when parameter completion calls a list api in
background, those results (pair of uuid and name strings) are cached by CloudMonkey to speed up rendering. The cache is kept for next 10-15
mins, after which a list api is called again in the background.
Example:
About
cloudmonkey was named after the beloved mascot of Apache CloudStack.
Dev ML: The Apache CloudStack Team <dev@cloudstack.apache.org>
Maintainer: Rohit Yadav <bhaisaab@apache.org>