IM Command-line Interface (CLI)
The im_client is a CLI client that uses XML-RPC or REST APIs of IM Server.
Installation
Prerequisites
The im_client needs at least Python 2.4 to run.
It is also required to install the RADL parser (https://github.com/grycap/radl), available in pip as the ‘RADL’ package. It is also required the Python Requests library (http://docs.python-requests.org/) available as ‘python-requests’ in O.S. packages or ‘requests’ in pip.
Optional packages
In case of using the SSL secured version of the XMLRPC API the SpringPython framework (http://springpython.webfactional.com/) must be installed.
Installing
Docker image
A Docker image named grycap/im-client has been created. Information about this image can be found here: https://hub.docker.com/r/grycap/im-client/. It is also available in Github Container registry ghcr.io/grycap/im-client: https://github.com/grycap/im-client/pkgs/container/im-client.
How to launch the IM client using docker:
docker run --rm -ti -v "$PWD:/im-client" grycap/im-client list
From pip
You only have to call the install command of the pip tool with the IM-client package:
$ pip install IM-client
From source
Download de source code from the Github repo: https://github.com/grycap/im-client/releases. Then you only need to install the tar-gziped file to any directoy:
$ tar xvzf IM-client-X.XX.tar.gz
Configuration
To avoid typing the parameters in all the client calls. The user can define a config file “im_client.cfg” in the current directory or a file “.im_client.cfg” in their home directory. In the config file the user can specify the following parameters:
[im_client]
# only set one of the urls
#xmlrpc_url=http://localhost:8899
restapi_url=http://localhost:8800
auth_file=auth.dat
xmlrpc_ssl_ca_certs=/tmp/pki/ca-chain.pem
Invocation
The im_client is called like this:
$ im_client.py [-u|--xmlrpc-url <url>] [-r|--restapi-url <url>] [-v|--verify-ssl] [-a|--auth_file <filename>] operation op_parameters
- -u|--xmlrpc-url url
URL to the XML-RPC service. This option or the ` -r` one must be specified.
- -r|--rest-url url
URL to the REST API on the IM service. This option or the ` -u` one must be specified.
- -v|--verify-ssl
Verify the certificates of the SSL connection. The default value is False.
- -a|--auth_file filename
Path to the authorization file, see Authorization File. This option is compulsory.
- -f|--force
Force the deletion of the infrastructure. Only for destroy operation. The default value is False.
- -q|--quiet
Work in quiet mode. Avoid all unnecessary prints. The default value is False.
- -n|--name
Show/use Infrastructure name in the selected operation. In case of list operation it will show the name of each infrastructure (if available). In other operations if this flag is set the user should specify the name of the infrastructure instead of the ID. The default value is False.
- operation
list filterList the infrastructure IDs created by the user. The
filterparameter is optional and is a regex that will be used to filter the list of infrastructures. This regex will be used with the RADL or TOSCA of the infrastructure.create inputfile async_flagCreate an infrastructure using RADL/TOSCA specified in the file with path
inputfile. Theasync_flagparameter is optional and is a flag to specify if the creation call will wait the resources to be created or return immediately the id of the infrastructure.destroy infIdDestroy the infrastructure with ID
infId.getinfo infId [radl_attribute]Show the information about all the virtual machines associated to the infrastructure with ID
infId. Optional parameterradl_attributeto show only the value of the specified attribute in the RADL.getcontmsg infIdShow the contextualization message of the infrastructure with ID
id.getstate infIdShow the state of the infrastructure with ID
id.getoutputs <infId>Show the outputs of infrastructure with ID
infId(Only in case of TOSCA docs with REST API).getvminfo infId vmId [radl_attribute]Show the information associated to the virtual machine with ID
vmIdassociated to the infrastructure with IDinfId. Optional parameterradl_attributeto show only the value of the specified attribute in the RADL.getvmcontmsg infId vmIdShow the contextualization message of the virtual machine with ID
vmIdassociated to the infrastructure with IDinfId.addresource infId radlfile ctxt_flagAdd to infrastructure with ID
infIdthe resources specifies in the RADL file with pathradlfile. Thectxt_flagparameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. If not specified the contextualization step will be launched.removeresource infId vmId ctxt_flagDestroy the virtual machine with ID
vmIdin the infrastructure with IDinfId. Thectxt_flagparameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. If not specified the contextualization step will be launched.start infIdResume all the virtual machines associated to the infrastructure with ID
infId, stopped previously by the operationstop.stop infIdStop (but not remove) the virtual machines associated to the infrastructure with ID
infId.alter infId vmId radlfileModify the specification of the virtual machine with ID
vmIdassociated to the infrastructure with IDvmId, using the RADL specification in file with pathradlfile.reconfigure infId radl_file vm_listReconfigure the infrastructure with ID
infIdand also update the configuration data specified in the optionalradl_file. The lastvm_listparameter is optional and is a list integers specifying the IDs of the VMs to reconfigure. If not specified all the VMs will be reconfigured.startvm infId vmIdResume the specified virtual machine
vmIdassociated to the infrastructure with IDinfId, stopped previously by the operationstop.stopvm infId vmIdStop (but not remove) the specified virtual machine
vmIdassociated to the infrastructure with ID infrastructure with IDinfId.rebootvm infId vmIdReboot the specified virtual machine
vmIdassociated to the infrastructure with ID infrastructure with IDinfId.sshvm infId vmId [show_only]Connect with SSH with the specified virtual machine
vmIdassociated to the infrastructure with ID infrastructure with IDinfId. Theshow_onlyparameter is optional and is a flag to specify if ssh command will only be shown in stdout instead of executed.export infId deleteExport the data of the infrastructure with ID
infId. Thedeleteparameter is optional and is a flag to specify if the infrastructure will be deleted from the IM service (the VMs are not deleted).import json_fileImport the data of an infrastructure previously exported with the previous function. The
json_fileis a file with the data generated with theexportfunction.wait infId [max_time]Wait infrastructure with ID
infIdto get a final state. It will return code0if it becomesconfiguredor1otherwhise. Optional parametermax_timeto set the max time to wait in seconds.create_wait_outputs inputfileThis operation is a combination of the create, wait and getoutputs functions. First it creates the infrastructure using the specified
inputfile, then waits for it to be configured, and finally gets the TOSCA outputs. In case of failure in then infrastructure creation step only the error message will be returned. The results will be returned to stdout in json format:{"infid": "ID", "error": "Error message"}
cloudusage cloud_idShow the usage/quotas of the cloud with ID
cloud_id. The results will be returned to stdout in json format:[ { "uri": "ost://server.com/image_id1", "name": "Image 1 Name" }, { "uri": "ost://server.com/image_id2", "name": "Image 2 Name" } ]
cloudimages cloud_idShow the images available in the cloud with ID
cloud_id. The results will be returned to stdout in json format (-1 means no limit):{ "cores": { "used": 36, "limit": -1 }, "ram": { "used": 50, "limit": -1 }, "instances": { "used": 10, "limit": 50 }, "security_groups": { "used": 0, "limit": -1 }, "floating_ips": { "used": 0, "limit": -1 } }
Python library
The IMClient can also be used as a Python library to access IM (since version 1.7.0) programatically. The following example shows how to use the IMClient to create and destroy an infrastructure:
from imclient import IMClient
auth = IMClient.read_auth_data("/path/auth.dat")
client = IMClient.init_client("https://im.egi.eu/im", auth)
inf_desc = """
network public (outbound = 'yes')
system node (
cpu.count>=2 and
memory.size>=4g and
net_interface.0.connection = 'public' and
disk.0.os.name='linux' and
disk.0.image.url = 'appdb://SCAI/egi.ubuntu.20.04?vo.access.egi.eu'
)
configure wn (
@begin
---
- tasks:
- debug: msg="Configured!"
@end
)
deploy node 1
"""
success, inf_id = client.create(inf_desc)
...
success, err = client.destroy(inf_id)
The IMClient class has the following methods:
- def init_client(im_url, auth_data, rest=True, ssl_verify=False):
Create and initialize the IMClient class
- Arguments:
im_url(string): URL to the IM API (REST or XML-RPC).
auth_data(dict of str objects): Authentication data to access cloud provider (as returned by read_auth_data function).
rest(boolean): Flag to specify the type of API to use (REST or XML-RPC). Default True.
ssl_verify(boolean): Flag to specify if ssl certificates must be validated. Default False.
- Returns(imclient.IMClient):
A client ready to interact with an IM instance.
- def read_auth_data(filename):
Read an IM auth data file.
- Arguments:
filename(string): path to the IM auth file.
- Returns(list of dict of str objects):
Authentication data to access cloud provider and the IM. One entry per line, each line splitted in a dictionary of pairs key/value.
- def create(self, inf_desc, desc_type="radl", asyncr=False):
Create an infrastructure
- Arguments:
inf_desc(string): Infrastructure description in RADL (plain or JSON) or TOSCA.
desc_type(string): Infrastructure description type (“radl”, “json” or “yaml”)
asyncr(boolean): Flag to specify if the creation call will be asynchronous. Default False.
- Returns:
A tuple with the operation success (boolean) and the infrastructure ID in case of successor the error message otherwise.
- def removeresource(self, inf_id, vm_list, context=None):
Remove resources from an infrastructure
- Arguments:
inf_id(string): Infrastructure ID.
vm_list(list of strings): List of VM IDs to delete.
context(boolean): Flag to disable the contextualization at the end.
- Returns:
A tuple with the operation success (boolean) and the list of deleted VM IDs in case of successor the error message otherwise.
- def addresource(self, inf_id, inf_desc, desc_type="radl", context=None):
Add resources into an infrastructure
- Arguments:
inf_id(string): Infrastructure ID.
inf_desc(string): Infrastructure description in RADL (plain or JSON) or TOSCA.
desc_type(string): Infrastructure description type (“radl”, “json” or “yaml”)
context(boolean): Flag to disable the contextualization at the end.
- Returns:
A tuple with the operation success (boolean) and the list of added VM IDs in case of success or the error message otherwise.
- def alter(self, inf_id, vm_id, inf_desc):
Modifies the features of a VM
- Arguments:
inf_id(string): Infrastructure ID.
vm_id(string): VM ID.
inf_desc(string): Infrastructure description in RADL (plain).
- Returns:
A tuple with the operation success (boolean) and the RADL of the modified VM in case of success or the error message otherwise.
- def reconfigure(self, inf_id, inf_desc, desc_type="radl", vm_list=None):
Reconfigure the infrastructure
- Arguments:
inf_id(string): Infrastructure ID.
inf_desc(string): Infrastructure description in RADL (plain).
vm_list(list of strings): Optional list of VM IDs to reconfigure (default all).
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.
- def get_infra_property(self, inf_id, prop):
Get an infrastructure property.
- Arguments:
inf_id(string): Infrastructure ID.
prop(string): Property to get. Valid values: “radl”, “contmsg”, “state”, “outputs”
- Returns:
A tuple with the operation success (boolean) and the value of the prop in case of success or the error message otherwise.
- def getvminfo(self, inf_id, vm_id, prop=None, system_name=None):
Get VM info.
- Arguments:
inf_id(string): Infrastructure ID.
vm_id(string): VM ID.
prop(string): Optional RADL property to get.
system_name(string): Optional system name to filter the VMs.
- Returns:
A tuple with the operation success (boolean) and the value of the prop in case of success or the error message otherwise.
- def getinfo(self, inf_id, prop=None, system_name=None):
Get infrastructure info.
- Arguments:
inf_id(string): Infrastructure ID.
prop(string): Optional RADL property to get.
system_name(string): Optional system name to filter the VMs.
- Returns:
A tuple with the operation success (boolean) and the value of the prop in case of success or the error message otherwise.
- def destroy(self, inf_id, asyncr=False):
Destroy an infrastructure
- Arguments:
inf_id(string): Infrastructure ID.
asyncr(boolean): Flag to specify if the deletion call will be asynchronous. Default False.
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.
- def list_infras(self, flt=None):
Get the list of user infrastructures
- Arguments:
flt(string): Optional filter (as regular expression) to filter the infrastructures.
- Returns:
A tuple with the operation success (boolean) and the list of infrastructure IDs in case of success or the error message otherwise.
- def start_infra(self, inf_id):
Start an infrastructure (previously stopped)
- Arguments:
inf_id(string): Infrastructure ID.
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.
- def stop_infra(self, inf_id):
Stop an infrastructure
- Arguments:
inf_id(string): Infrastructure ID.
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.
- def start_vm(self, inf_id, vm_id):
Start an VM (previously stopped)
- Arguments:
inf_id(string): Infrastructure ID.
vm_id(string): VM ID.
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.
- def stop_vm(self, inf_id, vm_id):
Stop an VM
- Arguments:
inf_id(string): Infrastructure ID.
vm_id(string): VM ID.
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.
- def reboot_vm(self, inf_id, vm_id):
Reboot an VM
- Arguments:
inf_id(string): Infrastructure ID.
vm_id(string): VM ID.
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.
- def getversion(self):
Get IM server version
- Returns:
A tuple with the operation success (boolean) and the version string in case of success or the error message otherwise.
- def export_data(self, inf_id, delete=None):
Export infrastructure data
- Arguments:
inf_id(string): Infrastructure ID.
delete(boolean): Flag to specify if the infrastructure will be deleted after exporting the data. Default False.
- Returns:
A tuple with the operation success (boolean) and the json data of the infrastructure in case of success or the error message otherwise.
- def import_data(self, data):
Import infrastructure data
- Arguments:
data(string): Json data with the Infrastructure info.
- Returns:
A tuple with the operation success (boolean) and the ID of the imported infrastructure in case of success or the error message otherwise.
- def get_cloud_images(self, cloud_id):
Get Cloud provider images
- Arguments:
cloud_id(string): ID of the cloud provider (as defined in the auth data).
- Returns:
A tuple with the operation success (boolean) and the requested data in case of success or the error message otherwise.
- def get_cloud_quotas(self, cloud_id):
Get Cloud provider quotas
- Arguments:
cloud_id(string): ID of the cloud provider (as defined in the auth data).
- Returns:
A tuple with the operation success (boolean) and the requested data in case of success or the error message otherwise.
- def change_auth(self, inf_id, new_auth_data, overwrite=None):
Change ownership of an infrastructure
- Arguments:
inf_id(string): Infrastructure ID.
new_auth_data(string): New Infrastructure Manager auth data to set.
overwrite(boolean): Flag to specify if the auth data will be overwrited. Default False.
- Returns:
A tuple with the operation success (boolean) and an empty string in case of success or the error message otherwise.