VM template
2.9.1 Create a VM template
API endpoint
POST /NSphere/api/vm-template-resource
API description
Create a VM template. One of the VM ID or UUID is required.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"id": null,
"uuid": null,
"title": "",
"desc": null,
"opType": 2,
"disConnect": false,
"templateStoragePath": "/vms/images",
"scope": 0,
"saveOnHost": false
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiAddTemplateDTO | Add VM template entity. | body | true | ApiAddTemplateDTO | ApiAddTemplateDTO |
id | VM ID. | false | integer(int64) | ||
uuid | VM UUID. Required when the VM ID is not provided. | false | string | ||
title | VM template display name. | true | string | ||
desc | VM template description. | false | string | ||
opType | How to create the VM template. 1 = clone as template, 2 = convert to template. When the VM is running or paused, converting to template is not allowed. | true | integer(int32) | ||
disConnect | Whether to disconnect the VM's CD/floppy drives. true: automatically disconnect the CD/floppy drives; false: do not disconnect them — if a CD or floppy drive is mounted, the template cannot be created. Defaults to false. | false | boolean | ||
templateStoragePath | Template storage directory. | true | string | ||
scope | Visibility scope of the VM template. Defaults to private. 0 = private, 1 = public. | false | integer(int32) | ||
saveOnHost | Whether to save on host storage. Defaults to false. | true | boolean |
Response status
Response code | Description | schema |
200 | OK | ApiResponseApiTaskMsgVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success. | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message. | string | |
failureMessage | Error message. Valid when the result is failure or partial success. | string | |
data | Response data. When the status code is 0 this contains the normal returned data; when non-zero and non-empty it contains the data required to describe the exception. | ApiTaskMsgVO | ApiTaskMsgVO |
msgId | Message ID. Can be used to query task progress. | integer(int64) | |
targetId | ID of the object the task acts on. | integer(int64) | |
targetName | Name of the object the task acts on. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}
2.9.2 Edit a VM template
API endpoint
PUT /NSphere/api/vm-template-resource
API description
Edit a VM template. After a fast deployment, the template's name and disk size can no longer be modified.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"id": 0,
"title": "",
"description": null,
"cpuCore": 0,
"cpuSocket": 0,
"memoryInit": 0,
"memoryUnit": "GB",
"templetStoragePath": "",
"storageList": [
{
"id": 0,
"storeFile": "",
"capacity": 0
}
]
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiModifyTemplateDTO | Edit VM template entity. | body | true | ApiModifyTemplateDTO | ApiModifyTemplateDTO |
id | VM template ID. | true | integer(int64) | ||
title | VM template display name. | true | string | ||
description | VM template description. | false | string | ||
cpuCore | Number of VM CPU cores. | true | integer(int32) | ||
cpuSocket | Number of VM CPU sockets. | true | integer(int32) | ||
memoryInit | VM memory value. When | true | integer(int32) | ||
memoryUnit | VM memory unit. Allowed values: MB, GB. | true | string | ||
templetStoragePath | Template storage path. | true | string | ||
storageList | true | array | Storage | ||
id | Storage ID. | true | integer(int64) | ||
storeFile | Storage path. | true | string | ||
capacity | Storage capacity, in MB. Range: current storage minimum to 16776192. | true | integer(int64) |
Response status
Response code | Description | schema |
200 | OK | ApiResponseApiTaskMsgVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success. | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message. | string | |
failureMessage | Error message. Valid when the result is failure or partial success. | string | |
data | Response data. When the status code is 0 this contains the normal returned data; when non-zero and non-empty it contains the data required to describe the exception. | ApiTaskMsgVO | ApiTaskMsgVO |
msgId | Message ID. Can be used to query task progress. | integer(int64) | |
targetId | ID of the object the task acts on. | integer(int64) | |
targetName | Name of the object the task acts on. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}
2.9.3 Delete a VM template
API endpoint
DELETE /NSphere/api/vm-template-resource
API description
One of the VM template ID or UUID is required. On successful task creation, the task ID is returned.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
id | VM template ID. | query | false | integer(int64) | |
uuid | VM template UUID. Required when the VM template ID is not provided. | query | false | string |
Response status
Response code | Description | schema |
200 | OK | ApiResponseLong |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success. | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message. | string | |
failureMessage | Error message. Valid when the result is failure or partial success. | string | |
data | Response data. When the status code is 0 this contains the normal returned data; when non-zero and non-empty it contains the data required to describe the exception. | integer(int64) | integer(int64) |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": null
}
2.9.4 Get VM template details
API endpoint
GET /NSphere/api/vm-template-resource/{id}
API description
Get VM template details. Changed in E0930: the response now includes the VM template's network information.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
id | VM template ID. | path | true | integer(int64) |
Response status
Response code | Description | schema |
200 | OK | ApiResponseApiVmTemplateDetailVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success. | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message. | string | |
failureMessage | Error message. Valid when the result is failure or partial success. | string | |
data | Response data. When the status code is 0 this contains the normal returned data; when non-zero and non-empty it contains the data required to describe the exception. | ApiVmTemplateDetailVO | ApiVmTemplateDetailVO |
id | VM template ID. | integer(int64) | |
uuid | VM template UUID. | string | |
name | VM template name. | string | |
title | VM template display name. | string | |
description | VM template description. | string | |
status | VM template status. 0: normal; 1: maintenance. Templates with image update enabled enter maintenance status. | integer(int32) | |
cpu | Number of virtual CPUs on the VM (CPU sockets × CPU cores). | integer(int32) | |
createDate | VM template creation time. | string(date-time) | |
memory | Memory, in MB. | integer(int64) | |
memoryFormat | Memory (with unit). | string | |
memoryInit | Displayed memory. | number(double) | |
memoryUnit | Memory unit. | string | |
osVersion | Operating system information of the VM template. | string | |
storageCapacity | Template storage size, in MB. | integer(int64) | |
storageCapacityFormat | Storage size (with unit). | string | |
system | Operating system installed in the VM template. Values: 0 = Windows, 1 = Linux, 2 = BSD. | integer(int32) | |
templetStoragePath | Template storage path. | string | |
hugePage | Whether huge pages are enabled. | boolean | |
kernelType | VM kernel type. 1: aarch64; 0: i686 (32-bit) or x86_64. | integer(int32) | |
cpuSocket | Number of VM CPU sockets. | integer(int32) | |
cpuCore | Number of VM CPU cores. | integer(int32) | |
scope | Visibility scope of the VM template. 0 = private, 1 = public. | integer(int32) | |
hostId | Host on which the VM template resides. | integer(int64) | |
hostName | Name of the host on which the VM template resides. | string | |
hostKernelType | Kernel type of the host on which the VM template resides. 1: arm, 0: x86. | integer(int32) | |
enableUltra | Whether the VM has Ultra mode enabled. 1: enabled; 0 or empty: not enabled. | integer(int32) | |
clusterId | Cluster ID. New attribute in E0930. | integer(int64) | |
type | External cloud resource type of the VM template (typically 2, i.e. CVM). New attribute in E0930. | integer(int32) | |
deployed | Whether fast deployment has been performed. | boolean | |
encryptPw | Whether the template contains an encrypted disk. | boolean | |
storageList | VM template storage entities. | array | ApiVmTemplateStorageVO |
id | Storage ID. | integer(int64) | |
storeFile | Storage file name. | string | |
capacity | Capacity. Unit: MB. | integer(int64) | |
targetBus | Bus type. ide: IDE disk, scsi: SCSI disk, usb: USB disk, virtio: high-speed disk, virtioScsi: high-speed SCSI disk. | string | |
type | Storage type. file: file, block: block device, network: network device. | string | |
device | Device name, e.g. vda, vdb. | string | |
format | Access mode. Read-Write (Read-Writ), Read-ForceWrite, Read-Only. | string | |
driveType | Storage volume type. raw, qcow2. | string | |
assignType | Allocation type. 0 = fixed, 1 = dynamic. | integer(int32) | |
diskDevice | Disk type. disk: hard disk, cdrom: CD drive, floppy: floppy drive. | string | |
mode | Pre-allocation format. Values: 0 = lazy zero, 1 = zero, 2 = thin. | integer(int32) | |
diskSecret | Whether the disk is encrypted. | boolean | |
diskSecUuid | Encrypted disk UUID. | string | |
networkList | VM template network entities. New attribute in E0930. | array | ApiVmTemplateNetworkVO |
id | Network ID. | integer(int64) | |
mac | NIC MAC address. | string | |
vswitchName | vSwitch name. | string | |
vlan | VLAN value. | string | |
outAvgBand | Outbound average bandwidth, in Kbps. | integer(int64) | |
inAvgBand | Inbound average bandwidth, in Kbps. | integer(int64) | |
inBurst | Inbound burst buffer size, in KBytes. | integer(int64) | |
outBurst | Outbound burst buffer size, in KBytes. | integer(int64) | |
mode | NIC forwarding mode. Possible values: vepa, dvs, veb, server. | string | |
profileName | Network policy template name. | string | |
portgroupUUID | VXLAN port group UUID. | string | |
networkPortGroupId | Port group ID. | integer(int64) | |
networkPortGroupName | Port group name. | string | |
netLimitProfileId | Network rate-limit policy ID. | integer(int64) | |
netLimitProfileName | Network rate-limit policy name. | string | |
isDpdk | Whether DPDK is enabled. | boolean |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"id": null,
"uuid": null,
"name": null,
"title": null,
"description": null,
"status": null,
"cpu": null,
"createDate": null,
"memory": null,
"memoryFormat": null,
"memoryInit": null,
"memoryUnit": null,
"osVersion": null,
"storageCapacity": null,
"storageCapacityFormat": null,
"system": null,
"templetStoragePath": null,
"hugePage": true,
"kernelType": null,
"cpuSocket": null,
"cpuCore": null,
"scope": null,
"hostId": null,
"hostName": null,
"hostKernelType": null,
"enableUltra": null,
"clusterId": null,
"type": null,
"deployed": true,
"encryptPw": true,
"storageList": [
{
"id": null,
"storeFile": null,
"capacity": null,
"targetBus": null,
"type": null,
"device": null,
"format": null,
"driveType": null,
"assignType": null,
"diskDevice": null,
"mode": null,
"diskSecret": true,
"diskSecUuid": null
}
],
"networkList": [
{
"id": null,
"mac": null,
"vswitchName": null,
"vlan": null,
"outAvgBand": null,
"inAvgBand": null,
"inBurst": null,
"outBurst": null,
"mode": null,
"profileName": null,
"portgroupUUID": null,
"networkPortGroupId": null,
"networkPortGroupName": null,
"netLimitProfileId": null,
"netLimitProfileName": null,
"isDpdk": true
}
]
}
}
2.9.5 Distribute a VM template
API endpoint
PUT /NSphere/api/vm-template-resource/distribution
API description
Distribute a VM template.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"id": 0,
"targetHostId": 0,
"storagePoolName": "",
"storagePoolTitle": "",
"cover": true
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiTemplateDistributionParaDTO | Distribute VM template entity. | body | true | ApiTemplateDistributionParaDTO | ApiTemplateDistributionParaDTO |
id | VM template ID. | true | integer(int64) | ||
targetHostId | Target host ID. | true | integer(int64) | ||
storagePoolName | Target storage pool name. | true | string | ||
storagePoolTitle | Target storage pool display name. | true | string | ||
cover | Whether to overwrite. true = overwrite, false = do not overwrite. | true | boolean |
Response status
Response code | Description | schema |
200 | OK | ApiResponseApiTaskMsgVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success. | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message. | string | |
failureMessage | Error message. Valid when the result is failure or partial success. | string | |
data | Response data. When the status code is 0 this contains the normal returned data; when non-zero and non-empty it contains the data required to describe the exception. | ApiTaskMsgVO | ApiTaskMsgVO |
msgId | Message ID. Can be used to query task progress. | integer(int64) | |
targetId | ID of the object the task acts on. | integer(int64) | |
targetName | Name of the object the task acts on. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}
2.9.6 List VM templates
API endpoint
GET /NSphere/api/vm-template-resource/list
API description
List VM templates. In E0930 the API adds new parameters and response attributes.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
offset | Offset. Specifies the record from which to start returning results. Defaults to 0. | query | false | integer(int32) | |
limit | Maximum number of records returned per page. Defaults to 10. | query | false | integer(int32) | |
sortDir | Sort type: 0 = no sort, 1 = ascending, 2 = descending. Defaults to no sort when sortField is not empty. | query | false | integer(int32) | |
sortField | Sort field. Supported: title, description, cpu, memory, system, kernelType, templetStoragePath, scope, createDate. | query | false | string | |
hostId | Host ID. New parameter in E0930. | query | false | integer(int64) | |
title | VM template display name. Supports fuzzy match. New parameter in E0930. | query | false | string | |
domainName | VM template name. Supports fuzzy match. New parameter in E0930. | query | false | string | |
description | VM template description. Supports fuzzy match. New parameter in E0930. | query | false | string | |
operTimeFrom | Start creation time of the VM template. New parameter in E0930. | query | false | string | |
operTimeTo | End creation time of the VM template. New parameter in E0930. | query | false | string | |
kernelType | VM kernel type. 1: aarch64; 0: i686 (32-bit) or x86_64. New parameter in E0930. | query | false | integer(int32) | |
scope | Owner of the VM template. 0 = private, 1 = public. New parameter in E0930. | query | false | integer(int32) | |
enableUltra | Whether the VM has Ultra mode enabled. 1: enabled; 0: not enabled. New parameter in E0930. | query | false | integer(int32) | |
kaasVm | Whether the template is a container VM template. New parameter in E0930. | query | false | boolean |
Response status
Response code | Description | schema |
200 | OK | ApiResponseApiPagingListResultApiVmTemplateBasicVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success. | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message. | string | |
failureMessage | Error message. Valid when the result is failure or partial success. | string | |
data | Response data. When the status code is 0 this contains the normal returned data; when non-zero and non-empty it contains the data required to describe the exception. | ApiPagingListResultApiVmTemplateBasicVO | ApiPagingListResultApiVmTemplateBasicVO |
data | VM template summary information. | array | ApiVmTemplateBasicVO |
id | VM template ID. | integer(int64) | |
uuid | VM template UUID. | string | |
name | VM template name. | string | |
title | VM template display name. | string | |
description | VM template description. | string | |
status | VM template status. 0: normal; 1: maintenance. Templates with image update enabled enter maintenance status. | integer(int32) | |
cpu | Number of virtual CPUs on the VM (CPU sockets × CPU cores). | integer(int32) | |
createDate | VM template creation time. | string(date-time) | |
memory | Memory, in MB. | integer(int64) | |
memoryFormat | Memory (with unit). | string | |
memoryInit | Displayed memory. | number(double) | |
memoryUnit | Memory unit. | string | |
osVersion | Operating system information of the VM template. | string | |
storageCapacity | Template storage size, in MB. | integer(int64) | |
storageCapacityFormat | Storage size (with unit). | string | |
system | Operating system installed in the VM template. Values: 0 = Windows, 1 = Linux, 2 = BSD. | integer(int32) | |
templetStoragePath | Template storage path. | string | |
hugePage | Whether huge pages are enabled. | boolean | |
kernelType | VM kernel type. 1: aarch64; 0: i686 (32-bit) or x86_64. | integer(int32) | |
cpuSocket | Number of VM CPU sockets. | integer(int32) | |
cpuCore | Number of VM CPU cores. | integer(int32) | |
scope | Visibility scope of the VM template. 0 = private, 1 = public. | integer(int32) | |
hostId | Host on which the VM template resides. | integer(int64) | |
hostName | Name of the host on which the VM template resides. | string | |
hostKernelType | Kernel type of the host on which the VM template resides. 1: arm, 0: x86. | integer(int32) | |
enableUltra | Whether the VM has Ultra mode enabled. 1: enabled; 0 or empty: not enabled. | integer(int32) | |
clusterId | Cluster ID. New attribute in E0930. | integer(int64) | |
type | External cloud resource type of the VM template (typically 2, i.e. CVM). New attribute in E0930. | integer(int32) | |
offset | Offset. Specifies the record from which to start returning results. | integer(int32) | |
size | Number of records returned in this response. | integer(int32) | |
total | Total number of records. | integer(int64) |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"data": [
{
"id": null,
"uuid": null,
"name": null,
"title": null,
"description": null,
"status": null,
"cpu": null,
"createDate": null,
"memory": null,
"memoryFormat": null,
"memoryInit": null,
"memoryUnit": null,
"osVersion": null,
"storageCapacity": null,
"storageCapacityFormat": null,
"system": null,
"templetStoragePath": null,
"hugePage": true,
"kernelType": null,
"cpuSocket": null,
"cpuCore": null,
"scope": null,
"hostId": null,
"hostName": null,
"hostKernelType": null,
"enableUltra": null,
"clusterId": null,
"type": null
}
],
"offset": null,
"size": null,
"total": null
}
}