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.

digraph stategraph { layout=dot; node [shape=circle, fontsize=10, fixedsize=true, height=.9, weight=.9]; "pending" -> "running" -> "configured" -> "off" ; "pending" -> "failed"; "running" -> "unconfigured"; "configured" -> "stopped"; "configured" -> "running"; "stopped" -> "pending"; "configured" -> "deleting"; }

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
            },
            {
               "cpuCores": 1,
               "memoryInMegabytes": 2048,
               "diskSizeInGigabytes": 10
            }
      ],
      "storage": [
               {"sizeInGigabytes": 100, "type": "ceph"},
               {"sizeInGigabytes": 100}
      ]
   }
}