RESTful API - Virtual Machine

By sending requests to the Virtual Machine endpoint /vm/ you can list, create, update or delete VMs.

HTTPie is highly recommended: CLI HTTP client, user-friendly curl replacement with intuitive UI, JSON support, syntax highlighting, wget-like downloads, extensions, etc. http://httpie.org

List all virtual machines

In order to list all your Virtual Machines you should make a HTTP GET request to the endpoint /vm/, passing of course your access token. You'll get a quick summary of every single virtual machine you have permission to manage in the EIS Virtual Cloud.

Name	Type	Description
uuid	string	128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID.
name	string	Virtual Machine name including VSS prefix.
guestFullName	string	This is the full name of the guest operating system for the virtual machine. For example: Windows 2000 Professional.
ipAddress	string	Primary IP address assigned to the guest operating system, if known.
memoryMB	integer	Memory size of the virtual machine, in megabytes.
cpuCount	integer	Number of processors in the virtual machine.
overallStatus	string	Overall alarm status on this node.
powerState	string	The current power state of the virtual machine.
provisionedGB	integer	Sum of Committed and Uncommitted storage.

The following example uses HTTPie to request all Virtual Machine managed by given user without filters:

http -a $TK GET https://vss-api.eis.utoronto.ca:8001/v2/vm/

{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca:8001/v2/", 
        "self": "https://vss-api.eis.utoronto.ca:8001/v2/vm/"
    }, 
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca:8001/v2/vm/50125944-d5e0-248d-0f3c-c499acbeb1ce/"
            }, 
            "cpuCount": 2, 
            "folder": {
                "_links": {
                    "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6557"
                }, 
                "moref": "group-v12342", 
                "name": "Swarm", 
                "parent": "Sandbox"
            }, 
            "guestFullName": "Other 3.x Linux (64-bit)", 
            "ipAddress": "128.100.72.1", 
            "memoryMB": 2048, 
            "name": "1604P-docker-node2", 
            "overallStatus": "green", 
            "powerState": "poweredOn", 
            "provisionedGB": 22, 
            "uuid": "50125944-d5e0-248d-0f3c-c499acbeb1ce"
        }
    ], 
    "meta": {
        "count": 22, 
        "time": "1.04441s", 
        "user": "jm"
    }
}

Filters

The main Virtual Machine resource has three main filters to reduce the number of VMs shown in the result or to locate a VM by hostname or ip address.

Name	Description
name	Virtual Machine name string to filter VMs
ip	Primary IP address assigned to the Guest operating system.
dns	Hostname of the guest operating system.
summary	Disables VM summary in results.

The following examples show how to implement a GET request with the first three parameters shown below. The result is similar to the previous section.

http -a $TK GET https://vss-api.eis.utoronto.ca:8001/v2/vm/?name=Test
http -a $TK GET https://vss-api.eis.utoronto.ca:8001/v2/vm/?ip=10.2.1.2
http -a $TK GET https://vss-api.eis.utoronto.ca:8001/v2/vm/?dns=wiki.eis.utoronto.ca

If you decide to add summary in the list of parameters, you'll disable the summary provided by the API about any given VM for this particular request. For example:

http -a $TK GET https://vss-api.eis.utoronto.ca:8001/v2/vm/?name=Test&summary

{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca:8001/v2/", 
        "self": "https://vss-api.eis.utoronto.ca:8001/v2/vm/"
    }, 
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca:8001/v2/vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db/"
            }, 
            "name": "1604Q-VMTest_1", 
            "uuid": "5012bd15-c20c-a971-aa68-af1a3cf3d0db"
        }
    ], 
    "meta": {
        "count": 1, 
        "time": "1.86220s", 
        "user": "jm"
    }
}

From now on, you will need the UUID of any virtual machine, provided by the "_links" section, to get further information about it and eventually to modify properties.

List specific virtual machine info

Some of the attributes will have an object value. Such is the case of the guest, hardware, network, config, vss and guest.

Name	Type	Description
uuid	string	VirtualCenter-specific 128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID.
name	string	Virtual Machine name including VSS prefix.
Config	VM Configuration
bootdelay	integer	Delay in milliseconds before starting the boot sequence. The boot delay specifies a time interval between virtual machine power on or restart and the beginning of the boot sequence.
hotaddCPU	boolean	Whether virtual processors can be added while this virtual machine is running.
hotremoveCpu	boolean	Whether virtual processors can be removed while this virtual machine is running.
hotaddMem	boolean	Whether memory can be added while this virtual machine is running.
Folder	Logical Folder
name	string	Immediate folder holding VM
parent	string	Parent folder holding the VM
path	string	Full path to immediate folder
Guest	Guest status and configuration
guestFullName	string	This is the full name of the guest operating system for the virtual machine. For example: Windows 2000 Professional.
guestId	string	Guest operating system configured on a virtual machine.
hostName	string	Hostname of the guest operating system, if known.
ipAddress	string	Primary IP address assigned to the guest operating system, if known.
toolsStatus	string	Current running status of VMware Tools in the guest operating system, if known.
toolsVersion	string	Current version status of VMware Tools in the guest operating system, if known.
Hardware
cpuCount	integer	Number of processors in the virtual machine.
coresPerSocket	integer	Number of cores used to distribute virtual CPUs among sockets in this virtual machine. If the value is unset it implies to numCoresPerSocket = 1.
memoryMB	integer	Memory size of the virtual machine, in megabytes.
numEthernetCards	integer	Number of virtual network adapters.
numVirtualDisks	integer	Number of virtual disks attached to the virtual machine.
devices	string	List of strings holding controllers, cd/dvd, disks and nics configured in the VM
version	string	The version string for this virtual machine.
Storage	Storage summary
provisionedGB	integer	Sum of Committed and Uncommitted storage.
uncommittedGB	integer	Additional storage space, in bytes, potentially used by this virtual machine on all datastores.
committedGB	integer	Total storage space, in bytes, committed to this virtual machine across all datastores.
unsharedGB	integer	Total storage space, in bytes, occupied by the virtual machine across all datastores, that is not shared with any other virtual machine.
Status	Runtime status related attributes
overallStatus	string	Overall alarm status on this node.
powerState	string	The current power state of the virtual machine.
alarms	boolean	Whether the VM has triggered alarms.
bootTime	String	The timestamp when the virtual machine was most recently powered on.
VSS	VSS Management tags
Admin	string	Admin responsible of this VM.
Inform	string	Informational contacts to be notified.
Requested	string	The timestamp when the virtual machine was requested.
Client	string	Custom client key-value notes.

The following example, requests information about a particular VM using its base resource /vm/ and appending the UUID to get the URI /vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db/.

http -a $TK GET https://vss-api.eis.utoronto.ca:8001/v2/vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db/

{
    "_links": {
        ....
    }, 
    "data": {
        "config": {
            "bootDelayMs": 5000, 
            "hotaddCpu": true, 
            "hotaddMem": true, 
            "hotremoveCpu": false
        }, 
        "folder": {
            "name": "jm", 
            "parent": "Sandbox", 
            "path": "Public > Sandbox > jm"
        }, 
        "guest": {
            "guestFullName": "Ubuntu Linux (64-bit)", 
            "guestId": "ubuntu64Guest", 
            "hostName": null, 
            "ipAddress": null, 
            "toolsStatus": "guestToolsNotInstalled", 
            "toolsVersion": null
        }, 
        "hardware": {
            "coresPerSocket": 1, 
            "cpuCount": 2, 
            "devices": {
                "cds": [], 
                "controllers": [
                    "IDE 0;IDE 0", 
                    "IDE 1;IDE 1", 
                    "SCSI controller 0;LSI Logic"
                ], 
                "disks": [
                    "Hard disk 1;Thin;4GB", 
                    "Hard disk 2;Thin;2GB", 
                    "Hard disk 3;Thin;1GB"
                ], 
                "nics": [
                    "Network adapter 1;Unused_Or_Quarantine_Veth;00:50:56:92:2b:bd", 
                    "Network adapter 2;VL-1102-UTCS;00:50:56:92:11:38"
                ]
            }, 
            "memoryMB": 2048, 
            "numEthernetCards": 2, 
            "numVirtualDisks": 3, 
            "version": "vmx-10"
        }, 
        "name": "1604Q-VMTest_1", 
        "networks": [
            "Unused_Or_Quarantine_Veth", 
            "VL-1102-UTCS"
        ], 
        "snapshot": false, 
        "status": {
            "alarms": false, 
            "bootTime": "", 
            "overallStatus": "green", 
            "powerState": "poweredOff"
        }, 
        "storage": {
            "committedGB": 0, 
            "provisionedGB": 9, 
            "uncommittedGB": 9, 
            "unsharedGB": 0
        }, 
        "uuid": "5012bd15-c20c-a971-aa68-af1a3cf3d0db", 
        "vss": {
            "admin": "JM Lopez:416-123-123:jm@eis.utoronto.ca", 
            "client": "EIS", 
            "inform": "jm@eis.utoronto.ca", 
            "requested": "2016-04-01 10:38:07"
        }
    }, 
    "meta": {
        "count": 11, 
        "time": "0.48864s", 
        "user": "jm"
    }
}

Links list have been removed from the VM info section due to its size, however, in the next section we'll describe every single sub resource.