Eco4Cloud APIs for developers

Eco4Cloud exposes a set of JSON, RESTful APIs in order to fetch or modify the workload consolidation options and constraints.

So, another software can interact with an Eco4Cloud instance by sending well-formed HTTP requests to the Eco4Cloud instance, identified by an IP address which we will call e4c_appliance_address from now on.

A client must obtain, through a login process, a cookie-like ticket and add it in HTTP request header for further requests, as a custom field, named “ticket”. The ticket is a unique code associated with a user that allows to make requests for 60 minutes. After ticket expiration, the client will receive an error until obtaining a new ticket.

A skeleton of invocation may be:

ticket=login(username,password);

request_1(ticket);

request_2(ticket);

...

Each request returns a JSON string containing the result of the API call.

Login

URL: http://e4c_appliance_address/api/Login

The request can be completed in GET or POST method, using the following parameters.

Name Description
username E4C registered username for authentication
password E4C registered password for authentication

The result will be a JSON string with the following structure.

Name Description Value
result The result of the login operations
  • “Ok”, in case of successful login
  • “KO”, in case of incorrect login
  • An error message, if an error occurs during the login
ticket The ticket associated with the login. Must be used for further requests.
  • Null, in case of incorrect login
  • A Ticket Code, in case of successful login

GET REQUESTS

URL: http://e4c_appliance_address/api/<entity>/get?<parameters>

The keyword “<entity>” specifies which kind of resource the client is querying for. The possible values are the following.

Name Description
Farm use for extract data related to the farm
Cluster use for extract data related to the clusters
Host use for extract data related to the host
Vm use for extract data related to the vms
DataStore use for extract data related to the datastores

The keyword “<parameters>” gives the possibility to apply filters on the extraction of data. Each request returns a JSON string representing the specified entity. The filters applied and the structure of the output depends on the type of entity specified in the request.

After the keyword “<parameters>”, it is also possible to append the option “&page=<page_number>”, in order to limit the number of results to fetch. Each page will list a maximum of 20 entities, so it will possible to fetch another page of results as soon as the listed entities in a page will be equal to 20.

GET - Farm

URL: http://e4c_appliance_address/api/Farm/get?<parameters>

The following filters are allowed.

Name Type Description
name optional If the filter is inserted, only farms matching the filter get listed in the result.

The result will be a JSON string with the following structure.

Name Type Description
Name String The name of the farm
Description String An optional description of the farm
Ta int Target resource utilization for the farm
Th int  Maximum acceptable resource utilization for the farm
Consolidation_on Boolean Whether the workload consolidation is enabled or disabled
power_off_min_uptime int The minimum amount of uptime (minutes) before Eco4Cloud workload consolidation is allowed to switch off a host of the farm
power_on_min_downtime int The minimum amount of downtime (minutes) before Eco4Cloud workload consolidation is allowed to switch on a host of the farm

Example: get a server farm chosen by its name

GET http://e4c_appliance_address/api/Farm/get?name=test_farm

{
   "Farms":[
      {
         "name":"test_farm",
         "description":"test_farm",
         "ta":"80",
         "th":"90",
         "consolidation_on":"true"
      }
   ]
}

GET - Cluster

URL: http://e4c_appliance_address/api/Cluster/get?<parameters>

The following filters are allowed.

Name Type Description
name optional If the filter is inserted, only clusters matching the filter get listed in the result.
farm_name optional If the filter is inserted, only clusters in the specified farm get listed in the result.

The result will be a JSON string with the following structure.

Name Type Description
Name String The name of the cluster
Uuid String The universally unique identifier of the cluster
servers_always_on int The minimum number of hosts that must be switched on and available
consolidation_enabled Boolean Whether the consolidation is enabled on the cluster
Farm String The name of the farm of the cluster
power_off_min_uptime int The minimum amount of uptime (minutes) before Eco4Cloud workload consolidation is allowed to switch off a host of the cluster
power_on_min_downtime int The minimum amount of downtime (minutes) before Eco4Cloud workload consolidation is allowed to switch on a host of the cluster
drs_mode String The DRS behavior backing up Eco4Cloud in case it gets disabled on the cluster. It can be chosen by the user and can be:

  • Manual
  • Partially automated
  • Fully Automated
  • Nothing – if not specified

Available only in VMware environments. Please refer to VMware documentation.

Example: list the clusters in a specific farm

GET http://e4c_appliance_address/api/Cluster/get?name=cluster_test&farm_name=test_farm

{
   "Clusters":[
      {
         "name":"cluster_test",
         "uuid":"datacenter-2_domain-c7",
         "servers_always_on":"1",
         "consolidation_enabled":"true",
         "Farm":"icar",
         "power_off_min_uptime":"10",
         "power_on_min_downtime":"10",
         "drs_mode":"nothing"
      }
   ]
}

GET - Host

URL: http://e4c_appliance_address/api/Host/get?<parameters>

The following filters are allowed.

Name Type Description
name optional If the filter is inserted, only hosts matching the filter get listed in the result
Cluster_name optional If the filter is inserted, only hosts of the specified cluster get listed in the result

The result will be a JSON string with the following structure.

Name Type Description
Name String The name of the host
Uuid String The universally unique identifier of the host
powered_on int Whether the host is currently turned on or off
cpu_frequency int The CPU frequency of the host (MHz)
cpu_cores String The number of CPU cores of the host
ram_mb int The amount of RAM memory in the host (MB)
bandwidth int The amount of bandwidth of the host (MBps)
standby_enabled Boolean Whether Eco4Cloud is allowed to switch on or off a host
Cluster String The name of the cluster of the host
Farm String The name of the farm of the host
power_off_min_uptime int The minimum amount of uptime (minutes) before Eco4Cloud workload consolidation is allowed to switch off a host. It overwrites the same option if entered also at a cluster level.
power_on_min_downtime int The minimum amount of downtime (minutes) before Eco4Cloud workload consolidation is allowed to switch on a host. It overwrites the same option if entered also at a cluster level.
 IPMI
Typically, Eco4Cloud instructs hosts switch on/off through the virtualization layer. Optionally, it is possible to interact directly with physical hosts through the IPMI protocol, to switch on/off a host.
ipmi_ip String IPMI IP address of the host
ipmi_username String IPMI username of the host
ipmi_password String IPMI password of the host
Performance
Eco4Cloud collects performance data for each host
performance_date String The date of the last performance sample
cpu float The percentage of CPU utilization
mem float The percentage of RAM utilization
bandwidth_usage float The percentage of bandwidth utilization
power float The power consumption of the host (Watts)

Example: get the host named “test_host_1″

GET http://e4c_appliance_address/api/Host/get?name=test_host_1

{
   "Hosts":[
      {
         "name":"test_host_1",
         "uuid":"datacenter-2_host-547",
         "powered_on":"true",
         "cpu_frequency":"2266.00",
         "cpu_cores":"8",
         "ram_mb":"24567",
         "bandwidth":"1000",
         "standby_enabled":"true",
         "Cluster":"cluster_test",
         "Farm":"test_farm",
         "power_off_min_uptime":"30",
         "power_on_min_downtime":"11",
         "ipmi_ip":"",
         "ipmi_username":"",
         "ipmi_password":"",
         "Performance":[
            {
               "performance_date":"2014-07-07 16:59:54",
               "cpu":"2.28",
               "mem":"51.74",
               "bandwidth_usage":"0.11",
               "power":"0.00"
            }
         ]
      }
   ]
}

GET - Virtual Machine

URL: http://e4c_appliance_address/api/Vm/get?<parameters>

The following filters are allowed.

Name Type Description
name optional If the filter is inserted, only VMs matching the filter get listed in the result
Cluster_name optional If the filter is inserted, only VMs of the specified cluster get listed in the result
Host_name Optional If the filter is inserted, only VMs of the specified host get listed in the result

The result will be a JSON string with the following structure.

Name Type Description
Name String The name of the VM
Uuid String The universally unique identifier of the VM
operating_system String The OS running on the VM
assigned_cores int The number of CPU cores assigned to the VM
assigned_memory_mb int The amount of RAM memory allocated to the VM
migration_enabled boolean Whether Eco4Cloud is allowed to migrate the VM
cluster_migration_enabled boolean Whether Eco4Cloud is allowed to migrate the VM outside of its cluster
Host String The name of the host of the vm
Cluster String The name of the cluster of the vm
Farm String The name of the farm of the vm
Performance
Eco4Cloud collects performance data for each VM
performance_date String The date of the last performance sample
cpu float The percentage of CPU utilization
mem float The percentage of RAM utilization
Bandwidth float The percentage of bandwidth utilization
active_memory int The amount of active memory
compressed_memory int The amount of compressed memory
swapped_memory int The amount of swapped memory
ballooned_memory int The amount of ballooned memory

Example: get the virtual machine named “test_vm_1″

GET http://e4c_appliance_address/api/vm/get?name=test_vm_1

{  
   “Vms”:[  
      {  
         “name”:“test_vm_1″,
         “uuid”:“datacenter-2_vm-124″,
         “operating_system”:“”,
         “assigned_cores”:“8”,
         “assigned_memory_mb”:“3072”,
         “migration_enabled”:“true”,
         “cluster_migration_enabled”:“false”,
         “Host”:“test_host_1″,
         “Cluster”:“cluster_test”,
         “Farm”:“test_farm”,
         “Performance”:[  
            {  
               “performance_date”:“2014-07-07 15:40:56″,
               “cpu”:“0.00”,
               “mem”:“0.00”,
               “bandwidth”:“0.00”,
               “active_memory”:“0.00”,
               “compressed_memory”:“0.00”,
               “swapped_memory”:“0.00”,
               “ballooned_memory”:“0.00”
            }
         ]
      }
   ]
}

GET - Data Store

URL: http://e4c_appliance_address/api/DataStore/get?<parameters>

The following filters are allowed.

Name Type Description
name optional If the filter is inserted, only datastores matching the filter get listed in the result
Cluster_name optional If the filter is inserted, only datastores of the specified cluster get listed in the result
Host_name Optional If the filter is inserted, only datastores of the specified host get listed in the result

The result will be a JSON string with the following structure.

Name Type Description
Name String The name of the datastore
Uuid String The universally unique identifier of the VM
Farm String The name of the farm of the datastore
Performance
Eco4Cloud collects real-time performance data for each datastore
performance_date String The date of the last performance sample
io float The IO rate

Example: get the list of datastores attached to host “test_host_1″

GET http://e4c_appliance_address/api/DataStore/get?host_name=test_host_1

{  
  “DataStore”:[  
    {  
      “name”:“test_datastore_1″,
      “uuid”:“datacenter-2_datastore-10″,
      “Farm”:“test_farm”,
      “Performance”:[  
        {  
          “performance_date”:“2014-07-07 16:59:54″,
          “io”:“0.00”
        }
      ]
    },
    {  
      “name”:“test_datastore_2″,
      “uuid”:“datacenter-2_datastore-548″,
      “Farm”:“test_farm”,
      “Performance”:[  
        {  
          “performance_date”:“2014-07-07 16:59:54″,
          “io”:“0.00”
        }
      ]
    }
  ]
}

SET REQUESTS

URL: http://e4c_appliance_address/api/<entity>/set

The keyword “<entity>” specifies which kind of resource the client is changing settings for. The possible values are the following.

Name Description
Farm for changing the the farm settings
Cluster for changing the the cluster settings
Host for changing the the host settings
Vm for changing the the virtual machine settings

Each SET operation takes as input a JSON string specifying the parameters to be changed and the conditions to be verified. The general structure of the string is as follows.

{
    "setList":[
        {"name":"<parameter1>","value":"<value1>"},
        {"name":"<parameter2>","value":"<value1>"},
        ...
    ],
    "whereList":[
        {"name":"<condition1>","value":"<value1>"},
        {"name":"<condition2>","value":"<value1>"},
        ...
    ]
}

The allowed values for the Setlist and WhereList depend on the entity specified in the request.

The result is a JSON string with the following structure.

Name Type Description
result String
  • Ok
  • Ko, in case of error(s)
rows_affected Int number of entities updated
error String the description of eventual error(s)

SET - Farm

URL: http://e4c_appliance_address/api/Farm/set

The following SetList is allowed.

Name Type Description
ta float Target resource utilization for the farm
th float Maximum acceptable resource utilization for the farm
consolidation_on boolean Whether the workload consolidation is enabled or disabled
power_off_min_uptime int The minimum amount of uptime (minutes) before Eco4Cloud workload consolidation is allowed to switch off a host of the farm
power_on_min_downtime int The minimum amount of downtime (minutes) before Eco4Cloud workload consolidation is allowed to switch on a host of the farm

The following WhereList is allowed.

Name Type Description
name String name of the  farm to be updated

Example: allow workload consolidation

POST http://e4c_appliance_address/api/Farm/set

DATA {“setList”:[{“name”:”consolidation_on”,”value”:”true”}],”whereList”:[{“name”:”name”,”value”:”test_farm”}]}

{  
  “result”:“ok”,
  “rows_affected”:1
}

SET - Cluster

URL: http://e4c_appliance_address/api/Cluster/set

The following SetList is allowed.

Name Type Description
servers_always_on int The minimum number of hosts that must be switched on and available
consolidation_enabled Boolean Whether the consolidation is enabled on the cluster
power_off_min_uptime int The minimum amount of uptime (minutes) before Eco4Cloud workload consolidation is allowed to switch off a host of the cluster
power_on_min_downtime int The minimum amount of downtime (minutes) before Eco4Cloud workload consolidation is allowed to switch on a host of the cluster
drs_mode String The DRS behavior backing up Eco4Cloud in case it gets disabled on the cluster. It can be chosen by the user and can be:

  • Manual
  • Partially automated
  • Fully Automated

Available only in VMware environments. Please refer to VMware documentation.

The following WhereList is allowed.

Name Type Description
name String name of the cluster to be updated

Example: stop workload consolidation on a specific cluster

POST http://e4c_appliance_address/api/Cluster/set

DATA {“setList”:[{“name”:”consolidation_enabled”,”value”:”false”}],”whereList”:[{“name”:”name”,”value”:”cluster_test”}]}

{  
  “result”:“ok”,
  “rows_affected”:1
}

SET - Host

URL: http://e4c_appliance_address/api/Host/set

The following SetList is allowed.

Name Type Description
standby_enabled Boolean Whether Eco4Cloud is allowed to switch on or off a host
power_off_min_uptime Int The minimum amount of uptime (minutes) before Eco4Cloud workload consolidation is allowed to switch off a host. It overwrites the same option if entered also at a cluster level.
power_on_min_downtime int The minimum amount of downtime (minutes) before Eco4Cloud workload consolidation is allowed to switch on a host. It overwrites the same option if entered also at a cluster level.

The following WhereList is allowed.

Name Type Description
name String name of the  host to be updated

Example: allow host switch off

POST http://e4c_appliance_address/api/Host/set

DATA {“setList”:[{“name”:”standby_enabled”,”value”:”true”}],”whereList”:[{“name”:”name”,”value”:”test_host_4″}]}

{  
  “result”:“ok”,
  “rows_affected”:1
}

SET - Virtual Machine

URL: http://e4c_appliance_address/api/Vm/set

The following SetList is allowed.

Name Type Description
migration_enabled boolean Whether Eco4Cloud is allowed to migrate the VM
cluster_migration_enabled boolean Whether Eco4Cloud is allowed to migrate the VM outside of its cluster

The following WhereList is allowed.

Name Type Description
name String name of the vm to be updated

Example: flag a VM as migratable

POST http://e4c_appliance_address/api/Vm/set

DATA {“setList”:[{“name”:”migration_enabled”,”value”:”true”}],”whereList”:[{“name”:”name”,”value”:”test_vm_1″}]}

{  
  “result”:“ok”,
  “rows_affected”:1
}