Virtual Machine - Attributes
- JM Lopez
Summary
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH |
|---|---|---|---|---|---|---|---|
| CPU | /vm/<vm-id>/cpu | CPU resource. Get CPU count, quick stats and update cpu count |  | | |||
| CPU settings | /vm/<vm-id>/cpu/config | CPU settings. Get and update CPU Hot add/remove setting | | | |||
| Memory | /vm/<vm-id>/memory | Memory resource. Get Memory count, quick stats and update memory size | | | |||
| Firmware | /vm/<vm-id>/firmware | Get or update firmware type. | | | |||
| Disk | /vm/<vm-id>/disk | Disk resource. List, create and delete virtual disks. | | | | ||
| Disk Unit | /vm/<vm-id>/disk/<disk_number> | Get specific disk information such as size, controller, provisioning. List update and delete virtual Disk. | | | | ||
| Disk Unit Backing | /vm/<vm-id>/disk/<disk_number>/backing | Get physical VMDK file backing and more information. | | ||||
| Disk Unit SCSI controller | /vm/<vm-id>/disk/<disk_number>/scsi | Get and update SCSI adapter of a given disk unit | | | |||
| Disk Unit Sharing | /vm/<vm-id>/disk/<disk_number>/sharing | Get and update Disk Sharing | | | |||
| Controllers | /vm/<vm-id>/controller | IO Controllers including SCSI and IDE | | ||||
| SCSI Controllers | /vm/<vm-id>/controller/scsi | Available SCSI controllers in the VM. Create, list and delete SCSI controllers | | | | ||
| SCSI Controller | /vm/<vm-id>/controller/scsi/<bus> | Get a specific SCSI controller info. Update controller type or delete given controller | | | | ||
| Floppy | /vm/<vm-id>/floppy | Floppy resource. List available floppy units. | | ||||
| Floppy Number | /vm/<vm-id>/floppy/<unit> | List current Floppy unit and update backend configuration. | | | |||
| CD/DVD | /vm/<vm-id>/cd | CD/DVD resource. List VM cd/dvd units. | | ||||
| CD/DVD Number | /vm/<vm-id>/cd/<unit> | CD/DVD unit resource. List current CD/DVD unit and update backend configuration. | | | |||
| Boot Options | /vm/<vm-id>/boot | Boot resource. Get and update boot configuration options. | | | |||
| Logical Folder | /vm/<vm-id>/folder | Logical Folder resource. Get and update containing folder. | | | |||
| Name | /vm/<vm-id>/name | Instance name. List and update assigned name without VSS prefix | | | |||
| Network Interface Card | /vm/<vm-id>/nic | Network interface list. | | | | ||
| Network Interface Card Number | /vm/<vm-id>/nic/<unit> | Network interface unit. List, create, update or delete NIC. | | | | ||
| Template | /vm/<vm_uuid/template | Template state. Mark VM as template or template as VM. | | | |||
| Operating System | /vm/<vm_uuid/os | Configured Operating System | | | |||
| Guest | /vm/<vm-id>/guest | Running Guest related configuration | | ||||
| Guest Operating System | /vm/<vm-id>/guest/os | Running Operating System configuration | | | |||
| Guest VMware Tools | /vm/<vm-id>/guest/tools | Guest VMware Tools configuration. | | | |||
| Guest Network | /vm/<vm-id>/guest/net | Guest network configuration. | | ||||
| Guest Network IP | /vm/<vm-id>/guest/net/ip | Guest network Ip address configuration. | | ||||
| Guest Process | /vm/<vm-id>/guest/cmd | Guest running processes or execute program | | | |||
| Guest Process ID | /vm/<vm-id>/guest/cmd/<pid> | Guest process management | | | | ||
| State | /vm/<vm-id>/state | Power state. | | | |||
| Domain | /vm/<vm-id>/domain | Fault domain. | | | |||
| Triggered Alarms | /vm/<vm-id>/alarm /vm/<vm-id>/alarm/<moref> | Triggered Alarms. Shows list of triggered alarms. Specific Triggered Alarms. Lists, clears and acknowledges alarm. | | | |||
| Events | /vm/<vm-id>/event /vm/<vm-id>/alarm/<hour_window> | Instance related vCenter events within 1 hour by default. | | ||||
| Note | /vm/<vm-id>/note | Instance Annotation. List raw virtual Machine annotation. | | ||||
| Client Notes | /vm/<vm-id>/note/client | Metadata Client custom notes if any. | | | |||
| Snapshots | /vm/<vm-id>/snapshot /vm/<vm-id>/snapshot/<snapshot_id> | Virtual Machine Snapshot resource. List or create VM snapshots. List, delete and restore from <snapshot_id> | | | | | |
| Disk Consolidation | /vm/<vm-id>/snapshot/consolidate | Disk consolidation status. List if disk consolidation is required and execute consolidation | | | |||
| Performance | /vm/<vm-id>/performance | Performance statistics, including datastore IO, memory, CPU and network. | | ||||
| Console | /vm/<vm-id>/console | HTML5 one-time console link. | | ||||
| Export | /vm/<vm-id>/export | OVF export action to vskey-stor. | | ||||
| VMX Version | /vm/<vm-id>/version | Virtual hardware version and upgrade policy. | | | |||
| Extra Configuration | /vm/<vm-id>/extra-config | Manage VMware **guestinfo** interface options, which are available to the VM guest operating system via VMware Tools. | | | | | |
| VSS | /vm/<vm-id>/vss | VSS related metadata. | | ||||
| VSS Admin | /vm/<vm-id>/vss/admin | Administrator. List or update VM admin name and contact info. | | | |||
| VSS Inform | /vm/<vm-id>/vss/inform | Informational contacts. List or update VM informational contacts. | | | |||
| VSS Usage | /vm/<vm-id>/vss/usage | Instance designated usage. | | | |||
| VSS HA Group | /vm/<vm-id>/vss/ha-group | HA group metadata. | | | | ||
| VSS Client | /vm/<vm-id>/vss/client | Client Department | | | |||
| VSS Description | /vm/<vm-id>/vss/description | Description | | | |||
| VSS Options | /vm/<vm-id>/vss/option | VSS Options | | | | | |
| VSS Service | /vm/<vm-id>/vss/service | VSS Service. | | | | ||
| Configuration specification | /vm/<vm-id>/spec | Instance spec. Will dump VM specifications (shell). | | | |||
| Guest OS Customization Specification | /vm/<vm-id>/custom-spec | Guest os customization specification. | |
<vm-id> is either Managed Object Reference Id or UUID.
TK stores the Cloud API Token generated as a result of the following POST request to the /auth/request-token resource:
curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username>
For example, extracting the token with the jq command:
TK=$(curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username> | jq '.token')
CPU
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* |
|---|---|---|---|---|---|---|---|
| CPU | /vm/<vm-id>/cpu | Virtual Machine CPU resource. Get CPU count, quick stats and update cpu count | | | |
Info
Requesting cpu info can be as easy as making a GET request to /vm/<vm-id>/cpu as shown below:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu"
Respose from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 385 Content-Type: application/json Date: Wed, 27 Apr 2016 17:47:28 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7179 X-RateLimit-Reset: 1461780000
Update
Increasing or decreasing CPU and Cores Per Socket can be done by making a PUT request to /vm/<vm-id>/cpu as shown below:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" value:=3 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" -d '{"value": 3}'
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" -d '{"value": {"count": 4, "cores_per_socket": 2}}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Content-Length: 397 Content-Type: application/json Date: Wed, 27 Apr 2016 18:15:08 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/827f4a45-db84-4799-b2f8-a02c85e003be X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7197 X-RateLimit-Reset: 1461783600
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Memory
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* |
|---|---|---|---|---|---|---|---|
| Memory | /vm/<vm-id>/memory | Virtual Machine Memory resource. Get Memory count, quick stats and update memory size | | | |
Info
Requesting memory info can be as easy as making a GET request to /vm/<vm-id>/memory as shown below:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 555 Content-Type: application/json Date: Wed, 27 Apr 2016 18:21:25 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7193 X-RateLimit-Reset: 1461783600
Update
Increasing or decreasing CPU can be done by making a PUT request to /vm/<vm-id>/memory as shown below:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory" value:=3 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory" -d '{"value": 3}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Content-Length: 397 Content-Type: application/json Date: Wed, 27 Apr 2016 18:15:08 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/0f39fa9f-4f35-426a-8ebb-8f1b34588fef X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7197 X-RateLimit-Reset: 1461783600
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Virtual Disk
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* |
|---|---|---|---|---|---|---|---|
| Disk | /vm/<vm-id>/disk | Virtual Machine disk resource. Get VM disks, and capacity. | | | | | |
| Disk Number | /vm/<vm-id>/disk/<disk_number> | Virtual Machine disk resource. Get specific disk information such as size, controller, provisioning. Update size or delete. | | | | |
List
Virtual Disks can be listed by a GET request to /v2/<vm-id>/disk resource. You will get the list of disks and the Hypermedia reference to the every disk available in the VM:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, OPTIONS, GET Content-Length: 652 Content-Type: application/json Date: Wed, 27 Apr 2016 18:26:42 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7188 X-RateLimit-Reset: 1461783600
Info
Displaying specific information of a disk such as controller, backing file, provisioning, capacity, etc. can be done by a GET request to /v2/vm/<vm-id>/disk/<disk_number> as shown below:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 688 Content-Type: application/json Date: Wed, 27 Apr 2016 18:37:30 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7186 X-RateLimit-Reset: 1461783600
If requested disk does not exist, you'll get a 404 response status as follows:
Update
PUT request to /vm/<vm-id>/disk/<disk_number> will submit a change request to update capacity. The following JSON object is expected as request body:
{"attribute": "capacity",
"value": 200}
The value of the key value is the new size of the Disk in GB.
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" attribute=capacity value=200 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" -d '{"attribute": "capacity", "value": 200}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 397 Content-Type: application/json Date: Wed, 27 Apr 2016 18:58:10 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/2f2b7baf-3abf-48f1-8d16-9dc63641a800 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7178 X-RateLimit-Reset: 1461783600
Create
A POST request should be made to /vm/<vm-id>/disk in order to create a disk or multiple with the following JSON object as request body:
{"value": [80, 100, 100]}
The value of the key value is either the new size of the Disk in GB or for advanced setup, the following object structure:
[{"capacity_gb": 80, "backing_mode": "persistent", "backing_sharing": "sharingnone" "backing_vmdk": "<vssUsers_path>"}]
http POST "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" value:='[80, 100, 100]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" -d '{"value": [80, 100, 100]}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 397 Content-Type: application/json Date: Wed, 27 Apr 2016 18:52:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/4ecfa88d-1d1a-44fa-bb9b-d0ab04c17691 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7180 X-RateLimit-Reset: 1461783600
Delete
To delete a disk or multiple disks you must submit a DELETE request to /vm/<vm-id>/disk/<disk_number> with no request body as follows:
# Just one disk
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1"
# Disk labels in array
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" value:='[2,3]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" -d '{"value": [2,3]}'
This action cannot be undone.
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 397 Content-Type: application/json Date: Wed, 27 Apr 2016 18:52:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/4ecfa88d-1d1a-44fa-bb9b-d0ab04c17691 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7180 X-RateLimit-Reset: 1461783600
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Floppy
List
Virtual Floppy units are listed by making a GET request to /v2/<vm_uuid/floppy which will return a list of available units to display further information from:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy"
Response from the API would look something like:
HTTP/1.1 200 OK Allow: HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 521 Content-Type: application/json Date: Mon, 27 Jun 2016 15:14:16 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2999 X-RateLimit-Reset: 1467043200
In this particular case, the floppy unit has no image as backend device.
Info
Displaying specific information of a disk such as controller, backing file, etc. can be done by a GET request to /v2/vm/<vm-id>/floppy/<floppy_number> as shown below:
Response from the API would look something like:
HTTP/1.1 200 OK Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 620 Content-Type: application/json Date: Mon, 27 Jun 2016 15:16:38 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2998 X-RateLimit-Reset: 1467043200
Update
Virtual Floppy units are not quite used as CD/DVDs, however, when the operating system is Windows and the VM has been configured with Paravirtual SCSI (PVSCSI) controllers, the installer requires to load VMwrare drivers to successfully see all virtual disks attached to PVSCSI controller. The drivers are available to mount from all ESXi hosts in [] /vmimages/floppies.
A PUT request to /vm/<vm-id>/floppy/<floppy_number> will submit a change request to update device backing, meaning client or floppy image. The following JSON object is expected as request body:
# floppy image
{"attribute": "img",
"value": "[] /vmimages/floppies/pvscsi-Windows2008.flp"}
# client
{"attribute": "client",
"value": ""}
Making the HTTP request would look like:
httpPUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy/1" attribute=img value='[] /vmimages/floppies/pvscsi-Windows2008.flp' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy/1" -d '{"attribute": "img", "value": "[] /vmimages/floppies/pvscsi-Windows2008.flp"}'
Response from the API would look something like:
HTTP/1.1 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 431 Content-Type: application/json Date: Mon, 27 Jun 2016 15:20:10 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/6e52bcc5-0abf-4f12-89ab-5f1e4f17b896 Server: nginx X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2997 X-RateLimit-Reset: 1467043200
CD/DVD
List
Virtual CD/DVD units can be listed by a GET request to /v2/<vm-id>/cd resource. You will get the list of cd/dvd and the Hypermedia reference to the every unit available in the VM:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, OPTIONS, GET Content-Length: 652 Content-Type: application/json Date: Wed, 27 Apr 2016 18:26:42 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7188 X-RateLimit-Reset: 1461783600
Info
Displaying specific information of a disk such as controller, backing file, etc. can be done by a GET request to /v2/vm/<vm-id>/cd/<cd_number> as shown below:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 688 Content-Type: application/json Date: Wed, 27 Apr 2016 18:37:30 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7186 X-RateLimit-Reset: 1461783600
If requested a non existent CD/DVD unit, you'll get a 404 response status as follows:
Update
A PUT request to /vm/<vm-id>/cd/<cd_number> will submit a change request to update device backing, meaning client or iso image. The following JSON object is expected as request body:
# iso image
{"attribute": "iso",
"value": "[vss-ISOs] Windows/W10/Win10_English_x32.iso"}
# client
{"attribute": "client",
"value": ""}
The ISO API resource provides a list of available ISOs to mount to the VM.
Making the HTTP request would look like:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1" attribute=iso value='[vss-ISOs] Windows/W10/Win10_English_x32.iso' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1" -d '{"attribute": "iso", "value": "[vss-ISOs] Windows/W10/Win10_English_x32.iso"}'
Response from the API would look something like:
HTTP/1.1 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 428 Content-Type: application/json Date: Fri, 20 May 2016 18:04:41 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/9b815488-e0d9-4b60-a94f-fe9b0fe46ec7 Server: nginx X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2993 X-RateLimit-Reset: 1463770800
Boot Options
The time when you power on the virtual machine, shows up the BIOS and launches the guest operating system software can be unnoticeable, because by default VMware sets up 0ms as boot delay. However, you can edit boot delay options to change that amount of time or to force the virtual machine to enter the BIOS setup screen after power on. This is done using the Boot resource in the RESTful API /vm/<vm-id>/boot.
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* |
|---|---|---|---|---|---|---|---|
| Boot Options | /vm/<vm-id>/boot | Virtual Machine Boot resource. Get and update boot configuration options. | | | |
Info
Showing what's currently configured as boot options is done by making a GET request to /vm/<vm-id>/boot as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 366 Content-Type: application/json Date: Wed, 27 Apr 2016 19:07:54 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7199 X-RateLimit-Reset: 1461787200
Update
Submitting a HTTP request using PUT to /vm/<vm-id>/boot is used to update two boot options: bootdelay, to change that amount of time from powering on to boot into the main device in milliseconds and bootbios, which will force to boot directly to the BIOS setup, boolean. The request body expected is a JSON object as follows:
# boot delay data
{"attribute": "bootdelay",
"value": 10000}
# boot to bios data
{"attribute": "bootbios",
"value": true}
Updating VMs boot delay can be done as shown below:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot" attribute=bootdelay value=10000 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot" -d '{"attribute": "bootdelay", "value": 10000}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Content-Length: 397 Content-Type: application/json Date: Wed, 27 Apr 2016 19:33:47 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/f5de4b0d-6f00-44ae-870a-e2858134b6d0 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7197 X-RateLimit-Reset: 1461787200
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Logical Folder
This sub resource provides access to containing logical folder object in vCenter.
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* |
|---|---|---|---|---|---|---|---|
| Folder | /vm/<vm-id>/folder | Virtual Machine containing Folder resource. Get and update containing folder. | | | |
Info
Querying which folder is this VM on is done by doing a GET request to /v2/vm/<vm-id>/folder.
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 508 Content-Type: application/json Date: Wed, 27 Apr 2016 19:42:16 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7196 X-RateLimit-Reset: 1461787200
The result will provide basic info about the folder such as name, parent and full path. Also, it provides a Hypermedia resource to the main /v2/folder/<moref> resource.
Update
Moving a VM to a specific logical folder is done by making a PUT request to /v2/vm/<vm-id>/folder with the moref (Managed object Reference) of the target folder, which can be obtained from the /v2/folder/ resource. The request body expected is a JSON object as shown below:
{"value": "group-v6736"}
Submitting a change request to update VMs logical folder can be done as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder" value=group-v6736 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder" -d '{"value": "group-v6736"}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Content-Length: 398 Content-Type: application/json Date: Wed, 27 Apr 2016 19:57:45 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/b3a2c488-ebdb-4d27-9ceb-a5c1d3085672 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7192 X-RateLimit-Reset: 1461787200
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Name
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* |
|---|---|---|---|---|---|---|---|
| Name | /vm/<vm-id>/name | Virtual Machine human readable name. List and update assigned name without VSS prefix | | | |
Info
Requesting Name info can be as easy as making a GET request to /vm/<vm-id>/name as shown below:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name"
Respose from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 309 Content-Type: application/json Date: Thu, 28 Apr 2016 19:34:48 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7199 X-RateLimit-Reset: 1461873600
Update
Renaming a Virtual Machine can be done by making a PUT request to /vm/<vm-id>/name as shown below:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name" value=Ubuntu4 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name" -d '{"value": "Ubuntu4"}'
VSS prefix must not be included, if included the API will return a 400 error:
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Content-Length: 398 Content-Type: application/json Date: Thu, 28 Apr 2016 17:46:12 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/e84558b9-4d18-41d2-9f4f-3ec873d37441 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7194 X-RateLimit-Reset: 1461866400
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Network Interface Card
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* |
|---|---|---|---|---|---|---|---|
| NIC | /vm/<vm-id>/nic | Virtual Machine nic resource. Get VM nic list. | | | | | |
| NIC Number | /vm/<vm-id>/nic/<nic_number> | Virtual Machine specific network interface. List, create, update or delete NIC. | | | | |
List
Virtual machine nics can be listed making a GET request to /v2/<vm-id>/nic resource. You will get the list of nics and the Hypermedia reference to the actual nic for further actions and properties.
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/nic" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/nic"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, OPTIONS, GET Content-Length: 820 Content-Type: application/json Date: Thu, 28 Apr 2016 20:42:39 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7184 X-RateLimit-Reset: 1461877200
Info
Displaying NIC specific information such as connection state, network, type, etc. can be done by making a GET request to /v2/vm/<vm-id>/nic/<nic_number> as shown below:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 534 Content-Type: application/json Date: Thu, 28 Apr 2016 20:47:35 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7181 X-RateLimit-Reset: 1461877200
If requested nic does not exist, you'll get a 404 response status as follows:
Update
There are two updates available to Network Interface Cards: network, state, type. Backend network updates require the Network Managed Object Reference which can be got from /v2/network/ resource, such as dvportgroup-00. NIC state on the other hand, has two options connect and disconnect given NIC. Finally, NIC type means which network adapter should be used between vmxnet3, vmxnet3, e1000, e1000e. Updates to NICs should be made by making a PUT request to /vm/<vm-id>/nic/<nic_number> with the following JSON object as request body:
# update network backend
{"attribute": "network",
"value": "dvportgroup-00"}
# update state
{"attribute": "state",
"value": "connect"}
# update nic adapter
{"attribute": "type",
"value": "vmxnet2"}
For instance, updating NIC 1 type to VMXNET2 is done as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" attribute=type value=VMXNET2 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" -d '{"attribute": "type", "value": "vmxnet2"}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 398 Content-Type: application/json Date: Thu, 28 Apr 2016 20:59:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/e6f4313c-5ffa-4e8c-8c52-b368cd08aa62 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7173 X-RateLimit-Reset: 1461877200
Create
A POST request should be submitted to /vm/<vm-id>/nic in order to create Network Interface Controllers with the Network MOREFs and Network Type in an array as value of the value key in JSON object sent as request body:
{"value": [{"network": "dvportgroup-00"}, {"network": "dvportgroup-01", "type": "vmxnet2"}]}
The value attribute is the Network MOREF.
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic" -d '{"value": [{"network": "dvportgroup-00"}, {"network": "dvportgroup-01", "type": "vmxnet2"}]}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 398 Content-Type: application/json Date: Fri, 29 Apr 2016 02:07:51 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/20e01be9-b91e-4db2-9e0d-66dbe602b536 X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7194 X-RateLimit-Reset: 1461898800
Delete
To delete a NIC you must submit a DELETE request to /vm/<vm-id>/nic/<nic_number> with no request body as follows:
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1"
# multiple nic deletion delting network adapter 2 and 3
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic" value:='[2, 3]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic" -d '{2, 3}'
This action cannot be undone.
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Length: 398 Content-Type: application/json Date: Fri, 29 Apr 2016 02:05:36 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/372da560-bc66-4ffa-a97e-f0b160a1e26f X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7195 X-RateLimit-Reset: 1461898800
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Template
Virtual Machine Templates are useful If you create a virtual machine that you want to clone frequently, offering a more secure way of preserving a virtual machine configuration, since they are more difficult to alter than ordinary virtual machine. Templates are commonly referred as Master Copy of certain virtual machine, thus any virtual machine can be marked as template.
| Resource | URI | Description | GET | POST | PUT | DELETE | OPTIONS* | |
|---|---|---|---|---|---|---|---|---|
| Template | /vm/<vm_uuid/template | Virtual Machine Template state. Mark VM as template or template as VM. | | | |
Info
In order to verify whether a virtual machine has been marked as template or can be used as template, you just need to submit a GET request to /vm/<vm-id>/template endpoint, resulting in a JSON object with just one attribute: isTemplate which could be either True or False.
http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 422 Content-Type: application/json Date: Fri, 29 Apr 2016 02:22:26 GMT X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7193 X-RateLimit-Reset: 1461898800
Update
Marking a VM as Template or a Template as VM can be done using the PUT method to the template URI /vm/<vm-id>/template. In this case a boolean has to be included as value of the value key in JSON object sent as request body:
# mark vm as template
{"value": true}
# mark template as vm
{"value": false }
The following example demonstrate how to craft the HTTP request:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template" value=true "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template" -d '{"value": true}'
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Content-Length: 398 Content-Type: application/json Date: Fri, 29 Apr 2016 02:31:47 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/07bfff5d-d2e6-4a09-a85c-d1cc847eabfc X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7191 X-RateLimit-Reset: 1461898800
Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.
Operating System
The virtual machine hardware is presented to the guest operating system based on this setting. It's highly recommended to match the guest OS name or type to ensure the best compatibility and operation.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| OS | /vm/<vm-id>/os | Virtual Machine OS configuration | | |
Info
To obtain the configured operating system, a GET request to the /vm/<vm-id>/os endpoint and the response would include the following attributes:
| Attribute | Type | Description |
|---|---|---|
| full_name | string | Operating System full name |
| guest_id | string | Operating system identifier |
The following example demonstrate how to query OS information of a given VM:
http GET https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os"
Response from the API would look something like:
HTTP/1.1 200 OK Allow: HEAD, OPTIONS, GET, PUT Connection: keep-alive Content-Length: 315 Content-Type: application/json Date: Fri, 01 May 2020 13:53:24 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4997 X-RateLimit-Reset: 1588341600 X-VssApi-AppServer: vss-api-prod X-VssApi-Version: v3.8.1
Update
To reconfigure the instance operating system make a PUT request to /v2/vm/<vm-id>/os wtih the following payload:
{"value": "guest_id"}
Where guest_id can be obtained from the /v2/os resource, for instance:
http GET "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,Ubuntu%" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os?filter=full_name,like,Ubuntu%"
Updating the instance operating system would include the guest_id provided:
Virtual Machine must be powered Off.
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os" value=ubuntu64Guest "Authorizatio: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os" -d '{"value": "ubuntu64Guest"}'
Response from the API would look something like:
HTTP/1.1 202 ACCEPTED Allow: HEAD, OPTIONS, GET, PUT Cache-Control: private, no-cache, no-store, max-age=0 Connection: keep-alive Content-Length: 518 Content-Type: application/json Date: Fri, 01 May 2020 14:31:59 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/9a65b490-23cb-4192-96c2-7d5da94341c7 Server: nginx X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4993 X-RateLimit-Reset: 1588345200 X-VssApi-AppServer: vss-api-prod X-VssApi-Version: v3.8.1
Guest
Guest related attributes are handled by the /v2/<vm-id>/guest resource, this includes hostname, guest state, main ip address, network configuration, VMware Tools status and Operating System configured.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Guest | /vm/<vm-id>/guest | Virtual Machine Guest related configuration | | |
Info
To display guest information, do a GET request to /vm/<vm-id>/guest endpoint, resulting in a JSON object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| guest_pperations_ready | boolean | Guest Operations availability. If true, the virtual machine is ready to process guest operations. |
| guest_state | string | Operation mode of guest operating system. One of:
|
| hostname | string | Main hostname if any. Requires VMware Tools or equivalent installed and running. |
| ip_address | string | List of ip addresses. Requires VMware Tools or equivalent installed and running. |
| network | object | Reference to Guest Network configuration resource. |
| os | object | Reference to Operating System resource and guestId. |
| tools | object | Reference to VMware Tools detailed status and current running status. |
The following example demonstrate how to query Guest basic information of a given VM:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest"
Response from the API would look something like:
HTTP/1.1 200 OK Allow: OPTIONS, GET, HEAD Connection: keep-alive Content-Length: 1204 Content-Type: application/json Date: Fri, 01 May 2020 14:33:08 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4991 X-RateLimit-Reset: 1588345200 X-VssApi-AppServer: vss-api-prod X-VssApi-Version: v3.8.1
Guest Operating System
Guest Operating System related attributes are handled by the /v2/<vm-id>/guest/os resource, this includes guest family, guest full name and guest id.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Guest Operating System | /vm/<vm-id>/guest/os | Virtual Machine Guest Operating System configuration | | |
Info
To display guest operating system information, do a GET request to /vm/<vm-id>/guest/os endpoint, resulting in a JSON object with the following attributes:
| Name | Type | Description |
|---|---|---|
| guest_family | string | Guest operating system family, if known. |
| guest_full_name | string | Guest operating system full name, if known. |
| guest_id | string | Guest operating system identifier (short name), if known. |
The following example demonstrate how to query Guest basic information of a given VM:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/os" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/os"
Response from the API would look something like:
HTTP/1.1 200 OK Allow: OPTIONS, GET, HEAD Connection: keep-alive Content-Length: 371 Content-Type: application/json Date: Fri, 01 May 2020 14:34:36 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4990 X-RateLimit-Reset: 1588345200 X-VssApi-AppServer: vss-api-prod X-VssApi-Version: v3.8.1
Guest VMware Tools
VMware Tools is a suite of utilities that enhances the performance of the virtual machines guest operating system and improves management of the virtual machine (Source: VMware). With this resource, you can display current guest operating system VMware Tools status including its running status, installation status, and version status. Also, it provides an interface to mount, unmount and even upgrade from the packaged version in vSphere.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Guest VMware Tools | /vm/<vm-id>/guest/tools | Virtual Machine Guest VMware Tools configuration. | | | |
Info
To display the guest operating system VMware Tools information, do a GET request to /vm/<vm-id>/guest/tools endpoint, resulting in a JSON object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| running_status | string | Current running status of VMware Tools in the guest operating system, if known.
Source: VMware. |
| version | string | Current version of VMware Tools, if known. |
| version_status | string | Current version status of VMware Tools in the guest operating system, if known.
Source VMware. |
The following example demonstrate how to query VMware Tools information of a given VM:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/5012accf-3e3d-a5f5-32cf-8a9d4c2ddc25/guest/tools" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/5012accf-3e3d-a5f5-32cf-8a9d4c2ddc25/guest/tools"
Response from the API would look something like:
HTTP/1.1 200 OK Allow: HEAD, OPTIONS, GET, PUT Connection: keep-alive Content-Length: 373 Content-Type: application/json Date: Fri, 01 May 2020 14:35:28 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4989 X-RateLimit-Reset: 1588345200 X-VssApi-AppServer: vss-api-prod X-VssApi-Version: v3.8.1
Update
Making a PUT request to /v2/<vm-id>/guest/tools would Mount, Unmount and Upgrade only vSphere packaged versions of VMware Tools. These tasks are commonly executed on virtual machines with Windows based guest operating systems. For popular Linux based VMs, VMware recommends to use Open VM Tools (open-vm-tools) which is the open source implementation of VMware Tools, however if there is any particular Linux distribution without OVTs available, it should use vSphere packaged version.
Changes to tis resource require the VM to be powered on. Otherwise, the following error will be thrown by the API:
In order to mount, unmount and automatically upgrade vSphere packaged VMware Tools version, the following JSON object with the attribute value should be sent via a PUT request to /v2/vm/<vm-id>/guest/tools:
{"value": 'mount'}
{"value": 'unmount'}
{"value": 'upgrade'}
For demonstration purposes, the following example will mount and unmount vSphere packaged VMware Tools version.
The following example demonstrate how to craft the HTTP request:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" value=mount "Authorization: Bearer $TK" http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" value=unmount "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" -d '{"value": "mount"}'
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" -d '{"value": "unmount"}'
Response from the API would look something like:
HTTP/1.1 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 427 Content-Type: application/json Date: Tue, 03 May 2016 01:59:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7194 X-RateLimit-Reset: 1462240800
Guest Network
VMware Tools provides an interface between the Hypervisor and the Guest Operating System, so there's certain information that can be pulled from the OS such as networking configuration including IP and Mac addresses, virtual network and connection state. This information can be gotten by the /v2/<vm-id>/guest/net resource:
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Guest Network | /vm/<vm-id>/guest/net | Virtual Machine Guest network configuration. | | |
Info
To display the network information provided by the Guest OS, do a GET request to /vm/<vm-id>/guest/net endpoint, resulting in a JSON object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| connected | boolean | Flag indicating whether or not the virtual device is connected. |
| ipAddress | array | IPv4 address is specified using dotted decimal notation. For example, "192.0.2.1". IPv6 addresses are 128-bit addresses represented as eight fields of up to four hexadecimal digits. A colon separates each field (:). For example, 2001:DB8:101::230:6eff:fe04:d9ff. The address can also consist of the symbol '::' to represent multiple 16-bit groups of contiguous 0's only once in an address as described in RFC 2373. |
| macAddress | string | MAC address of the adapter. |
| nic | string | Reference to nic associated |
The following example demonstrate how to query Network information of a given VM:
http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Guest Network IP
Guest operating system network ip addresses configuration reported via VMware tools.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Guest Network IP | /vm/<vm-id>/guest/net/ip | Virtual Machine Guest network IP configuration. | | |
Info
| Attribute | Type | Description |
|---|---|---|
| origin | string | How this address was configured:
|
| ipAddress | array | IPv4 address is specified using dotted decimal notation. For example, "192.0.2.1". IPv6 addresses are 128-bit addresses represented as eight fields of up to four hexadecimal digits. A colon separates each field (:). |
| macAddress | string | MAC address of the adapter. |
| state | string | The state of ipAddress:
|
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net/ip" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net/ip"
The following response body is expected from the API:
Guest Process
Processes running in the guest operating system can be listed using the API via VMware Tools. If VMware Tools has not been installed or is not running, this resource will not work properly.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
Guest Process | /vm/<vm-id>/guest/cmd | Virtual Machine running processes. | | | | | ||
| Guest Process ID | /vm/<vm-id>/guest/cmd/<pid> | Virtual Machine Guest OS running process ID | | | | |
Info
To list running processes the following JSON object must be provided:
| Attribute | Type | Description | Required |
|---|---|---|---|
| user | string | Guest OS username | |
| pass | string | Guest OS username password | |
Passwords are not save when querying processes but they are when submitting a command, however they are encrypted.
The following example demonstrate how to query running processes information of a given VM:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd" user='OSUser' pass='plain-text-pass' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd" -d '{"user": "OSUser", "pass": "plain-text-pass"}'
Response from the API would look something like:
HTTP/1.1 200 OK Allow: HEAD, POST, OPTIONS, GET Connection: keep-alive Content-Length: 13844 Content-Type: application/json Date: Tue, 12 Jul 2016 14:39:10 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2994 X-RateLimit-Reset: 1468335600
If you wish to display more about any give process, just append the pid to the /v2/vm/<uuid>/guest/cmd/<pid> URI as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" user='OSUser' pass='plain-text-pass' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" -d '{"user": "OSUser", "pass": "plain-text-pass"}'
HTTP/1.1 200 OK Allow: HEAD, DELETE, OPTIONS, GET Connection: keep-alive Content-Length: 583 Content-Type: application/json Date: Tue, 12 Jul 2016 14:51:40 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2989 X-RateLimit-Reset: 1468335600
Response body's data section contains the following attributes:
| Attribute | Type | Description |
|---|---|---|
| cmdLine | string | program executed |
| endTime | string | If the process was started using the API then the process completion time will be available if queried within 5 minutes after it completes. |
| pid | integer | Process Id |
| owner | string | Process owner |
| name | string | Process name |
| exitCode | integer | If the process was started using the API then the process exit code will be available if queried within 5 minutes after it completes. |
Create
The API also allows to execute a command in the guest operating system. In order to do so, you
| Attribute | Type | Description | Required |
|---|---|---|---|
| user | string | Guest OS username to execute command | |
| pass | string | Guest OS username password | |
| cmd | string | Command to be executed | |
| args | string | The arguments to the program. | |
| workDir | string | The absolute path of the working directory for the program to be run. | |
| env | string | List of environment variables, specified in the guest OS notation |
The minimum JSON payload sent via the POST method would be something like the following object:
{"user": "guest-os-username",
"pass": "guest-os-username-pass",
"cmd": "/bin/dd",
"args": "if=/dev/zero of=/tmp/f.out count=10000"}
Submitting the change request is shown below:
http POST "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" user='OSUser' pass='plain-text-pass' cmd='/bin/dd' args='if=/dev/zero of=/tmp/f.out count=10000' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" -d '{"user": "OSUser", "pass": "plain-text-pass" "cmd": "/bin/dd", "args": "if=/dev/zero of=/tmp/f.out count=10000"}'
The request will be processed and you will get a PID number if was successfully executed. Validating the exit code and running times can be done by making a GET request to the /vm/<uuid>/guest/cmd/<pid> as previously described.
Update
Killing a running process through the API is possible by making a DELETE request appending the pid to the /v2/vm/<uuid>/guest/cmd/<pid> URI as follows:
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" user='OSUser' pass='plain-text-pass' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" -d '{"user": "OSUser", "pass": "plain-text-pass"}'
State
The state resource provides information about the execution state and history of a virtual machine.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
State | /vm/<vm-id>/state | Virtual Machine power and running state. | | | |
Info
To display the execution state information, do a GET request to /vm/<vm-id>/state endpoint, resulting in a JSON object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| powerState | string | The current power state of the virtual machine. |
| connectionState | string | The connectivity state of a virtual machine.
Source VMware |
| bootTime | string | The timestamp when the virtual machine was most recently powered on. |
| domain | object | Fault domain the virtual machine is running on. |
The following example demonstrate how to query State information of a given VM:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Update
Currently, making a PUT request to /vm/<uuid>/state can update both power state and guest OS state to either poweredOn, poweredOff, reset or shutdown, reboot respectively. The following table describes each supported option and its effect on the virtual machine.
| Option | Type | Description | VMware Tools Running |
|---|---|---|---|
| poweredOn | string | Powers on this virtual machine. If the virtual machine is suspended, this method resumes execution from the suspend point. | - |
| poweredOff | string | Powers off this virtual machine. If this virtual machine is a fault tolerant primary virtual machine, this will result in the secondary virtual machine(s) getting powered off as well. | - |
| reset | string | Resets power on this virtual machine. If the current state is poweredOn, then this method first performs powerOff(hard). Once the power state is poweredOff, then this method performs powerOn(option). | |
| shutdown | string | Issues a command to the guest operating system asking it to perform a clean shutdown of all services. | |
| reboot | string | Issues a command to the guest operating system asking it to perform a reboot. | |
In order to update the state of any given VM, a request body must be sent in JSON format via a PUT request to /v2/vm/<vm-id>/state specifying a key named value and the desired state string, for instance:
{"value": "poweredOn"}
{"value": "poweredOff"}
{"value": "reset"}
{"value": "shutdown"}
{"value": "reboot"}
For demonstration purposes, the following example will power On and power Off a virtual machine.
The following example shows how to craft the HTTP request:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" value=poweredOn "Authorization: Bearer $TK" http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" value=poweredOff "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" -d '{"value": "poweredOn"}'
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" -d '{"value": "poweredOff"}'
Response from the API would look something like:
HTTP/1.1 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 427 Content-Type: application/json Date: Tue, 03 May 2016 01:59:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7194 X-RateLimit-Reset: 1462240800
Domain
Virtual machine fault domain is also available through the API.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
Domain | /vm/<vm-id>/domain | Virtual Machine fault domain. | | | |
Info
Obtaining the current fault domain where a virtual machine is running on, do a GET request to the /vm/<vm-id>/domain endpoint. The response contains a reference to the fault domain with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| name | string | Fault domain name. |
| moref | string | Managed object reference of the fault domain |
The following example demonstrates how to query a given virtual machine fault domain:
http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/domain" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/domain"
Response from the API would look something like:
HTTP/1.1 200 OK Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 491 Content-Type: application/json Date: Thu, 26 Jan 2017 02:08:52 GMT Server: nginx Strict-Transport-Security: max-age=63072000 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4998 X-RateLimit-Reset: 1485399600
Update
Migrating a virtual machine to another fault domain is possible by making a PUT request to the /v2/vm/<vm-id>/domain resource, specifying target domain moref. In order to proceed with the virtual machine relocation, it's required to be in a powered off state, thus, there is also the option to force if the VM is powered on by including the boolean attribute in the JSON payload force. After migrating, the virtual machine can be powered on by the migration task if the boolean attribute poweron is included. Refer to the following table to summarize what attributes should be included in the domain migration request:
| Attribute | Type | Description |
|---|---|---|
| value | string | Target fault domain managed object reference (moref) |
| poweron | boolean | Power on after migrating. |
| force | boolean | Will shutdown guest or power off VM if not able to migrate. |
The following example payload will send a GuestOS shutdown signal, if the OS does not shut down, it will power off the VM, start the migration and power on the virtual machine when complete.
{"value": "domain-c5877",
"poweron": true,
"force": true}
The following example shows how to craft the HTTP PUT request with the required JSON payload:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/domain" value=domain-c5877 poweron:=true force:=true "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/domain" -d '{"value": "domain-c5877", "poweron": true, "force": true} '
Response from the API would look something like:
HTTP/1.1 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 427 Content-Type: application/json Date: Tue, 03 May 2016 01:59:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d X-RateLimit-Limit: 7200 X-RateLimit-Remaining: 7194 X-RateLimit-Reset: 1462240800
Triggered Alarms
The Virtual Machine alarm resource provides information about any triggered alarms, as well methods to acknowledge and clear them.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Triggered alarm | /vm/<vm-id>/alarm | Virtual Machine specific Triggered Alarms. | | | ||||
| Specific triggered alarm | /vm/<vm-id>/alarm/<moref> | Lists, clears and acknowledges alarm. | | | |
Info
To show any triggered alarms related to a given virtual machine, do a GET request to /vm/<vm-id>/alarm endpoint, resulting in a JSON object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| dateTime | string | Timestamp the alarm triggered. |
| moref | string | Managed object reference of the alarm |
| name | string | Alarm name. |
| overallStatus | string | Overall status of the alarm object. gray - The status is unknown. Source VMware |
The following example demonstrate how to query Triggered Alarms of a given VM:
http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Now, to get further information about the alarm, follow the self attribute value within the _links attribute, which appends the Managed Object Reference (moref) of the alarm to the URI, as follows:
http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6"
In the response object, you will find even more alarm related attributes described in the following table:
| Attribute | Type | Description |
|---|---|---|
| acknowledged | boolean | Flag to indicate if the alarm's actions have been acknowledged for the associated |
| acknowledgedByUser | string | The user who acknowledged this triggering. If the triggering has not been acknowledged, then the value is not valid. |
| acknowledgedDateTime | string | The time this triggering was acknowledged. If the triggering has not been acknowledged, then the value is not valid. |
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Update
Currently, making a PUT request to /vm/<uuid>/alarm/<moref> can acknowledge or clear given alarm.
Acknowledging the alarm can be done by specifying either ack or clear value for the attribute value as shown below:
{"value": 'ack'}
{"value": 'clear'}
For demonstration purposes, the following example will Acknowledge and then Clear a virtual machine triggered alarm.
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6" value=ack "Authorization: Bearer $TK" http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6" value=clear "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6"" -d '{"value": "ack"}'
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6"" -d '{"value": "clear"}'
{
"data": {
"_links": {
"request": "https://vss-api.eis.utoronto.ca/v2/request/change/2",
"task": "https://vss-api.eis.utoronto.ca/v2/request/task/c510469d-b045-4221-bdb0-41ce65507cea"
},
"message": "VM Change Request has been accepted for processing",
"name": "Accepted",
"state": "Submitted",
"status": 202
},
"meta": {
"time": "0.17118s",
"user": "jm"
}
}
When displaying the alarm information you can see two attributes have been populated: acknowledgedByUser and acknowledgedDateTime. This means the alarm has been successfully Acknowledged, besides of checking the status
Events
This resource provides information about vCenter events related to a specific virtual machine within a time frame.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| vCenter events | /vm/<vm-id>/event | Virtual Machine related vCenter events within 1 hour by default. | | |
Info
To list any vCenter events related to a given virtual machine, do a GET request to /vm/<vm-id>/event endpoint, this will query all events within 1 hour by default, resulting in a JSON object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| createdTime | string | Timestamp of event |
| message | string | What kind of activity is this message related to. |
| userName | string | Username executing this task. If not specified, it has been created by vCenter. |
Querying events of a given virtual machine can be done as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event"
If no timeframe was specified, 1 hour is used as default value and sometimes it does not return any event. In such case you will get a 404 error as follows:
HTTP/1.0 404 NOT FOUND Allow: HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Appending the number of hours to the URI, you will query the events within N hours. In the following example uses 2 as a time window:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event/2" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event/2"
Client Notes
This resource provides information about the virtual machine Client Custom Notes, which is used to store any string provided by the user.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Client Notes | /vm/<vm-id>/note/client | Virtual Machine Client custom notes if any. | | | |
Update
A PUT request to /vm/<uuid>/note/client with attribute value will update, delete existing client notes. A JSON object is the value expected which could be either in pure JSON format or sent as a string. Examples of JSON objects are show below:
{"value": "BillingCode: 12345"}
The following example shows how to craft the HTTP request to add the BillingCode custom note with value 12345:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client" value='BillingCode: 12345' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client" -d '{"value": "BillingCode: 12345"}'
{
"data": {
"_links": {
"request": "https://vss-api.eis.utoronto.ca/v2/request/change/2",
"task": "https://vss-api.eis.utoronto.ca/v2/request/task/c510469d-b045-4221-bdb0-41ce65507cea"
},
"message": "VM Change Request has been accepted for processing",
"name": "Accepted",
"state": "Submitted",
"status": 202
},
"meta": {
"time": "0.07118s",
"user": "jm"
}
}
List
Listing existent Custom Client notes can be done by making a GET request to the /vm/<vm-id>/client/note as shown below:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Performance
Basic performance counters can be gotten from /vm/<vm-id>/performance resource. The only restriction is that the virtual machine has to be powered On, otherwise an error will be thrown.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Performance | /vm/<vm-id>/performance | Virtual Machine performance statistics, including datastore IO, memory, CPU and network. | | | ||||
| CPU | /vm/<vm-id>/performance/cpu | CPU relevant performance counters | | | ||||
| Memory | /vm/<vm-id>/performance/memory | Memory relevant performance counters | | | ||||
| Datastore | /vm/<vm-id>/performance/io | Datastore relevant performance counters | | | ||||
| Network | /vm/<vm-id>/performance/net | Network relevant performance counters | | |
Making a HTTP GET request to /vm/<vm-id>/performance will result in a JSON object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| cpu | object | Virtual Machine CPU statistics
|
| datastore | object | Virtual Machine IO stats from datastore.
|
| dateTime | string | Timestamp of performance stats. |
| memory | object | Virtual Machine memory statistics.
|
| name | string | Virtual machine name. |
| network | object | Network Errors and traffic
|
Getting performance stats using the API can be obtained by structuring a GET request to the performance endpoint as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/performance" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/performance"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Console
This resource will generate a Virtual Machine HTML5 one-time valid URL to copy and paste it in your preferred browser, so you avoid going through the vSphere web client.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Console | /vm/<vm-id>/console | Virtual Machine HTML5 one-time console link. | | |
To generate a console link you just need to have a valid vSphere session (unfortunately), and this is due to the nature of vSphere API.
A link will be generated by making a GET request to /vm/<vm-id>/console as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/console" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/console"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: HEAD, OPTIONS, GET Content-Length: 594 Content-Type: application/json Date: Fri, 06 May 2016 18:00:19 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2999 X-RateLimit-Reset: 1462561200
Version
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Hardware Version | /vm/<vm-id>/version | Upgrade hardware version or upgrade policy | | | |
List
Listing current virtual hardware version (VMX) can be done by making a GET request to the /vm/<vm-id>/version as shown below:
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/version"
Response from the API would look something like:
HTTP/1.0 200 OK Allow: PUT, HEAD, OPTIONS, GET Content-Length: 2550 Content-Type: application/json Date: Fri, 06 May 2016 13:26:29 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2991 X-RateLimit-Reset: 1462543200
Update
Currently two attributes are supported by the resource /vm/<vm-id>/version:
| Attribute | Description |
|---|---|
| version | Virtual machine hardware version |
| upgrade_policy | Virtual machine upgrade policy. Specifies whether to upgrade the virtual machine hardware to the lates versiont on always, never, onSoftPowerOff |
Before performing a virtual machine hardware upgrade, it is highly recommended to take a snapshot in case of any eventuality.
To submit a change request and update the version to the latest virtual hardware, do a PUT request to /vm/<vm-id>/version resource:
curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/version" -d '{"attribute": "version", "value": "vmx-13"}'
After submitting the request, a task will be created as any other change request.
To update the upgrade_policy, just use the proper attribute-value setting as follows:
curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/version" -d '{"attribute": "upgrade_policy", "value": "onSoftPowerOff"}'
When the onSoftPowerOff policy has been se to the virtual machine upgrade_policy, the virtual machine hardware upgrade will happen on next shut down.
ExtraConfig
This resource provides all methods to create VMware **guestinfo** interface options, which are available to the VM guest operating system via VMware Tools with the following command:
vmtoolsd --cmd "info-get guestinfo.<option>"
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Extra Config | /vm/<vm-id>/extra-config | Manage VMware guestinfo interface options. | | | | | |
List
To obtain current available options, perform a GET request to /vm/<vm-id>/extra-config:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config"
Response from the API would look something like:
HTTP/1.1 200 OK Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Content-Encoding: gzip Content-Length: 314 Content-Type: application/json Date: Fri, 12 Jul 2019 16:31:14 GMT Server: gunicorn/19.7.1 Vary: Accept-Encoding X-Ratelimit-Limit: 5000 X-Ratelimit-Remaining: 4993 X-Ratelimit-Reset: 1562950800 X-Vssapi-Appserver: e207c7a693bf X-Vssapi-Version: v2.3.37
Create
Extra config entries are based in key-value objects, thus a json object is expected in the payload in order to create valid keys, for instance:
{"key1": "value1"}
The request to the API would be via POST to /vm/<vm-id>/extra-config with the json object in the value attribute:
http POST https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" value:='{"key": "value"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" -d '{"value": {"key": "value"}}'
Response from the API would look something like:
HTTP/1.1 202 Accepted Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Cache-Control: private, no-cache, no-store, max-age=0 Content-Encoding: gzip Content-Length: 282 Content-Type: application/json Date: Fri, 12 Jul 2019 16:29:51 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/344dccce-8d7e-4cb2-a17d-942b743284c3 Server: gunicorn/19.7.1 Vary: Accept-Encoding X-Ratelimit-Limit: 5000 X-Ratelimit-Remaining: 4994 X-Ratelimit-Reset: 1562950800 X-Vssapi-Appserver: c143fbd7e313 X-Vssapi-Version: v2.3.37
Update
Just like creating, the required payload to update an existing entry is a JSON object (dictionary). The request to the API would be via PUT to /vm/<vm-id>/extra-config with the json object in the value attribute:
http PUT https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" value:='{"key": "value"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" -d '{"value": {"key": "value"}}'
Response from the API would look something like:
HTTP/1.1 202 Accepted Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Cache-Control: private, no-cache, no-store, max-age=0 Content-Encoding: gzip Content-Length: 283 Content-Type: application/json Date: Fri, 12 Jul 2019 16:31:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/30bdd085-01d8-42b5-81b7-3fcfec3b9329 Server: gunicorn/19.7.1 Vary: Accept-Encoding X-Ratelimit-Limit: 5000 X-Ratelimit-Remaining: 4992 X-Ratelimit-Reset: 1562950800 X-Vssapi-Appserver: c143fbd7e313 X-Vssapi-Version: v2.3.37
Delete
Deleting entries is simpler, just add a list of keys to the JSON payload in the value attribute:
["key1", "key2"]
The request to the API would be via DELETE to /vm/<vm-id>/extra-config with the json object in the value attribute:
http PUT https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" value:='["key"]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" -d '{"value": ["key"]}'
Response from the API would look something like:
HTTP/1.1 202 Accepted Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE Cache-Control: private, no-cache, no-store, max-age=0 Content-Encoding: gzip Content-Length: 283 Content-Type: application/json Date: Fri, 12 Jul 2019 16:31:23 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/30bdd085-01d8-42b5-81b7-3fcfec3b9329 Server: gunicorn/19.7.1 Vary: Accept-Encoding X-Ratelimit-Limit: 5000 X-Ratelimit-Remaining: 4992 X-Ratelimit-Reset: 1562950800 X-Vssapi-Appserver: c143fbd7e313 X-Vssapi-Version: v2.3.37
Export
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Export OVF | /vm/<vm-id>/export | Virtual Machine OVF export action to vskey-stor. | | |
VMware vSphere provides the ability to export virtual machines for use in other software through the Export feature. The export virtual machine resource will automate the Export process generating an Open Virtualization Format (OVF) and will transfer it to your account space in https://vskey-stor.eis.utoronto.ca. A virtual machine qualifies to be exported if used storage is less than 200G and power state is Off.
OVF is a platform-independent, efficient, extensible, and open packaging and distribution format for virtual machines. OVF format provides a complete specification of the virtual machine, including the full list of required virtual disks and the required virtual hardware configuration, including CPU, memory, networking, and storage. Source VMware
To request an export make a POST request to /vm/<vm-id>/export as follows:
http POST "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/export" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/export"
Response from the API would look something like:
HTTP/1.0 202 ACCEPTED Allow: POST, OPTIONS Content-Length: 397 Content-Type: application/json Date: Fri, 06 May 2016 18:42:29 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/1b5b82b3-30f8-4be2-8302-e6d458a92d6f X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2989 X-RateLimit-Reset: 1462561200
When the Export Request completes, go to https://vskey-stor.eis.utoronto.ca, login with your VSKEY credentials and you will find a directory named after the exported virtual machine Uuid which will contain OVF and VMDK files. OVF contains all the VM configuration and VMDK files are the exported disks.
Snapshots
The /v2/vm/<vm_uuid/snapshot resource allows you to manage in a simplified manner virtual machine snapshots, including basic activities such as list, create, delete and revert to a particular snapshot.
Recommended reading Virtual Machine - Attributes
As described in the following table, there are two URIs to deal with /vm/<vm-id>/snapshot which lists virtual machine snapshots, if any, and creates snapshots in a particular point in time. On the other hand /vm/<vm-id>/snapshot/<snapshot_id> provides information about the requested snapshot_id, allows you to manually delete it or even restore the virtual machine state to that particular snapshot.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Snapshots | /vm/<vm-id>/snapshot | Virtual Machine Snapshot resource. List or create VM snapshots. | | | | |||
| Snapshot | /vm/<vm-id>/snapshot/<snapshot_id> | List, delete and restore from <snapshot_id> | | | | |
List
Listing existent snapshots can be done by making a GET request to /vm/<vm-id>/snapshot:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot"
The API response would contain a list of JSON objects with two attributes _links and name:
Following the URI included in the JSON list, shows further attributes of a particular snapshot:
| Attribute | Type | Description |
|---|---|---|
| age | string | Timedelta from the time taken to now. |
| createTime | string | Timestamp when the snapshot was taken. |
| description | string | Snapshot description |
| fileKeys | array | Disks keys involved in the snapshot. |
| id | integer | Snapshot id. |
| name | string | Snapshot name. |
| quiesced | boolean | Whether the file system was quiesced in the virtual machine |
| sizeGB | integer | Snapshot size in GB. |
| powerState | string | Virtual machine power state. |
A GET request to /vm/<vm-id>/snapshot/<snapshot_id> would get previously described attributes in the response.
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19"
API response would look like:
Create
To submit a snapshot request, you should create a POST request to /vm/<vm-id>/snapshot with the following attributes in form of a JSON object:
| Attribute | Type | Description |
|---|---|---|
| from_date | string | Timestamp with the following format %Y-%m-%d %H:%M. If date is in the past, the snapshot will be taken right away, otherwise it will wait. |
| valid_for | integer | Number of hours (max 72) the snapshot will live |
| description | string | A brief description of the snapshot. |
An example of a JSON object is show below:
{"from_date": "2016-05-11 10:20",
"valid_for": 72,
"description": "before upgrading very important module"}
Crafting the POST request should look something like:
http POST "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot" valid_for=73 from_date='2016-05-11 10:20' description='before upgrading very important module' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot" -d '{"from_date": "2016-05-11 10:20", "valid_for": 72, "description": "before upgrading very important module"}'
In this case, the snapshot will be deleted 72 hours after from_date, this is 2016-05-14 10:20.
If an invalid date or parameter value is submitted, HTTP 400 errors would be returned:
{
"message": "According to VSS best practices, the maximum lifetime should be 72 hours.",
"status": 400
}
After submitting the request, a confirmation will be returned and this time, it will not contain a task ID, just a request_id:
HTTP/1.0 202 ACCEPTED Allow: HEAD, POST, OPTIONS, GET Content-Length: 318 Content-Type: application/json Date: Wed, 11 May 2016 14:07:00 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2998 X-RateLimit-Reset: 1462978800
To monitor your snapshot creation/deletion, you can get further information by making a GET request to /v2/request/snapshot/<request_id>
Delete
Snapshot deletion is scheduled and it will be executed as soon as the validity time has expired, however, if there's the need to manually delete it, you can make a DELETE request to /vm/<vm-id>/snapshot/<snapshot_id> with no data.
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19"
After submitting the request, a confirmation will be returned and this time, it will not contain a task ID, just a request_id:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PATCH, OPTIONS, DELETE Content-Length: 318 Content-Type: application/json Date: Wed, 11 May 2016 14:07:00 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2998 X-RateLimit-Reset: 1462978800
To monitor your snapshot creation/deletion, you can get further information by making a GET request to /v2/request/snapshot/<request_id>
Revert
Reverting to a given snapshot is done by making a PATCH request to /vm/<vm-id>/snapshot/<snapshot_id> with no data.
http PATCH "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X PATCH "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19"
After submitting the request, a confirmation will be returned and this time, it will not contain a task ID, just a request_id:
HTTP/1.0 202 ACCEPTED Allow: HEAD, GET, PATCH, OPTIONS, DELETE Content-Length: 318 Content-Type: application/json Date: Wed, 11 May 2016 14:07:00 GMT X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2998 X-RateLimit-Reset: 1462978800
To monitor your snapshot request, you can get further information by making a GET request to /v2/request/snapshot/<request_id>
Disk Consolidation
When you initiate a Delete or DeleteAll operation on snapshots, the snapshot is immediately deleted, then the backing virtual machine disk .vmdk files are consolidated on-disk. If the consolidation fails [during snapshot deletion], some Virtual Disk files may remain on disk and/or be actively used on the Datastore, consuming storage capacity. (Source: VMware).
Recommended reading Consolidating snapshots in vSphere 5.x/6.0
The /v2/vm/<vm_uuid/snapshot/consolidate resource provides a simple interface to know whether virtual machine disks require consolidation via GET method and also, executes disk consolidation on demand via PUT method as shown in the following table:
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Disk consolidation | /vm/<vm-id>/snapshot/consolidate | Virtual Machine Disk consolidation resource | | | |
Virtual machine disk consolidation is based on finding hierarchies of redo logs that can be combined without violating data dependency. The redundant redo logs after merging are then deleted. Consolidation improves I/O performance since less number of virtual disk files need to be traversed; it also reduces the storage usage.
List
To validate whether a virtual machine requires disk consolidation, a GET request to the URI /vm/<vm-id>/snapshot/consolidate can be done as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate"
In this case, only one attribute is returned in the JSON object data, called requireDiskConsolidation, which is a flag to indicate whether or not disk must be consolidated
Update
If disk consolidation is required, a simple PUT request to the /vm/<vm-id>/snapshot/consolidate URI should be submitted.
Additional space is temporarily required to perform the operation. Consolidation can be I/O intensive, it is advisable to invoke this operation when guest is not under heavy I/O usage.
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate"
After submitting the request, a task will be created as any other change and the Response from the API should look something like:
HTTP/1.1 202 ACCEPTED Allow: PUT, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 427 Content-Type: application/json Date: Tue, 10 May 2016 14:01:15 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/d603ca15-2b40-4c82-b3f2-8965bb2903aa Server: nginx X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2999 X-RateLimit-Reset: 1462892400
After disk consolidation is complete, requireDiskConsolidation flag has changed to false.
VSS Client/Billing Department
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Usage | /vm/<vm-id>/vss/client | Virtual Machine Client/Billing Department. | | | |
List
Getting the current VSS Client or Billing department is done by making a HTTP request to /v2/vm/<vm-id>/vss/client as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client"
The API response would contain a list of JSON objects with two attributes _links and data:
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client",
"vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
},
"data": {
"value": "EIS"
},
"meta": {
"count": 1,
"time": "0.14646s",
"user": "jm"
}
}
Update
Updating a given virtual machine Billing Department/Client is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/client resource and providing the new usage in the payload as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" value:='{"value": "VSS"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" -d '{"value": "VSS"}'
VSS VM Description
The virtual machine description is part of the VSS Metadata that helps to provide context about the software or service of the virtual machine.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Description | /vm/<vm-id>/vss/description | Virtual Machine Description. | | | |
List
Getting the current VSS Description is done by making a HTTP request to /v2/vm/<vm-id>/vss/description as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description"
The API response would contain a list of JSON objects with two attributes _links and data:
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description",
"vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
},
"data": {
"value": "Graylog2 server for log analysis"
},
"meta": {
"count": 1,
"time": "0.14646s",
"user": "jm"
}
}
Update
Updating a given virtual machine Description is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/description resource and providing the new usage in the payload as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description" value:='{"value": "Logstash server to collect logs, parse them, and store them for later use."}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" -d '{"value": "Logstash server to collect logs, parse them, and store them for later use."}'
The description has a minimum of 50 and maximum of 200 characters of length.
VSS Usage
Part of the VSS metadata and the name prefix (YYMMP-) is composed by the virtual machine usage, which is intended to specify whether it will be hosting a Production, Development, QA, or Testing system.
| Resource | URI | Description | GET | POST | PUT | DELETE | PATCH | OPTIONS* |
|---|---|---|---|---|---|---|---|---|
| Usage | /vm/<vm-id>/vss/usage | Virtual Machine usage. | | | |
List
Getting the current VSS usage is done by making a HTTP request to /v2/vm/<vm-id>/vss/usage as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage"
The API response would contain a list of JSON objects with two attributes _links and data:
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage",
"vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
},
"data": {
"value": "Prod"
},
"meta": {
"count": 1,
"time": "0.14646s",
"user": "jm"
}
}
Update
Updating a given virtual machine usage is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/usage resource and providing the new usage in the payload as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage" value:='{"value": "Prod"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage" -d '{"value": "Prod"}'
Options used in the value parameter are:
- Prod, prd, Prd, prod
- Test, testing, Testing
- Dev, dev
- QA, qa
Previos action will trigger a change in the VSS prefix used in the name of the virtual machine, as well as in the VSS metadata.
VSS Admin
Getting the current VSS admin is done by making a HTTP request to /v2/vm/<vm-id>/admin as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin"
The API response would contain a list of JSON objects with two attributes _links and data:
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage",
"vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
},
"data": {
"email": "jm@eis.utoronto.ca",
"name": "JM Lopez",
"phone": "416-123-1234"
},
"meta": {
"count": 1,
"time": "0.14646s",
"user": "jm"
}
}
Update
Updating a given virtual machine VSS VM admin is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/admin resource and providing the new VM admin in the payload as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin" value:='{"value": "JM Lopez:416-123-2123:jm@eis.utoronto.ca"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin" -d '{"value": "JM Lopez:416-123-2123:jm@eis.utoronto.ca"}'
The VM admin is in the following format "<full_name>:<phone_number>:<email_address>"
VSS Inform
Part of the VSS Metadata in the virtual machine is composed by the informational contacts, which can be obtained by a request to /v2/vm/<vm-id>/vss/inform:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/inform" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/inform"
The response contains a list of JSON objects with two attributes _links and data:
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/inform",
"vm": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss"
},
"data": [
"jm@eis.utoronto.ca"
],
"meta": {
"count": 1,
"time": "0.06006s",
"user": "jm"
}
}
Update
Updating a given virtual machine VSS Informational contacts is done by submitting a PUT request to the /v2/vm/<vm-id>/vss/inform resource and providing the new VM informational email list, followed by whether this list will be appended or replaced in the payload as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/inform" value="jm.lopez@utoronto.ca,jm@eis.utoronto.ca" append:=false "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/inform" -d '{"value": "jm.lopez@utoronto.ca,jm@eis.utoronto.ca", "append": False}'
VSS Service
Part of the VSS Metadata in the virtual machine is composed by VSS Service, which can be obtained by a request to /v2/vm/<vm-id>/vss/service:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/service" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/service"
The response contains a list of JSON objects with two attributes _links and data:
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/service",
"vss": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss"
},
"data": {
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vss/service/57"
},
"description": "VMware virtual server & storage hosting",
"id": 57,
"name": "Virtual Server Service",
"service_group_id": 7
},
"meta": {
"count": 5,
"time": "0.07775s",
"user": "jm"
}
}
Update
Updating a given virtual machine VSS Service is done by submitting a PUT request to the /v2/vm/<vm-id>/vss/service resource and providing the new VSS Service ID or Label. Then, the first step is to look up the VSS Service as follows:
http GET "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,%Cloud%&expand=1" $TK
The response includes the following objects:
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,%25Cloud%25&expand=1"
},
"data": [
{
"created_on": "2019-03-11T19:27:31.921275Z",
"description": "Central Backup Service",
"group": {
"description": "Infrastructure as a Service (IaaS)",
"id": 7,
"name": "ITS Private Cloud Infrastructure"
},
"id": 56,
"label": "ITS Private Cloud Infrastructure/UTORbackup",
"name": "UTORbackup",
"updated_on": "2019-04-15T16:28:24.371791Z"
},
{
"created_on": "2019-03-11T19:27:32.246834Z",
"description": "VMware virtual server & storage hosting",
"group": {
"description": "Infrastructure as a Service (IaaS)",
"id": 7,
"name": "ITS Private Cloud Infrastructure"
},
"id": 57,
"label": "ITS Private Cloud Infrastructure/Virtual Server Service",
"name": "Virtual Server Service",
"updated_on": "2019-04-15T16:28:24.396338Z"
}
],
"meta": {
"count": 2,
"filter": "label,like,%Cloud%",
"pages": {
"first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2C%25Cloud%25&per_page=10&page=1&expand=1",
"last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2C%25Cloud%25&per_page=10&page=1&expand=1",
"next_url": null,
"page": 1,
"pages": 1,
"per_page": 10,
"prev_url": null,
"total": 2
},
"time": "0.00535s",
"user": "jm"
}
}
Once we get the proper label "ITS Private Cloud Infrastructure/Virtual Server Service" or ID 57, we can proceed to submit the change request to update the attributre in the virtual machine:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/service" value:=57 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/service" -d '{"value": 57}'
VSS HA Group
VSS metadata includes the HA Group tag, which helps to identify which virtual machine instances should be separated into different fault domains with the end goal being that if there's an unforeseen outage in one fault domain which takes out one VM, then the associated redundant virtual machines in other resource zones would not be affected. For example, if you have three front-end HA proxy setup in a load-balance situation, the HA group feature would indicate which VMs should be migrated to other resource zones so that neither of the VMs have any resources in common. Having that, virtual machine migration from fault domains require the instance to be powered off, this feature does not cause automatic VM migration, but only identifies which VMs should be separated and in case of any missing association, then associated.
Obtaining the current state of a given ha_group can be done through the /v2/vm/<vm-id>/vss/ha_group resource.
http GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/ha_group" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/ha_group"
The response contains a list of JSON objects with two attributes _links and data:
{
"_links": {
"self": "http://vss-api.eis.utoronto.ca/v2/vm/501220a5-a091-1866-9741-664236067142/vss/ha_group",
"vss": "http://vss-api.eis.utoronto.ca/v2/vm/501220a5-a091-1866-9741-664236067142/vss"
},
"data": {
"count": 1,
"valid": true,
"vms": [
{
"_links": {
"self": "http://vss-api.eis.utoronto.ca/v2/vm/50128577-2026-908a-7bb7-df5a34fea7bf"
},
"name": "1610T-cranky_sinoussi",
"uuid": "50128577-2026-908a-7bb7-df5a34fea7bf",
"valid": true
}
]
},
"meta": {
"count": 3,
"time": "0.12620s",
"user": "jm"
}
}
The following table describes each of the "data" attributes:
| Attribute | Description |
|---|---|
| count | Count of virtual machines related to the current vm |
| valid | Overall status of ha group vm association. |
| vms | Virtual machines associated |
| vms[*].name | Related virtual machine name. Null if by any reason it does not exist. |
| vms[*].uuid | Related virtual Machine uuid. |
| vms[*].valid | Related virtual machine valid status. True if association is mutual. |
A background task kicks in every hour for full vm association status and domain separation. If HA group is not valid, by domain separation or association you will receive an email as follows:
Update
Updating a virtual machine HA Group is done by submitting a PUT request to the /v2/vm/<vm-id>/vss/ha_group resource and providing the related virtual machine UUID list, followed by whether this list will be appended or replaced in the payload as follows:
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/ha_group" value:='["be693fa9-af28-4849-b3e1-dc4fa629d128", "79c8325d-5696-45d0-bcde-2c1f6d6cffed"]' append:=false "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/ha_group" -d '{"value": ["be693fa9-af28-4849-b3e1-dc4fa629d128", "79c8325d-5696-45d0-bcde-2c1f6d6cffed"], "append": False}'
Configuration Specification
The sole purpose of the configuration specification resource /v2/vm/<vm-id>/spec is to provide the given virtual machine relevant attributes to carbon-copy a virtual machine without its data. Therefore, the resource is available only through the GET method. The following lines exemplify how to obtain a virtual machine configuration spec:
http GET "https://vss-api.eis.utoronto.ca/v2/vm/50128d83-0fcc-05e3-be71-d972ffdf3284/spec" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50128d83-0fcc-05e3-be71-d972ffdf3284/spec"
Response would be something similar as shown below:
An example on how to use the configuration spec is detailed in this KB article Virtual Machine - Attributes.
Guest OS Customization Specification
One of the most recent features is allowing to reconfigure a virtual machine (change Hostname, and NIC IP address configuration automatically by processing these changes through VMware Tools) from first boot after being deployed by the Guest Operating System Customization Specification. However, this feature can be also executed on a given virtual machine instance if the VM power state is OFF. One common use case is repurposing a virtual machine instance or moving a virtual machine from one network to another without accessing the guest operating system.
The customization specification consists of the following key value items:
| Attribute | Value type | Description | Required |
|---|---|---|---|
hostname | string | Valid hostname. | |
| domain | string | Valid domain. | |
| dns | list | List of dns servers in string. Priority is set by order |  only if dhcp is false |
| interfaces | list | List of interface objects | |
| poweron | boolean | Power on instance after submitting customization spec | - |
| Attribute | Value type | Description | Required |
|---|---|---|---|
| ip | string | Network interface ip address | only if dhcp is false |
| mask | string | Network interface ip address subnet mask | only if dhcp is false |
| gateway | list | List of ip address gateway | only if dhcp is false |
| dhcp | boolean | Whether to use dhcp or not | |
To reconfigure a server with static IP address, the JSON payload would look as follows:
{"hostname": "web1",
"dns": ["192.168.1.1", "8.8.8.8"],
"domain": "eis.utoronto.ca",
"interfaces": [{"ip": "192.161.11",
"dhcp": false,
"mask": "255.255.255.0",
"gateway": ["192.168.1.1"]
}
],
"poweron": true}
Above payload can be submitted using the POST method to /v2/vm/<vm-id>/custom_spec as shown below:
http POST "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/custom_spec" hostname=web1 domain=eis.utoronto.ca dns:='["192.168.1.1", "8.8.8.8"]' interfaces:='[{"ip": "192.161.11", "dhcp": false, "mask": "255.255.255.0", "gateway": ["192.168.1.1"] }]' poweron:=true "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/custom_spec" -d '{"hostname": "web1", "dns": ["192.168.1.1", "8.8.8.8"], "domain": "eis.utoronto.ca", "interfaces": [{"ip": "192.161.11", "dhcp": false, "mask": "255.255.255.0", "gateway": ["192.168.1.1"] } ], "poweron": true}'