IM XML-RPC API

IM Service can be accessed through the API that follows the XML-RPC specification. The port number and the security settings are controlled by the options listed in XML-RPC API.

The last parameter in every call refers to the credentials for the IM Service, the VMRC and cloud providers. Every credential is represented as a struct datatype, whose keys and values are described in Authorization File. Then the parameter is an array of these structs.

IM valid States

List of valid VM and infrastructure states:

The state can be

pending, launched, but still in initialization stage;

running, created successfully and running, but still in the configuration stage;

configured, running and contextualized;

unconfigured, running but not correctly contextualized;

stopped, stopped or suspended;

off, shutdown or removed from the infrastructure;

failed, an error happened during the launching; or

unknown, unable to obtain the status.

deleting, in the deletion process.

The next figure shows a state diagram of virtual machine status. This figure is illustrative as if may differ in case of Cloud Providers.

Methods

This is the list of method names:

GetInfrastructureList

parameter 0:: auth: array of structs
parameter 1:: filter: (optional, default value None) string
ok response:: [true, infIds: array of integers]
fail response:: [false, error: string]

Return the ID associated to the infrastructure created by the user. In case of using a filter it will be used as a regular expression to search in the RADL or TOSCA used to create the infrastructure.

CreateInfrastructure

parameter 0:: radl: string
parameter 1:: auth: array of structs
parameter 2:: async: (optional, default value False) boolean
ok response:: [true, infId: integer]
fail response:: [false, error: string]

Create and configure an infrastructure with the requirements specified in the RADL document passed as string. Return the ID associated to the created infrastructure. If async is set to True the call will not wait forthe VMs to be created.

GetInfrastructureInfo

parameter 0:: infId: integer
parameter 1:: auth: array of structs
ok response:: [true, vm_list: array of integers]
fail response:: [false, error: string]

Return a list of IDs associated to the virtual machines of the infrastructure with ID infId.

GetInfrastructureContMsg

parameter 0:: infId: integer
parameter 1:: auth: array of structs
parameter 2:: headeronly: (optional, default value False) boolean
ok response:: [true, cont_out: string]
fail response:: [false, error: string]

Return the contextualization log associated to the infrastructure with ID infId. In case of headeronly flag is set to True. Only the initial part of the infrastructure contextualization log will be returned (without any VM contextualization log).

GetInfrastructureState

parameter 0:: infId: integer
parameter 1:: auth: array of structs
ok response:: [true, struct(state: string, vm_states: dict of integer (VM ID) to string (VM state)]
fail response:: [false, error: string]

Return the aggregated state associated to the infrastructure with ID infId.

GetInfrastructureRADL

parameter 0:: infId: integer
parameter 1:: auth: array of structs
ok response:: [true, radl_info: string]
fail response:: [false, error: string]

Return a string with the original RADL specified to create the infrastructure with ID infId.

GetVMInfo

parameter 0:: infId: integer
parameter 1:: vmId: string
parameter 2:: auth: array of structs
ok response:: [true, radl_info: string]
fail response:: [false, error: string]

Return a string with information about the virtual machine with ID vmId in the infrastructure with ID infId. The returned string is in RADL format.

GetVMProperty

parameter 0:: infId: integer
parameter 1:: vmId: string
parameter 2:: property_name: string
parameter 3:: auth: array of structs
ok response:: [true, property_value: string]
fail response:: [false, error: string]

Return a string with the specific property of the RADL information about the virtual machine with ID vmId in the infrastructure with ID infId. It enables to get a single property of the RADL of the function GetVMInfo.

GetVMContMsg

parameter 0:: infId: integer
parameter 1:: vmId: string
parameter 2:: auth: array of structs
ok response:: [true, cont_msg: string]
fail response:: [false, error: string]

Return a string with contextualization log of the virtual machine with ID vmId in the infrastructure with ID infId.

AlterVM

parameter 0:: infId: integer
parameter 1:: vmId: string
parameter 2:: radl: string
parameter 3:: auth: array of structs
ok response:: [true, struct(info: string, cloud: string, state: string)]
fail response:: [false, error: string]

Change the features of the virtual machine with ID vmId in the infrastructure with with ID infId, specified by the RADL radl. Return a struct with information about the nodified virtual machine, like GetVMInfo.

DestroyInfrastructure

parameter 0:: infId: integer
parameter 1:: auth: array of structs
parameter 2:: force: (optional, default value False) boolean
parameter 3:: async: (optional, default value False) boolean
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Undeploy all the virtual machines associated to the infrastructure with ID infId. The force parameter is optional and is a flag to specify that the infra will be from the IM although not all resources are deleted. If async is set to True the call will not wait the infrastructure to be deleted.

AddResource

parameter 0:: infId: integer
parameter 1:: radl: string
parameter 2:: auth: array of structs
parameter 3:: context: (optional, default value True) boolean
ok response:: [true, infId: integer]
fail response:: [false, error: string]

Add the resources specified in radl to the infrastructure with ID infId. The last context parameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. The default value is True. The deploy instructions in the radl must refer to systems already defined. If all the systems defined in radl are new, they will be added. Otherwise the new systems defined will be ignored. All the systems specified in the deploy must be specified in the radl. If they has been already defined only a reference is needed. This is a simple example to deploy one new VM from an alreay defined system:

network public
system node
deploy node 1

RemoveResource

parameter 0:: infId: integer
parameter 1:: vmIds: string
parameter 2:: auth: array of structs
parameter 3:: context: (optional, default value True) boolean
ok response:: [true, integer]
fail response:: [false, error: string]

Updeploy the virtual machines with IDs in vmIds associated to the infrastructure with ID infId. The different virtual machine IDs in vmIds are separated by commas. On success it returns the number of VMs that have been undeployed. The last context parameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. The default value is True.

StopInfrastructure

parameter 0:: infId: integer
parameter 1:: auth: array of structs
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Stop (but do not undeploy) all the virtual machines associated to the infrastructure with ID infId. They can resume by StartInfrastructure.

StopVM

parameter 0:: infId: integer
parameter 1:: vmId: integer
parameter 2:: auth: array of structs
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Stop (but do not undeploy) the specified virtual machine with ID vmId associated to the infrastructure with ID infId. They can resume by StartVM.

StartInfrastructure

parameter 0:: infId: integer
parameter 1:: auth: array of structs
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Resume all the virtual machines associated to the infrastructure with ID infId, previously stopped by StopInfrastructure.

StartVM

parameter 0:: infId: integer
parameter 1:: vmId: integer
parameter 2:: auth: array of structs
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Resume the specified virtual machine with ID vmId associated to the infrastructure with ID infId, previously stopped by StopInfrastructure or StopVM.

RebootVM

parameter 0:: infId: integer
parameter 1:: vmId: integer
parameter 2:: auth: array of structs
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Reboot the specified virtual machine with ID vmId associated to the infrastructure with ID infId.

Reconfigure

parameter 0:: infId: integer
parameter 1:: radl: string
parameter 2:: auth: array of structs
parameter 3:: vm_list: (optional, default value None) array of integers
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Update the infrastructure with ID infId using the configuration sections in the RADL radl. Some virtual machines associated to the infrastructure may be reconfigured. The last vm_list parameter is optional and is a list integers specifying the IDs of the VMs to reconfigure. The default value is None that means that all the VMs will be reconfigured.

ExportInfrastructure

parameter 0:: infId: integer
parameter 1:: delete: bool
parameter 2:: auth: array of structs
ok response:: [true, string]
fail response:: [false, error: string]

Return the serialization of the infrastructure with ID infId. If delete is true, the infrastructure is marked as deleted after that (and no machine is undeployed). This function is useful to transfer the control of an infrastructure to other IM server. See ImportInfrastructure.

ImportInfrastructure

parameter 0:: strInf: string
parameter 1:: auth: array of structs
ok response:: [true, infId: integer]
fail response:: [false, error: string]

Take control of the infrastructure serialized in strInf and return the ID associated in the server. See ExportInfrastructure.

CreateDiskSnapshot

parameter 0:: infId: integer
parameter 1:: vmId: integer
parameter 2:: diskNum: integer
parameter 3:: imageName: string
parameter 4:: autoDelete: boolean
parameter 5:: auth: array of structs
ok response:: [true, string]
fail response:: [false, error: string]

Create a snapshot of the specified diskNum in the VM vmId of the infrastructure with ID infId`. The ``autoDelete flag specifies that the snapshot will be deleted when the infrastructure is destroyed. It returns the image url of the new created image in IM format (see disk.<diskId>.image.url format in RADL).

GetCloudImageList

parameter 0:: cloudId: integer
parameter 1:: auth: array of structs
parameter 2:: filters: (optional, default value None) struct
ok response:: [true, imageUrls: array of structs]
fail response:: [false, error: string]

Get the list of available images in the specified cloud provider. The optional filters parameter enables filterin the list of images. This field is cloud provider specific (e.g. {"region": "<region_name>"} for Amazon EC2, GCE or Azure). The id cloudId is relative to the id field in the auth paramater. Response format:

[
   {
      "uri" : "ost://hostname/image-id1",
      "name" : "Image Name1"
   },
   {
      "uri" : "ost://hostname/image-id2",
      "name" : "Image Name2"
   }
]

GetCloudQuotas

parameter 0:: cloudId: integer
parameter 1:: auth: array of structs
ok response:: [true, struct]
fail response:: [false, error: string]

Get available and used resources for the current user in the specified cloud provider. The id cloudId is relative to the id field in the auth paramater. Response format:

{
   "cores": {"used": 1, "limit": 10},
   "ram": {"used": 1, "limit": 10},
   "instances": {"used": 1, "limit": 10},
   "floating_ips": {"used": 1, "limit": 10},
   "security_groups": {"used": 1, "limit": 10}
}

ChangeInfrastructureAuth

parameter 0:: infId: integer
parameter 1:: newAuth: array of structs
parameter 2:: overwrite: boolean
parameter 3:: auth: array of structs
ok response:: [true, string of length zero]
fail response:: [false, error: string]

Change the authentication data of the infrastructure with ID infId. using the newAuth provider. If overwrite is true, the authentication data will be overwrited otherwise it will be appended.

GetInfrastructureOwners

parameter 0:: infId: integer
parameter 1:: auth: array of structs
ok response:: [true, list of strings]
fail response:: [false, error: string]

Return the list of current owners of the infrastructure with ID infId.

EstimateResouces

parameter 0:: radl: string
parameter 1:: auth: array of structs
ok response:: [true, struct]
fail response:: [false, error: string]

Get the estimated amount of resources needed to deploy the infrastructure specified in the RADL document passed as string. The response is a struct with the following format (memory unit MB, disk and storage unit GB):

{
   "ost1": {
      "cloudType": "OpenStack",
      "cloudEndpoint": "http://openstack.example.com:5000",

      "compute": [
            {
               "cpuCores": 2,
               "memoryInMegabytes": 4096,
               "diskSizeInGigabytes": 20,
               "GPU": 0,
               "publicIP": 1
            },
            {
               "cpuCores": 1,
               "memoryInMegabytes": 2048,
               "diskSizeInGigabytes": 10
            }
      ],
      "storage": [
               {"sizeInGigabytes": 100, "type": "ceph"},
               {"sizeInGigabytes": 100}
      ]
   }
}

GetStat

parameter 0:: init_date: string
parameter 1:: end_date: string
parameter 2:: auth: array of structs
ok response:: [true, list of dicts]
fail response:: [false, error: string]

Return the stats of the current user in the IM service. Return all the infrastructures in the interval init_date-end-date deployed by the user showing some aggregated information. In JSON format:

[
   {"creation_date": "2022-03-07 13:16:14",
   "tosca_name": "kubernetes",
   "vm_count": 2,
   "cpu_count": 4,
   "memory_size": 1024,
   "cloud_type": "OSCAR",
   "cloud_host": "server.com",
   "hybrid": false,
   "deleted": false,
   "im_user": "username",
   "inf_id": "1",
   "last_date": "2022-03-23"}
]