cloudmonkey is a command line interface (CLI) tool written in python that leverages Marvin that provides cloudstackAPI. 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.
cloudmonkey requires Python 2.5 or above and has following dependencies:
readline clint
For installing any Python package, pip is recommended: http://www.pip-installer.org/en/latest/installing.html
$ pip install cloudmonkey
To upgrade:
$ pip install --upgrade cloudmonkey
Thought a clean upgrade is recommended:
$ pip uninstall cloudmonkey $ pip install cloudmonkey
$ yum install python-setuptools $ easy_install cloudmonkey
or if pip available (pip is recommended)
$ pip install cloudmonkey
$ apt get python-setuptools $ easy_install cloudmonkey
or if pip available (pip is recommended)
$ pip install cloudmonkey
$ git clone https://git-wip-us.apache.org/repos/asfgit clone https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git $ mvn clean install -P developer $ cd tools/cli # cloudmonkey-x.x.x.tar.gz will be built in dist $ python setup.py build $ python setup.py install
cloudmonkey gets configuration from ~/.cloudmonkey_config which is it's config file in user's home directory.
Further it logs in ~/.cloudmonkey_log and stores history in ~/.cloudmonkey_history. 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
There are other parameters which can be customized:
Key |
Purpose |
Default |
host |
IP or resolvable domain of management server |
localhost |
port |
Api server port, 8080 is encouraged over 8096 |
8080 |
apikey |
User api key |
"" |
secretkey |
User secret key |
"" |
prompt |
cloudmonkey prompt, default prompt has a UTF-8 char which can be an issue |
🵠cloudmonkey> |
asyncblock |
Poll for async commands, making it false will cause cloudmonkey to return jobid |
true |
timeout |
Timeout interval for polling async commands |
3600 |
color |
Enable coloured output, set to false to disable |
true |
log_file |
Log file |
~/.cloudmonkey_log |
history_file |
History file |
~/.cloudmonkey_history |
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.
> set host 192.168.56.1 > set port 8080 > set apikey <put-your-api-key-for-your-user> > set secretkey <put-your-secret-key-for-your-user> > set prompt mycloudmonkey>
Make sure your management server is running, try out some commands:
> <tab><tab> > list <tab><tab> > list users <tab><tab>
Help for any command can be obtained using help <cmd> or ?<cmd> or <cmd> --help or <cmd> -h, examples:
> help list > help list users > ?list > ?list users > list users --help > list users -h
A typical help doc for an api will list all available acceptable arguments and required arguments.
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 and rest you know
Anything after # is treated as comment and is not processed on the shell.
Use cloudmonkey as a command line tool, by passing args to cloudmonkey. Example:
$ cloudmonkey list users $ cloudmonkey create domain name=mydomain
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 #Put space separated host ips in following host_ips=10.147.28.60 host_user=root host_passwd=password sec_storage=nfs://10.147.28.7/export/home/rohit/secondary prm_storage=nfs://10.147.28.7/export/home/rohit/primary zone_id=`$cli create zone dns1=$dns_ext internaldns1=$dns_int name=MyZone networktype=Basic | grep ^id\ = | awk '{print $3}'` echo "Created zone" $zone_id phy_id=`$cli create physicalnetwork name=phy-network zoneid=$zone_id | grep ^id\ = | awk '{print $3}'` echo "Created physical network" $phy_id $cli add traffictype traffictype=Guest physicalnetworkid=$phy_id echo "Added guest traffic" $cli add traffictype traffictype=Management physicalnetworkid=$phy_id echo "Added mgmt traffic" $cli update physicalnetwork state=Enabled id=$phy_id echo "Enabled physicalnetwork" nsp_id=`$cli list networkserviceproviders name=VirtualRouter physicalnetworkid=$phy_id | grep ^id\ = | awk '{print $3}'` vre_id=`$cli list virtualrouterelements nspid=$nsp_id | grep ^id\ = | awk '{print $3}'` $cli api configureVirtualRouterElement enabled=true id=$vre_id $cli update networkserviceprovider state=Enabled id=$nsp_id echo "Enabled virtual router element and network service provider" nsp_sg_id=`$cli list networkserviceproviders name=SecurityGroupProvider physicalnetworkid=$phy_id | grep ^id\ = | awk '{print $3}'` $cli update networkserviceprovider state=Enabled id=$nsp_sg_id echo "Enabled security group provider" netoff_id=`$cli list networkofferings name=DefaultSharedNetworkOfferingWithSGService | grep ^id\ = | awk '{print $3}'` net_id=`$cli create network zoneid=$zone_id name=guestNetworkForBasicZone displaytext=guestNetworkForBasicZone networkofferingid=$netoff_id | grep ^id\ = | awk '{print $3}'` echo "Created network $net_id for zone" $zone_id pod_id=`$cli create pod name=MyPod zoneid=$zone_id gateway=$gw netmask=$nmask startip=$pod_start endip=$pod_end | grep ^id\ = | awk '{print $3}'` echo "Created pod" $cli create vlaniprange podid=$pod_id networkid=$net_id gateway=$gw netmask=$nmask startip=$vlan_start endip=$vlan_end forvirtualnetwork=false echo "Created IP ranges for instances" cluster_id=`$cli add cluster zoneid=$zone_id hypervisor=$hpvr clustertype=CloudManaged podid=$pod_id clustername=MyCluster | grep ^id\ = | awk '{print $3}'` echo "Created cluster" $cluster_id #Put loop here if more than one for host_ip in $host_ips; do $cli add host zoneid=$zone_id podid=$pod_id clusterid=$cluster_id hypervisor=$hpvr username=$host_user password=$host_passwd url=http://$host_ip; echo "Added host" $host_ip; done; #$cli create storagepool zoneid=$zone_id podid=$pod_id clusterid=$cluster_id name=MyNFSPrimary url=$prm_storage #echo "Added primary storage" $cli add secondarystorage zoneid=$zone_id url=$sec_storage echo "Added secondary storage" $cli update zone allocationstate=Enabled id=$zone_id echo "Basic zone deloyment completed!"
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:
> create project name="my unique name" displaytext="my lengthy description"
Some api accept array or maps as their arguments, in that case use arg0.key=value syntax. For example, while creating network offering:
> create networkoffering supportedservices=Dhcp,Dns serviceproviderlist[0].service=Dhcp serviceproviderlist[0].provider=VirtualRouter serviceproviderlist[1].service=Dns serviceproviderlist[1].provider=VirtualRouter
Text processing is very easy, one can pipe the data and call their favourite text processors, be it awk, sed or grep.
Examples:
> list accounts listall=true | grep ^id\ = > list users | wc -l > list routers | more
Automation can be done using shell or ! followed by shell commands. For example:
> shell ls -lahi > shell whoami > shell ssh root@<ip> > !date > !ping google.com
For example if one has to create 100 users, one can execute cloudmonkey with args in a loop:
> !for((i=0;i<100;i++)); do cloudmonkey create user username=user$i account=admin firstname=user$i lastname=user$i password=password$i email=user$i@domain.org; done;
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.
For example:
> api uploadVolume url=xxx format=yyy name=zzz zoneid=aaa
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:
> set asyncblock false
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:
> query asyncjobresult jobid=<job-id>
1. Bash/zsh completion
2. DocBook Documentation
cloudmonkey was named after the beloved mascot of Apache CloudStack and is powered by Marvin.
Author: The Apache CloudStack Team <cloudstack-dev@incubator.apache.org>
Maintainer: Rohit Yadav <bhaisaab@apache.org>