Introduction
By sending requests to the Virtual Machine endpoint /v2/vm you can list, create, update or delete VMs. The Virtual Machine endpoint has the following methods available:
| Resource | URI | Description | GET | POST | PUT | DELETE |
|---|---|---|---|---|---|---|
| Virtual Machine | /vm | Virtual Machine management resource. Read, update, delete, create virtual machines. |  | | | |
OPTIONS HTTP method
Remember, you can also show what methods are allowed and method description, parameters, etc. by making a GET HTTP request to /v2/vm.
http OPTIONS "https://vss-api.eis.utoronto.ca:8001/v2/vm" curl -X OPTIONS "https://vss-api.eis.utoronto.ca:8001/v2/vm"
On this page:
Create
Single Virtual Machine
To create a new Virtual Machine, send a POST request to /v2/vm. The attribute values that must be set to successfully create a Virtual Machine are marked with a in the following table:
| Attribute | Description | Type | Ref URI | Options | Default | Required |
|---|---|---|---|---|---|---|
| admin_email | Administrator's email | string | - | - | User's email number submitting the request | |
| admin_name | Administrator's name | string | - | - | User's name number submitting the request | |
| admin_phone | Administrator's phone number | string | - | - | User's phone number submitting the request | |
| bill_dept | Billing Department | string | - | - | - | |
| built_from | Build process. If you are installing OS from scratch use os_install. Clone when deploying a VM from a running or powered off virtual Machine. Template gives the ability to deploy multiple VMs at the same time. | string | - | os_install clone template image | - | |
| cpu | CPU count | integer | - | - | 1 | |
| description | Short description of the service or application. This will be part of the annotations field. | string | - | - | - | |
| disks | Disks in GigaBytes. | array | - | - | [40] | |
| high_io | If set to true,VM will be created with a VMware Paravirtual SCSIController. PVSCSI controllers are best suited for environments, especially SAN environments, running I/O-intensive applications. | boolean | - | True False | False | |
| domain | Fault domain moId (Managed Object Identifier) | string | /v2/domain | - | Fualt Domain 3 | |
| folder | Folder moId (Managed Object Identifier) | string | /v2/folder | - | - | |
| inform | Informational comma separated emails | string | - | - | User's email number submitting the request | |
| iso | ISO image path to be mounted after creation | string | /v2/isos | - | None | |
| memory | Memory in GB | integer | - | - | 1 | |
| name | Human readable name without the VSS Prefix. This prefix will be added before creation. | string | - | - | Randomly generated | |
| networks | Network Managed Object Identifier (moId) array. Each network will be attached to a Network Adapter VMXNET3, the most recent virtual network device from VMware, and was designed from scratch for high performance and to support new features. | array | /v2/network | - | Unaccessible VLAN | |
| os | Supported guest operating system identifier. | string | /v2/os | - | - | |
| usage | Virtual Machine usage. Prod for Production, Test for testing, QA for Quality Assurance, and Dev for Development. | string | - | Prod Test QA Dev | Test | |
| source_vm | Source Virtual Machine Uuid. | string | /v2/vm
| - | - |
|
| source_template | Source Virtual Machine Template Uuid. | string | /v2/template | - | - | only with template |
| source_image | Source OVA/OVF Virtual Machine file stored in VSKEY-STOR | string | /v2/image | - | - | only with image |
A new virtual machine can be created with as few as the following attributes in JSON format:
{"usage": "Prod",
"os": "ubuntu64Guest",
"built_from": "os_install",
"bill_dept": "EIS",
"description": "Java web application.",
"folder": "group-v4122",
"networks": ["dvportgroup-95",
"dvportgroup-92"],
"disks": [40, 100]
}
HTTPie
http -a $TK POST "https://vss-api.eis.utoronto.ca:8001/v2/vm" usage='Prod' os='ubuntu64Guest' built_from='os_install' bill_dept='EIS' description='Java web application.' folder='group-v4122' networks:='["dvportgroup-95", "dvportgroup-92"]' disks:='[40, 20]'
CURL
curl -H "Content-Type: application/json" -u $TK -X POST "https://vss-api.eis.utoronto.ca:8001/v2/vm" -d '{"usage": "Prod", "os": "ubuntu64Guest", "built_from": "os_install", "bill_dept": "EIS", "description": "Java web application.", "folder": "group-v4122", "networks": ["dvportgroup-95", "dvportgroup-92"], "disks": [40, 100]}'
If the request was successfully submitted and all parameters were accepted, the following Response Status, Headers and body will be received:
HTTP/1.0 202 ACCEPTED Allow: HEAD, POST, OPTIONS, GET Content-Length: 364 Content-Type: application/json Date: Tue, 26 Apr 2016 18:24:23 GMT Location: https://vss-api.eis.utoronto.ca:8001/v2/request/task/fa276e28-a876-477a-ab40-0d2d84df9234 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7190 X-RateLimit-Reset: 1461697200
Note that you will receive as well additional Hypermedia links contained in the _links attribute. Request object is the new virtual machine creation request which stores all parameters previously submitted and Task, is the unique task in charged of processing your request. Request and Task are both related, in terms of status, errors and warnings. Request will store any status or errors caught by the task, also it will pass the recently created VM Uuid.
Task
Request processing is almost instantaneous, however you could check the task progress by making a HTTP GET request to any given /v2/request/task/<task_id> endpoint.
Request
Checking the overall status of the request and also the resulting Uuid can be done by making a HTTP GET request to /v2/request/new/8 endpoint:
Multiple Virtual Machines
To create multiple Virtual Machines, send a POST request to /v2/vm. Creating multiple VMs is quite similar to creating a single VM, but instead of sending name as a string, send names as an array and select the right built process, either clone or template. The following request body is used to deploy three VM from a VM template:
{"bill_dept": "EIS",
"built_from": "template",
"description": "Ubuntu cluster",
"os": "ubuntu64Guest",
"folder": "group-v4122",
"source_template": "50123c4c-c810-5c0f-6203-eac67f0cb7e8",
"names": ["Ubuntu1",
"Ubuntu2",
"Ubuntu3"],
"networks": ["dvportgroup-95",
"dvportgroup-92"],
"disks": [40, 100]}
The main difference between selecting clone or template as built process is that a source VM Template can deploy multiple instances concurrently, whereas a VM Clone can only be deployed concurrently when the source Virtual Machine is powered off. If VM is powered On, it can only be cloned one at a time.
HTTPie
http -a $TK POST "https://vss-api.eis.utoronto.ca:8001/v2/vm" os='ubuntu64Guest' built_from='template' bill_dept='EIS' description='Ubuntu cluster' folder='group-v4122' networks:='["dvportgroup-95", "dvportgroup-92"]' disks:='[40, 100]' names:='["Ubuntu1", "Ubuntu2", "Ubuntu3"]' source_template=50123c4c-c810-5c0f-6203-eac67f0cb7e8
CURL
curl -H "Content-Type: application/json" -u $TK -X POST "https://vss-api.eis.utoronto.ca:8001/v2/vm" -d '{"bill_dept": "EIS", "built_from": "template", "description": "Ubuntu cluster", "os": "ubuntu64Guest", "folder": "group-v4122", "source_template": "50123c4c-c810-5c0f-6203-eac67f0cb7e8", "names": ["Ubuntu1", "Ubuntu2", "Ubuntu3"], "networks": ["dvportgroup-95", "dvportgroup-92"], "disks": [40, 100]}'
HTTP/1.0 202 ACCEPTED Allow: HEAD, POST, OPTIONS, GET Content-Length: 682 Content-Type: application/json Date: Wed, 27 Apr 2016 14:16:42 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7191 X-RateLimit-Reset: 1461769200
The main difference between single and multiple vm creation/deployment is the number of requests and tasks returned by the API. In this case, since we required three VMs, we get the same number of requests and tasks as a result of the POST request, which can be queried individually to verify its progress or result.
Task
Request processing is almost instantaneous, however you could check the task progress by making a HTTP GET request to any given /v2/request/task/<task_id> endpoint.
Requests
Checking the overall status of the requests and also the resulting Uuid can be done by making a HTTP GET request to /v2/request/new/26 - 28 endpoint:
List
Virtual machines
In order to list all your Virtual Machines you should make a HTTP GET request to the endpoint /v2/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 | VM general "health" value:
|
| powerState | string | The current power state of the virtual machine. |
| provisionedGB | integer | Sum of Committed and Uncommitted storage. |
The following examples use HTTPie and CURL to request ALL Virtual Machine managed by given user without filters:
http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/vm" curl -u $TK -X GET "https://vss-api.eis.utoronto.ca:8001/v2/vm"
HTTP response data would look something like:
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. |
| path | Inventory path in the following format EIS-DCB/vm/Public/jm/APIDemo/1605T-VMTest_1 |
| summary | Enables 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" http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/vm?path=EIS-DCB/vm/Public/jm/APIDemo/1605T-VMTest_1"
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=1"
HTTP response data would look something like:
From now on, you will need the UUID of any virtual machine, provided by the either the uuid attribute or in the "_links" section, to get further information and eventually to modify its configuration.
Specific virtual machine info
Some of the attributes will have an object value. Such is the case of guest, hardware, network, config and vss.
| 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 | VM general "health" value:
|
| 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. |
http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db"
HTTP response data would look something like:
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.
Delete
Single Virtual Machine
To delete an existent Virtual Machine, send a DELETE request to /v2/vm/<vm_uuid> and a change request to decommission requested VM will be submitted.
HTTPie
http -a $TK DELETE "https://vss-api.eis.utoronto.ca:8001/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607"
CURL
curl -u $TK -X DELETE "https://vss-api.eis.utoronto.ca:8001/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607"
HTTP/1.0 202 ACCEPTED Allow: HEAD, DELETE, OPTIONS, GET Content-Length: 398 Content-Type: application/json Date: Thu, 28 Apr 2016 15:32:55 GMT Location: https://vss-api.eis.utoronto.ca:8001/v2/request/task/7e8e4a7c-7c09-42d2-86e1-41ff5ea530c6 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7195 X-RateLimit-Reset: 1461859200
Task
Request processing is almost instantaneous, however you could check the task progress by making a HTTP GET request to any given /v2/request/task/<task_id> endpoint.
Requests
Checking the overall status of the requests and also its result can be done by making a HTTP GET request to /v2/request/change/26 - 28 endpoint: