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/v2/vm" curl -X OPTIONS "https://vss-api.eis.utoronto.ca/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 | - |
| client | Client 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 contentlib | - | |
| 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 or array of objects | - | - | [40] [ {"capacity_gb": 40, "backing_mode": "persistent", "backing_sharing": "nosharing"} ] | - |
| 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 | - | Fault Domain | - |
| folder | Folder moId (Managed Object Identifier) | string | /v2/folder | - | - | |
| inform | Informational comma separated emails or list of email addresses. | string or list of strings | - | - | User's email submitting the request | - |
| iso | ISO image path to be mounted after creation | string | /v2/iso | - | 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 interface controller object. [{"network": "moref-or-name", "type": "valid-type"}]
Each network will be attached to a NIC type specified or if not, 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 | - |
| notes | Client notes to be stored in the annotation field. | string | - | - | - | - |
| source_vm | Source Virtual Machine Moref or Uuid. | string | - | - |
| |
| source_vm_snap_id | Clone virtual machine from source snapshot | integer | /v2/vm/<id>/snapshot | - | - | only with clone |
| source_clib | Source Deployable (VM or OVF) Content Library item name or ID. | string | /v2/contentlib/item | only with contentlib | ||
| source_template | Source Virtual Machine Template Moref or 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 |
| user_data | Cloud-init user_data to preconfigure the guest os upon first boot. Note: Experimental feature and currently tested with Ubuntu Cloud Images and VMware Photon OS. Only supported on OVA/OVF deployments. | string | - | - | - | - |
| extra_config | Allows to Set VMware guestinfo interface properties which are available to the VM guest operating system via VMware Tools. These properties are stored in the VMX file prefixed with "guestinfo.". | array of objects | - | - | - | - |
| custom_spec | Customize a guest operating system to prevent conflicts if virtual machines are identical after deployed. To customize the guest operating system, you must configure the virtual machine and guest to meet VMware Tools and virtual disk requirements. | dict | - | - | - | recommended with clone and template deployment |
| power_on | Power on virtual machine after successful deployment | boolean | - | False | - | - |
| ha_group | Create high availability group metadata (based on morefs) | array or string | /v2/vm | - | - | - |
| vss_options | Sets available VSS Options to virtual machine metadata. | array or string | /v2/vss/options | - | - | - |
| vss_service | Tags Virtual Machine with a specific predefined service. | string | /v2/vss/service | - | - | only for ITS users |
| retirement | Create a Retirement request for the virtual machine. The retirement request allows to set a retirement date for a virtual machine. There are currently two types:
Timedelta {
"value": {"type": "timedelta", "days": 4, "months": 6, "hours": 0},
"warning": {"days": 15}
}
Datetime {
"value": {"type": "datetime", "datetime": "2021-10-20 10:00"},
"warning": {"days": 15}
}
warning is optional but if not set, no notification will be sent to confirm or cancel retirement. | object | - | - | - | - |
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",
"client": "EIS",
"description": "Java web application.",
"folder": "group-v4122",
"networks": [{"network": "dvportgroup-95", "type": "e1000"}, {"network": "dvportgroup-92"}],
"disks": [40, 100],
"power_on": true
}
HTTPie
http POST "https://vss-api.eis.utoronto.ca/v2/vm" "Authorization: Bearer $TK" usage='Prod' os='ubuntu64Guest' built_from='os_install' client='EIS' description='Java web application.' folder='group-v4122' networks:='[{"network": "dvportgroup-95", "type": "e1000"}, {"network": "dvportgroup-92"}]' disks:='[40, 20]' power_on:=true
CURL
curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm" -d '{"usage": "Prod", "os": "ubuntu64Guest", "built_from": "os_install", "client": "EIS", "description": "Java web application.", "folder": "group-v4122", "networks": [{"network": "dvportgroup-95", "type": "e1000"}, {"network": "dvportgroup-92"}], "disks": [40, 100], "power_on": true}'
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/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:
{"": "EIS",
"built_from": "template",
"description": "Ubuntu cluster",
"os": "ubuntu64Guest",
"folder": "group-v4122",
"source_template": "50123c4c-c810-5c0f-6203-eac67f0cb7e8",
"names": ["Ubuntu1",
"Ubuntu2",
"Ubuntu3"],
"networks": [
{"network": "dvportgroup-95", "type": "e1000"},
{"network": "dvportgroup-92", "type": "vmxnet3"}
],
"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 POST "https://vss-api.eis.utoronto.ca/v2/vm" "Authorization: Bearer $TK" os='ubuntu64Guest' built_from='template' client='EIS' description='Ubuntu cluster' folder='group-v4122' networks:='[{"network": "dvportgroup-95", "type": "e1000"}, {"network": "dvportgroup-92"}]' disks:='[40, 100]' names:='["Ubuntu1", "Ubuntu2", "Ubuntu3"]' source_template=50123c4c-c810-5c0f-6203-eac67f0cb7e8
CURL
curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm" -d '{"client": "EIS", "built_from": "template", "description": "Ubuntu cluster", "os": "ubuntu64Guest", "folder": "group-v4122", "source_template": "50123c4c-c810-5c0f-6203-eac67f0cb7e8", "names": ["Ubuntu1", "Ubuntu2", "Ubuntu3"], "networks": [{"network": "dvportgroup-95", "type": "e1000"}, {"network": "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:
The following examples use HTTPie and CURL to request ALL Virtual Machine managed by given user without filters:
http GET "https://vss-api.eis.utoronto.ca/v2/vm" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm"
HTTP response data would look something like:
Included attributes are described in the following table:
| 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. |
| moref | string | Managed object reference of the vm |
| name | string | Virtual Machine name including VSS prefix. |
| guest_full_name | string | The full name of the guest operating system for the virtual machine. For example: Windows 2000 Professional. |
| guest_id | string | The guest operating system identifier. |
| ip_address | string | Primary IP address assigned to the guest operating system, if known. |
| hostname | string | Guest hostname. Provided only when VMware Tools is running. |
memoryGB | integer | Memory size of the virtual machine, in Gigabytes. |
cpu_count | integer | Number of processors in the virtual machine. |
overall_status | string | VM general "health" value:
|
| power_state | string | The current power state of the virtual machine. The state could be: poweredOff or poweredOn |
| provisioned_gb | integer | Sum of Committed and Uncommitted storage. |
| folder | object | Folder object which contains current VM |
| folder_moref | string | Folder managed object reference |
| tools_running_status | string | VMware Tools running status. |
| tools_version | string | VMware Tools version. |
| tools_version_status | string | VMware Tools version status. |
| version | string | Virtual hardware version. |
Paging
All requests to the /vm URL are paginated. The response body includes a 'meta.pages' key with everything to navigate through the results, for instance:
| Key | Description |
|---|---|
| first_url | Contain the URLs to navigate through results. |
| last_url | |
| prev_url | |
| next_url | |
| page | Current page |
| pages | Total number of pages |
| per_page | Results per page. Maximum 250; Default 10. |
| total | Total number of results |
Results per page can be set by including the parameter in the URL query, so we can get the desired number of elements per page, for example:
http GET "https://vss-api.eis.utoronto.ca/v2/vm?per_page=200" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm?per_page=1500"
Sorting
The resource provides also attribute sorting by adding the sort parameter in the URL query string in the following format:
sort=<field_name>,<asc|desc>
For example:
http GET "https://vss-api.eis.utoronto.ca/v2/vm?sort=name,desc" "Authorization: Bearer $TK" http GET "https://vss-api.eis.utoronto.ca/v2/vm?sort=uuid,asc" "Authorization: Bearer $TK"
Filtering
Virtual Machines can be filtered by adding the filter argument to the query string in the following format:
filter=<field_name>,<operator>,<value>
Operators can be:
| Operator | Description |
|---|---|
| eq | Equals |
| ne | Not equal |
| lt | Lower than |
| le | Lower equal |
| gt | Greater than |
| ge | Greater equal |
| like | Matching pattern |
| in | Match value in many items separated by commas |
Filter Virtual Machine resource by any of the following
| Attribute | Filter |
|---|---|
| name | name |
| ipAddress | ip_address |
| hostname | hostname |
| powerState | power_state |
| cpuCount | cpu_count |
| overallStatus | overall_status |
| toolsVersion | tools_version |
| toolsVersionStatus | tools_version_status |
| version | version |
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 GET "https://vss-api.eis.utoronto.ca/v2/vm?filter=name,like,%Test%" "Authorization: Bearer $TK" http GET "https://vss-api.eis.utoronto.ca/v2/vm?filter=ip_address,eq,10.2.1.2" "Authorization: Bearer $TK" http GET "https://vss-api.eis.utoronto.ca/v2/vm?filter=hostname,like,wiki.eis.utoronto.ca" "Authorization: Bearer $TK"
Filtering by name can be done as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm?filter=name,like,%Test%" "Authorization: Bearer $TK"
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 | |
| boot.delay_ms | 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. |
| os.guest_id | string | Operating system configured in the virtual machine |
| Folder | Logical Folder | |
| name | string | Immediate folder holding VM |
| parent | string | Parent folder holding the VM |
| path | string | Full path to immediate folder |
| moref | string | Managed object reference to parent folder |
| Guest | Guest status and configuration | |
| guest_full_name | string | This is the full name of the guest operating system for the virtual machine. For example: Windows 2000 Professional. |
| guest_id | string | Guest operating system configured on a virtual machine. |
| hostname | string | Hostname of the guest operating system, if known. |
| ip_address | string | List of IP address assigned to the guest operating system, if known. |
| tools_status | string | Current running status of VMware Tools in the guest operating system, if known. |
| Note | Virtual Machine Metadata | |
| note | string | Virtual Machine full annotation |
| client | string | Client notes |
| Name | ||
| full_name | string | VM full name including VSS prefix. |
| Hardware | Virtual Machine Hardware configuration | |
| cpu_count | integer | Number of processors in the virtual machine. |
| cores_per_socket | 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. |
| memory_mb | integer | Memory size of the virtual machine, in megabytes. |
| 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 | |
| provisioned_gb | integer | Sum of Committed and Uncommitted storage. |
| uncommitted_gb | integer | Additional storage space, in bytes, potentially used by this virtual machine on all datastores. |
| committed_gb | integer | Total storage space, in bytes, committed to this virtual machine across all datastores. |
| unshared_gb | integer | Total storage space, in bytes, occupied by the virtual machine across all datastores, that is not shared with any other virtual machine. |
| State | Runtime status related attributes | |
| overall_status | string | VM general "health" value:
|
| power_state | string | The current power state of the virtual machine. |
| alarms | boolean | Whether the VM has triggered alarms. |
| Snapshot | Virtual Machine Snapshot information | |
| exist | boolean | Whether the current virtual machine has Snapshots |
| VSS | VSS Metadata | |
| admin | string | Admin responsible of this VM. |
| client | string | Custom client key-value notes. |
http GET "https://vss-api.eis.utoronto.ca/v2/vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db" "Authorization: Bearer $TK"
HTTP response data would look something like:
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 DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607" "Authorization: Bearer $TK"
CURL
curl -H "Authorization: Bearer $TK" $TK -X DELETE "https://vss-api.eis.utoronto.ca/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/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: