ITS Private Cloud API v3.14.1 🎉

Created by JM Lopez
Last updated: Nov 23, 2020
4 min read

We are pleased to announce we released the ITS Cloud API v3.14.2 with the following improvements and bug fixes:

Improvements

User/Personal VMDK file object, sync request and resources. (#1445)

Endpoints

  •  /v2/user/file (GET)
  •  /v2/user/file/vdmk (GET, PATCH)
  • /v2/request/vmdk-sync (GET)
  • /v2/request/vmdk-sync/<id> (GET)

Description

This improvement brings the ability submit a synchronization request to browse the vmdk files in the VSS API which were previously uploaded to the vskey-stor space. 

The first step is to upload a valid VMDK to vskey-stor. Then submit a sync request to the following URL:

curl -X PATCH https://vss-api.eis.utoronto.ca/v2/user/file/vmdk -H "Authorization: Bearer $TK"

Once the request has been processed, you will be able to browse the files as follows:

curl -X GET https://vss-api.eis.utoronto.ca/v2/user/file/vmdk -H "Authorization: Bearer $TK"
{
	"_links": {
		"self": "https://vss-api.eis.utoronto.ca/v2/user/file/vmdk"
	},
	"data": [
	{
		"created_on": "2020-11-16 Mon 11:28:52 EST",
		"data_store": "vssUser-xfers",
		"folder": "vskey/josem/50307927-887d-b04e-81a0-a8da57703590",
		"id": 24,
		"label": "vskey/josem/50307927-887d-b04e-81a0-a8da57703590/disk-0.vmdk",
		"name": "disk-0.vmdk",
		"path": "[vssUser-xfers] vskey/josem/50307927-887d-b04e-81a0-a8da57703590/disk-0.vmdk",
		"updated_on": "2020-11-16 Mon 11:28:52 EST"
	}
	],
	"meta": {
		"count": 1,
		"pages": {
		"first_url": "https://vss-api.eis.utoronto.ca/v2/user/file/vmdk?page=1&per_page=100&expand=True",
		"last_url": "https://vss-api.eis.utoronto.ca/v2/user/file/vmdk?page=1&per_page=100&expand=True",
		"next_url": null,
		"page": 1,
		"pages": 1,
		"per_page": 100,
		"prev_url": null,
		"total": 1
	},
	"time": "0.00731s",
	"user": "josem"
	}
}

VM/Add disk from User Vmdk file. (#1448)

Endpoints

  • /v2/vm/<id>/disk (POST)

Description

The improvement brings support to mount "external" vmdk drives which are useful when migrating virtual machines to the ITS Private Cloud. Before attempting to "mount" an external disk, you should have synchronized their available Vmdk files from vskey-stor. (PATCH to /v2/user/file/vmdk).

The action of "mounting" external disk is actually divided in the following steps:

  1. Copy the external disk to the target VM home.
  2. The VMDK in question will be named with the following format: %(vmx_home)s/%(vm_name)s-vsk-%(unit)s.vmdk
  3. A VMDK descriptor will be created at the final step of the copying process which will result in: %(vmx_home)s/%(vm_name)s-vsk-%(unit)s.vmdk and %(vmx_home)s/%(vm_name)s-vsk-%(unit)s-flat.vmdk.

To submit an automated mount process, submit a POST request to /v2/vm/<id>/disk adding the attribute backing_vmdk with either the vmdk id or full path with the following payload:

curl -X POST https://vss-api.eis.utoronto.ca/v2/vm/vm-1234/disk -d '[{"capacity_gb": 100, "backing_vmdk": '[vssUser-xfers] vskey/josem/50307927-887d-b04e-81a0-a8da57703590/disk-0.vmdk'}]' -H "Authorization: Bearer $TK"

It takes a fair amount of time to process depending on the VMDK size, but you can monitor the process with the request URL which was provided in previous POST action response. Once the file is copied to the target datastore, the task will automatically mount it and make it available to the virtual machine.

VM/Extra Configuration: allow set disk.EnableUUID. (#1447)

Endpoints

  • /v2/vm (POST)
  • /v2/vm/<id>/extra-config (GET, PUT)
  • /v2/vm/<id>/spec (GET)
  • /v2/vss/vm-extra-config (GET)

Description

VMWare by default does not provide information needed by udev to generate /dev/disk/by-id entries and in some Linux OS such as Ubuntu or Suse there could be entries in the syslog as follows:

failed to get udev uid: Invalid argument

The solution provided by VMware is to add the advanced setting disk.EnableUUID = "TRUE" to the virtual machine configuration file. This can be now accomplished by either including the extra_config attribute in the /vm creation payload or updating the settings in the /vm/<id>/extra-config resource.

curl -X POST https://vss-api.eis.utoronto.ca/v2/vm -d '{"usage": "Prod", "os": "ubuntu64Guest", "built_from": "os_install", "client": "EIS", "description": "Java web application.", "folder": "group-v4122", "networks": [{"network": "dvportgroup-95", "type": "vmxnet3"}, {"network": "dvportgroup-92"}], "disks": [{"capacity_gb": 100}, {"capacity_gb": 100, "backing_mode": "independent_persistent"})], "power_on": true, "extra_config": [{"disk.EnableUUID": "TRUE"}, {"customTag": "CustomTagValue"}]}' -H "Authorization: Bearer $TK"

As you can see in the previous example, the extra_config attribute also can take custom key-value tags that will be stored as guestinfo.* options. Existing Extra Config options are included in the /vm/<id>/extra-config and also in /spec resource.

The /v2/vss/vm-extra-config resource provides a list of supported extra configuration options:

curl -X GET https://vss-api.eis.utoronto.ca/v2/vss/vm-extra-config -H "Authorization: Bearer $VSS_API_TOKEN"
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/vss/vm-extra-config",
"vss": "https://vss-api.eis.utoronto.ca/v2/vss"
},
"data": [
{
"description": "Enable disk UUID on virtual machines",
"option": "disk.EnableUUID"
},
{
"description": "Enable content Copy/Paste between VMRC client and Windows/Linux",
"option": "isolation.tools.copy.disable"
},
{
"description": "Enable content Copy/Paste between VMRC client and Windows/Linux",
"option": "isolation.tools.paste.disable",
"prefix": false
},
{
"description": "Enable content Copy/Paste between VMRC client and Windows/Linux",
"option": "isolation.tools.setGUIOptions.enable"
},
{
"description": "You can use the guestinfo variables to query information such as version and build information.",
"option": "guestinfo."
}
],
"meta": {
"count": 5,
"time": "0.00248s",
"user": "josem"
}
}

VM/deployment to support firmware type (efi, bios) (#1451)

Endpoints

  • /v2/vm (POST)
  • /v2/vm/<id>/spec (GET)
  • /v2/vss/vm-firmware (GET)

Description

For virtual machines runninng Windows 10 or Windows Server 2016 VM’s today, VMware HIGHLY recommends using the EFI firmware enabled. Moving from traditional BIOS/MBR to EFI (UEFI) firmware after the fact introduces some challenges later on down the line (Source VMware Blog).

From this version of the VSS API, you would be able to deploy virtual machines with an specific firmware option, either the default BIOS or EFI. 

To deploy a virtual machine with EFI, just include the attribute firmware=efi in the virtual machine creation payload POST /v2/vm:

{
	"built_from": "os_install",
	"client": "EIS",
	"cpu": 2,
	"description": "Staging Server",
	"disks": [
		{
		"capacity_gb": 127
		}
	],
	"firmware": "efi",
	"folder": "group-v12345",
	"memory": 4,
	"name": "WIN-EFI",
	"networks": [
		{
		"network": "dvportgroup-1234",
		"type": "vmxnet3"
		}
	],
	"os": "windows9Server64Guest",
	"usage": "QA",
}

For instance:

curl -x POST https://vss-api.eis.utornto.ca/v2/vm -H "Authorization: Bearer $TK" -d '{"built_from": "os_install", "client": "EIS", "cpu": 2, "description": "Staging Server", "disks": [{"capacity_gb": 127}], "firmware": "efi", "folder": "group-v12345", "memory": 4, "name": "WIN-EFI", "networks": [{"network": "dvportgroup-1234", "type": "vmxnet3"}], "os": "windows9Server64Guest", "usage": "QA"}'

VM/update Enable or Disable UEFI Secure Boot for a Virtual Machine (efi, bios) (#1452)

Endpoints

  •  /v2/vm/<id>/firmware (GET, PUT)
  • /v2/vss/vm-firmware (GET)

Description

Warning. If you have already deployed the virtual machine and would like to switch the firmware type, please test the process in a testing environment before attempting to perform it in a production VM.

To update an existent virtual machine firmware, simply make a PUT request to /v2/vm/<id>/firmware with the virtual machine powered off:

curl -x POST https://vss-api.eis.utornto.ca/v2/vm/vm-1234/firmware -H "Authorization: Bearer $TK" -d '{"value": "firmware"}'

Vm/Template conversion add more info to old/new value. (#1446)

Bug Fixes

VM/Template is marked on a domain without user permission (#1453)

VM/Disk backing_vmdk issue when mounting disk (#1454)

University of Toronto - Since 1827