VM Instance Operations

CreateVmInstance

API Request

URLs

POST zstack/v1/vm-instances

Headers

Authorization: OAuth the-session-uuid

Body

{   "params": {     "name": "vm1",     "instanceOfferingUuid": "ae97ced44efc3314b8f7798972b4ba1a",     "imageUuid": "da119f7906513eccabf271991c35a65e",     "l3NetworkUuids": [       "cc0e4c5e77df3af68e59668e7f9e06c5"     ],     "dataDiskOfferingUuids": [       "19d22d051b063d379a2816daaf431838",       "905d94a6abb5398fa1995f6398e3f6fc"     ],     "clusterUuid": "a0468dc645223f67bd0f2ab95276bbae",     "description": "this is a vm",     "strategy": "InstantStart"   },   "systemTags": [],   "userTags": [] }

Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"vm1","instanceOfferingUuid":"ae97ced44efc3314b8f7798972b4ba1a","imageUuid":"da119f7906513eccabf271991c35a65e","l3NetworkUuids":["cc0e4c5e77df3af68e59668e7f9e06c5"],"dataDiskOfferingUuids":["19d22d051b063d379a2816daaf431838","905d94a6abb5398fa1995f6398e3f6fc"],"clusterUuid":"a0468dc645223f67bd0f2ab95276bbae","description":"this is a vm","strategy":"InstantStart"}}' \ http://localhost:8080/zstack/v1/vm-instances

Request Parameters

Name	Type	Location	Description	Optional Value	Starting Version
name	String	body (contained in the params structure)	The VM instance name.		0.6
instanceOfferingUuid	String	body (contained in the params structure)	The instance offering UUID. Specifies the CPU, memory, and other parameters of the VM instance.		0.6
imageUuid	String	body (contained in the params structure)	The image UUID. Specifies the image from which the root volume of the VM instance is created.		0.6
l3NetworkUuids	List	body (contained in the params structure)	The L3 network UUID list. You can specify one or more L3 networks. Then the VM instance will create a NIC on each network.		0.6
type	String	body (contained in the params structure)	Optional. The VM instance type. This parameter is a reserved field for internal use.	UserVm ApplianceVm	0.6
rootDiskOfferingUuid	String	body (contained in the params structure)	Optional. The disk offering UUID of the root volume. If the image type specified in imageUuid is ISO, you must specify rootDiskOfferingUuid to determine the size of the root volume to be created. If the image type is not ISO, this parameter is optional.		0.6
dataDiskOfferingUuids	List	body (contained in the params structure)	Optional. The disk offering UUID list. You can specify one or more disk offering UUIDs to create one or more data volumes for the VM instance. (The UUIDs can be repeated.)		0.6
zoneUuid	String	body (contained in the params structure)	Optional. The zone UUID. If specified, the VM instance will be created in the specified zone.		0.6
clusterUuid	String	body (contained in the params structure)	Optional. The cluster UUID. If specified, the VM instance will be created in the specified cluster. This parameter can override zoneUuid.		0.6
hostUuid	String	body (contained in the params structure)	Optional. The host UUID. If specified, the VM instance will be created on the specified host. This parameter can override zoneUuid and clusterUuid.		0.6
primaryStorageUuidForRootVolume	String	body (contained in the params structure)	Optional. The primary storage UUID. If specified, the root volume of the VM instance will be created on the specified primary storage.		1.8
description	String	body (contained in the params structure)	Optional. The detailed description of the VM instance.		0.6
defaultL3NetworkUuid	String	body (contained in the params structure)	Optional. The UUID of the default L3 network. If multiple L3 networks are specified in l3NetworkUuids, this parameter specifies the L3 network that provides default routing. If not specified, the first network specified in `l3NetworkUuids` will be used as the default network.		0.6
resourceUuid	String	body (contained in the params structure)	Optional. The resource UUID. If specified, the VM instance will use the specified value as UUID.		0.6
tagUuids	List	body (contained in the params structure)	Optional. The tag UUID list.		3.4.0
systemTags	List	body	Optional. The system tags of the VM instance.		0.6
userTags	List	body	Optional. The user tags of the VM instance.		0.6
strategy	String	body (contained in the params structure)	Optional. The VM instance creation strategy. Start the VM instance immediately after creation. Do not start the VM instance after creation.		0.6

Note:

When you create a VM instance in ZStack, you can specify an affinity group by adding the affinityGroup option to SystemTags.
- Format of the affinityGroup option: affinityGroupUuid::UUID
- Example: affinityGroupUuid::5fd71606d5af451d981413f35367a8d6
When you create a VM instance in ZStack, you can specify a PCI device by adding the PCI option to SystemTags.
- Format of the PCI option: pciDevice::UUID
- Example: pciDevice::634b48a7bca139d9944a0f95b0c2dddf
When you create a VM instance in ZStack, you can bind a CPU by adding the vmCpuPinning option to SystemTags.
- Format of the vmCpuPinning option: vmCpuPinning::binding policy
- Example: vmCpuPinning::1:3;1-3:4-7,^6
- Only the administrator can update, create, or delete the SystemTag. When you clone a VM instance, you will also clone this SystemTag.
When you create a VM instance in ZStack, you can use the userdata feature by adding the userdata option to SystemTags.
- Format of the userdata option: userdata::base64 encoded script
- Example: userdata::I2Nsb3VkLWNvbmZpZwp1c2VyczoKIC0gbmFtZTogdGVzdAogICBzaGVsbDogL2Jpbi9iYXNoCiAgIGdyb3VwczogdXNlcnMKICAgc3VkbzogWydBTEw9KEFMTCkgTk9QQVNTV0Q6QUxMJ10KICAgc3NoLWF1dGhvcml6ZWQta2V5czoKICAgICAgIC0gc3NoLXJzYSBBQUFBQjNOemFDMUxYQ0pmanJvRDFsVCByb290QDEwLTAtMC0xOApib290Y21kOgogLSBta2RpciAvdG1wL3RlbXAgCndyaXRlX2ZpbGVzOgogLSBwYXRoOiAvdG1wL1pTdGFja19jb25maWcKICAgY29udGVudDogfAogICAgICAgSGVsbG8sd29ybGQhCiAgIHBlcm1pc3Npb25zOiAnMDc1NScKaG9zdG5hbWU6IFBlcmYtdGVzdApkaXNhYmxlX3Jvb3Q6IGZhbHNlCnNzaF9wd2F1dGg6IHllcwpjaHBhc3N3ZDoKICBsaXN0OiB8CiAgICAgIHJvb3Q6d29yZAogIGV4cGlyZTogRmFsc2UKcnVuY21kOgogLSBlY2hvIGxzIC1sIC8gPi9yb290L2xpc3Quc2g=
When you create a VM instance in ZStack, you can specify an SSH key by adding the sshkey option to SystemTags.
- Format of the sshkey option: sshkey::public key content
- Example: sshkey::ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDPAGDmLG2yW1fGQsek4PdBL6wiVMHuLrl566ITPAf8A2Oi5BaExoUwdPjA96OaUSrtlsKlrXUMGEJwN1r1TrL9JdUMg7jww3QysGuS3P+bRsBe1TSGHS8LNc9JY9HpoL4ZN/j0zTaZfju9eDzbVsbDrF91x3yDeeGH6IG6gWJn96HPfrlg7REfo04eBdflsTaaFC0lAXoBOrnGVnzRdQfwTNRGmMAyFzCV83HOhVzBJuL5VqtAT8a0lSC4QgZTNROh6zbkTUUYYQu0QS65EaJCTyAhksuidRzyjLX3p3oMileKdJNugRa5IDHhGJXExIK+58Nvaqfj/03yN8IfO7sj root@hpe-77
When you create a VM instance in ZStack, you can specify the high availability (HA) level by adding the ha option to SystemTags.
- Format of the ha option: ha::NeverStop
- Example: ha::NeverStop
When you create a VM instance in ZStack, you can specify the console mode by adding the vmConsoleMode option to SystemTags.
- Format of the vmConsoleMode option: vmConsoleMode::console mode
- Example: vmConsoleMode::spice or vmConsoleMode::vnc
When you create a VM instance in ZStack, you can specify the USB redirection by adding the usbRedirect option to SystemTags.
- Format of the usbRedirect option: usbRedirect::true
- Example: usbRedirect::true
When you create a VM instance in ZStack, you can specify the console password by adding the consolePassword option to SystemTags.
- Format of the consolePassword option: consolePassword::console password
- Example: consolePassword::123456
When you create a VM instance in ZStack, you can specify an IP address for the L3 network by adding the staticIp option to SystemTags. If the network address type is double stack (IPv4+IPv6), you can add two staticIp options, which are IPv4 and IPv6, respectively.
- Format of the staticIp option: staticIp::L3 network UUID::specified IP
- Example: staticIp::81a21a81cde84c1084c191354053a3b5::172.20.196.0
When you create a VM instance in ZStack, you can specify the MAC address of the corresponding NIC on the L3 network by adding the customMac option to SystemTags.
- Format of the customMac option: customMac::L3 network UUID::specified MAC address
- Example: customMac::81a21a81cde84c1084c191354053a3b5::fa:00:37:ee:9f:00
When you create a VM instance in ZStack, you can specify the volume provisioning strategy by adding the volumeProvisioningStrategy option to SystemTags. The SystemTag is passed by using the rootVolumeSystemTags parameter.
- Format of the volumeProvisioningStrategy option: volumeProvisioningStrategy::ThinProvisioning, volumeProvisioningStrategy::ThickProvisioning
- Example: volumeProvisioningStrategy::ThinProvisioning, volumeProvisioningStrategy::ThickProvisioning
When you create a VM instance in ZStack, you can specify the Ceph pool where the root volume is located by adding the rootPoolName option to SystemTags. The SystemTag is passed by using the rootPoolName parameter.
- Format of the rootPoolName option: ceph::rootPoolName::xxx. Here, xxx is the pool name.
- Example: ceph::rootPoolName::pri-v-r-26e11ca6814d4e1ba504d845f7848db3
When you create a VM instance in ZStack, you can specify the mother board type by adding the vmMachineType option to SystemTags. The SystemTag is passed by using the vmMachineType parameter.
- Format of the vmMachineType option: vmMachineType::xx. Here, xx is pc or q35.
- Example: vmMachineType::pc
When you create a VM instance in ZStack, you can specify the CD-ROM list by adding the cdroms option to SystemTags. The SystemTag is passed by using the cdroms parameter.
- Format of the cdroms option: cdroms::${cdrom-1 config}::${cdrom-2 config}::${cdrom-3 config}. The CD-ROM configuration (cdrom config) has three options: iso uuid (the UUID of the ISO to be attached by the CD-ROM), empty (do not select any ISO), and none (do not configure the CD-ROM).
- Examples:
  - Create an empty list: cdrom: cdroms::empty::none::none
  - Create three empty lists: cdrom: cdroms::empty::empty::empty
  - Create three lists with ISO attached: cdrom：cdroms::iso_1_uuid::iso_2_uuid::iso_3_uuid
When you create a VM instance in ZStack, you can choose not to create any CD-ROM by adding the createWithoutCdRom option to SystemTags. The SystemTag is passed by using the createWithoutCdRom parameter.
- Format of the createWithoutCdRom option: createWithoutCdRom::true
- Example: createWithoutCdRom::true
When you create a VM instance in ZStack, you can specify a MDEV device by adding the mdevDevice option to SystemTags.
- Format of the mdevDevice option: mdevDevice::MDEV_DEV_UUID
- Example: mdevDevice::e2af8f869eff49d2a3d6f86cadc27090
When you create a VM instance in ZStack, you can specify whether to automatically uninstall the physical PCI device allocated from the device specifications when the VM instance is shut down. You can also delete or change the configurations of existing VM instances. Note that you can add the autoReleaseSpecReleatedPhysicalPciDevice option to SystemTags.
- Format of the autoReleaseSpecReleatedPhysicalPciDevice option: autoReleaseSpecReleatedPhysicalPciDevice
- Example: autoReleaseSpecReleatedPhysicalPciDevice
When you create a VM instance in ZStack, you can specify whether to automatically uninstall the virtual PCI device allocated from the device specifications when the VM instance is shut down. You can also delete or change the configurations of existing VM instances. Note that you can add the autoReleaseSpecReleatedVirtualPciDevice option to SystemTags.
- Format of the autoReleaseSpecReleatedVirtualPciDevice option: autoReleaseSpecReleatedVirtualPciDevice
- Example: autoReleaseSpecReleatedVirtualPciDevice
When you create a VM instance in ZStack, you can specify the MDEV device specification and the device count allocated from the specification by adding the mdevDeviceSpec option to SystemTags.
- Format of the mdevDeviceSpec option: mdevDeviceSpec::MDEV_SPEC_UUID::MDEV_DEV_NUM
- Example: mdevDeviceSpec::e2af8f869eff49d2a3d6f86cadc27090::4
When you create a VM instance in ZStack, you can specify the PCI device specification and the device count allocated from the specification by adding the pciDeviceSpec option to SystemTags.
- Format of the pciDeviceSpec option: pciDeviceSpec::PCI_SPEC_UUID::PCI_DEV_NUM
- Example: pciDeviceSpec::e2af8f869eff49d2a3d6f86cadc27090::4
When you create a VM instance in ZStack, you can specify the resource priority by adding the vmPriority option to SystemTags.
- Format of the vmPriority option: vmPriority::PRIORITY_LEVEL. Here, PRIORITY_LEVEL can be Normal or High.
- Example: vmPriority::Normal
When you create a VM instance in ZStack, the cloud records the version of the GuestTools ISO installed in the VM instance, compares the ISO version with that of the host, and decides whether to upgrade the GuestTools ISO. Note that you can add the GuestTools option to SystemTags.
- Format of the GuestTools option: GuestTools::TOOLS_VERSION. Here, the initial value of TOOLS_VERSION is 1.0.0. This value will change as the version of GuestTools is upgraded.
- Example: GuestTools::1.0.0
- Note: When a VM instance is created from an image, if the image has the GuestTools tag, the value of the GuestTools tag will be copied from the image to the new VM instance.
When you create a VM instance in ZStack, you can set a cross-cluster HA policy by adding the resourceBindings option to SystemTags.
- Format of the resourceBindings option: resourceBindings::Cluster:clusterUuid. Here, clusterUuid is the UUID of the cluster.
- Example: resourceBindings::Cluster:2sdasf231jvznsdak
When you create a VM instance in ZStack, you can specify a hostname by adding the hostname option to SystemTags.
- Format of the hostname option: hostname::xxxxx. Here, xxxxx is the hostname.
- Example: hostname::host.zstack.org
When you create a VM instance in ZStack, you can enable SR-IOV by adding the enableSRIOV option to SystemTags.
- Format of the enableSRIOV option: enableSRIOV::{L3_NETWORK_UUID}
- Example: enableSRIOV::9e19dafe81c64fed8e34f72e27582339

API Response

Sample Response

{   "inventory": {     "uuid": "6efab7159c6932429c6b0e7e0b64b660",     "name": "Test-VM",     "description": "web server VM",     "zoneUuid": "d10bd7a9565138efaf6171db8e18fa7d",     "clusterUuid": "692c71639d873bf6a356cd8e285d0d9c",     "imageUuid": "28061e65e48037eda71b53a0732bf087",     "hostUuid": "f877177de7bd377e811bc6313878b2b1",     "lastHostUuid": "a3ccdc90a600334f994c69aee4270ac5",     "instanceOfferingUuid": "9a874241f867333ca0bf0ab2134f8515",     "rootVolumeUuid": "f52d7c94d69d3bbb97d36a270fe910c3",     "platform": "Linux",     "defaultL3NetworkUuid": "2ac1b70fdb0f38769a29c6ebd0262cca",     "type": "UserVm",     "hypervisorType": "KVM",     "memorySize": 8.589934592E9,     "cpuNum": 1.0,     "allocatorStrategy": "LastHostPreferredAllocatorStrategy",     "createDate": "Nov 14, 2017 10:20:57 PM",     "lastOpDate": "Nov 14, 2017 10:20:57 PM",     "state": "Running",     "vmNics": [       {         "uuid": "0dfbb8a297e9349ea8799c4ce48c6d10",         "vmInstanceUuid": "6efab7159c6932429c6b0e7e0b64b660",         "usedIpUuid": "39b57596a8ba35289bd9f40efceeae03",         "l3NetworkUuid": "2ac1b70fdb0f38769a29c6ebd0262cca",         "ip": "192.168.1.10",         "mac": "00:0c:29:bd:99:fc",         "netmask": "255.255.255.0",         "gateway": "192.168.1.1",         "deviceId": 0.0,         "createDate": "Nov 14, 2017 10:20:57 PM",         "lastOpDate": "Nov 14, 2017 10:20:57 PM"       }     ],     "allVolumes": [       {         "uuid": "f52d7c94d69d3bbb97d36a270fe910c3",         "name": "Root-Volume-For-VM-6efab7159c6932429c6b0e7e0b64b660",         "primaryStorageUuid": "4ed5bbb150a034b5917e7e6c9c4b8170",         "vmInstanceUuid": "6efab7159c6932429c6b0e7e0b64b660",         "diskOfferingUuid": "0521187274d73f5b936c22b145384c74",         "rootImageUuid": "28061e65e48037eda71b53a0732bf087",         "installPath": "/zstack_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-f52d7c94d69d3bbb97d36a270fe910c3/f52d7c94d69d3bbb97d36a270fe910c3.qcow2",         "type": "Root",         "format": "qcow2",         "size": 1.073741824E11,         "actualSize": 2.147483648E10,         "deviceId": 0.0,         "state": "Enabled",         "status": "Ready",         "createDate": "Nov 14, 2017 10:20:57 PM",         "lastOpDate": "Nov 14, 2017 10:20:57 PM"       }     ]   } }

Name	Type	Description	Starting Version
error	ErrorCode	The error code. If not null, the operation fails, or vice versa. For more information, see error.	0.6
inventory	VmInstanceInventory	See inventory.	0.6

#error

Name	Type	Description	Starting Version
code	String	The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001.	0.6
description	String	The brief description of the error.	0.6
details	String	The details about the error.	0.6
elaboration	String	The reserved field. Default value: null.	0.6
opaque	LinkedHashMap	The reserved field. Default value: null.	0.6
cause	ErrorCode	The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null.	0.6

#inventory

Name	Type	Description	Starting Version
uuid	String	The resource UUID.	0.6
name	String	The resource name.	0.6
description	String	The detailed description of the resource.	0.6
zoneUuid	String	The zone UUID.	0.6
clusterUuid	String	The cluster UUID.	0.6
imageUuid	String	The image UUID.	0.6
hostUuid	String	The host UUID.	0.6
lastHostUuid	String	The UUID of the host on which the VM instance was running last time.	0.6
instanceOfferingUuid	String	The instance offering UUID.	0.6
rootVolumeUuid	String	The root volume UUID.	0.6
platform	String	The platform on which the VM instance is running.	0.6
defaultL3NetworkUuid	String	The UUID of the default L3 network.	0.6
type	String	The VM instance type.	0.6
hypervisorType	String	The hypervisor type of the VM instance.	0.6
memorySize	Long	The memory size.	0.6
cpuNum	Integer	The CPU count.	0.6
cpuSpeed	Long	The CPU speed.	0.6
allocatorStrategy	String	The allocator strategy.	0.6
createDate	Timestamp	The creation date.	0.6
lastOpDate	Timestamp	The last operation date.	0.6
state	String	The state of the VM instance.	0.6
vmNics	List	See vmNics.	0.6
allVolumes	List	See allVolumes.	0.6

#vmNics

Name	Type	Description	Starting Version
uuid	String	The resource UUID.	0.6
vmInstanceUuid	String	The VM instance UUID.	0.6
l3NetworkUuid	String	The L3 network UUID.	0.6
ip	String	The IP address.	0.6
mac	String	The MAC address.	0.6
netmask	String	The netmask.	0.6
gateway	String	The gateway.	0.6
metaData	String	The reserved field for internal use.	0.6
deviceId	Integer	The device ID. An integer that indicates the order of NICs in the Ethernet device of the guest operating system. For example, 0 usually means eth0, and 1 usually means eth1.	0.6
createDate	Timestamp	The creation date.	0.6
lastOpDate	Timestamp	The last operation date.	0.6

#allVolumes

Name	Type	Description	Starting Version
uuid	String	The resource UUID.	0.6
name	String	The resource name.	0.6
description	String	The detailed description of the resource.	0.6
primaryStorageUuid	String	The primary storage UUID.	0.6
vmInstanceUuid	String	The VM instance UUID.	0.6
diskOfferingUuid	String	The disk offering UUID.	0.6
rootImageUuid	String	The UUID of the root volume image.	0.6
installPath	String	The installation path.	0.6
type	String	The volume type.	0.6
format	String	The volume format.	0.6
size	Long	The virtual size of the volume.	0.6
actualSize	Long	The actual size of the volume.	0.6
deviceId	Integer	The device ID.	0.6
state	String	The state of the volume.	0.6
status	String	The status of the volume.	0.6
createDate	Timestamp	The creation date.	0.6
lastOpDate	Timestamp	The last operation date.	0.6
isShareable	Boolean	Whether the volume can be shared.	0.6

SDK Sample

Java SDK

CreateVmInstanceAction action = new CreateVmInstanceAction(); action.name = "vm1"; action.instanceOfferingUuid = "ae97ced44efc3314b8f7798972b4ba1a"; action.imageUuid = "da119f7906513eccabf271991c35a65e"; action.l3NetworkUuids = asList("cc0e4c5e77df3af68e59668e7f9e06c5"); action.dataDiskOfferingUuids = asList("19d22d051b063d379a2816daaf431838","905d94a6abb5398fa1995f6398e3f6fc"); action.clusterUuid = "a0468dc645223f67bd0f2ab95276bbae"; action.description = "this is a vm"; action.strategy = "InstantStart"; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; CreateVmInstanceAction.Result res = action.call();

Python SDK

CreateVmInstanceAction action = CreateVmInstanceAction() action.name = "vm1" action.instanceOfferingUuid = "ae97ced44efc3314b8f7798972b4ba1a" action.imageUuid = "da119f7906513eccabf271991c35a65e" action.l3NetworkUuids = [cc0e4c5e77df3af68e59668e7f9e06c5] action.dataDiskOfferingUuids = [19d22d051b063d379a2816daaf431838, 905d94a6abb5398fa1995f6398e3f6fc] action.clusterUuid = "a0468dc645223f67bd0f2ab95276bbae" action.description = "this is a vm" action.strategy = "InstantStart" action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" CreateVmInstanceAction.Result res = action.call()

CreateVmInstanceFromVolume

API Request

URLs

POST zstack/v1/vm-instances/from/volume

Headers

Authorization: OAuth the-session-uuid

Body

{   "params": {     "name": "vm1",     "description": "this is a vm",     "instanceOfferingUuid": "80c606e35bc038bbb102e31cae191ea2",     "l3NetworkUuids": [       "333817afcaf63f13a101f674761c8a77"     ],     "volumeUuid": "23984cd68b903fd4883aa962c70d83fc",     "clusterUuid": "ada53eb6c42e34d3946ff1280718d9f2",     "strategy": "InstantStart"   },   "systemTags": [],   "userTags": [] }

Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"vm1","description":"this is a vm","instanceOfferingUuid":"80c606e35bc038bbb102e31cae191ea2","l3NetworkUuids":["333817afcaf63f13a101f674761c8a77"],"volumeUuid":"23984cd68b903fd4883aa962c70d83fc","clusterUuid":"ada53eb6c42e34d3946ff1280718d9f2","strategy":"InstantStart"}}' http://localhost:8080/zstack/v1/vm-instances/from/volume

Request Parameters

Name	Type	Location	Description	Optional Value	Starting Version
name	String	body (contained in the params structure)	The resource name.		3.10.0
description	String	body (contained in the params structure)	Optional. The detailed description of the resource.		3.10.0
instanceOfferingUuid	String	body (contained in the params structure)	Optional. The instance offering UUID. Note: This parameter is optional if you choose the CPU number and memory size.		3.10.0
cpuNum	Integer	body (contained in the params structure)	Optional. The CPU number or memory size. Note: This parameter is optional if you choose instanceOfferingUuid.		3.10.0
memorySize	Long	body (contained in the params structure)			3.10.0
l3NetworkUuids	List	body (contained in the params structure)	The L3 network UUID. Specifies one or more L3 networks. The VM instance will create one NIC on each L3 network.		3.10.0
type	String	body (contained in the params structure)	Optional. The VM type. The reserved field, which is no need to specify.	UserVm ApplianceVm	3.10.0
volumeUuid	String	body (contained in the params structure)	Optional. The volume UUID.		3.10.0
platform	String	body (contained in the params structure)	Optional. The volume system platform.	Linux Windows Other	3.10.0
zoneUuid	String	body (contained in the params structure)	Optional. The zone UUID. If specified, the VM instance will will be created in the specified zone.		3.10.0
clusterUuid	String	body (contained in the params structure)	Optional. The cluster UUID. If specified, the VM instance will be created in the specified cluster. The resource priority of this parameter is higher than zoneUuid.		3.10.0
hostUuid	String	body (contained in the params structure)	Optional. The host UUID. If specified, the VM instance will be created in the specified host. The resource priority of this parameter is higher than zoneUuid and clusterUuid.		3.10.0
primaryStorageUuid	String	body (contained in the params structure)	Optional. The primary storage UUID. If specified, the root volume of the VM instance will be created in the specified primary storage.		3.10.0
defaultL3NetworkUuid	String	body (contained in the params structure)	Optional. The default L3 network UUID. When l3NetworkUuids specifies multiple L3 networks, this parameter specifies to provide the default L3 network. If not specified, the first network of `l3NetworkUuids` will be selected as the default network.		3.10.0
strategy	String	body (contained in the params structure)	Optional. The VM creation strategy. After the VM instance is created, the VM instance is started immediately. After the VM instance is created, the VM instance will not be started.	InstantStart CreateStopped	3.10.0
resourceUuid	String	body (contained in the params structure)	Optional. The resource UUID. If specified, the VM instance will use this field as UUID.		3.10.0
tagUuids	List	body (contained in the params structure)	Optional. The tag UUID list.		3.10.0
systemTags	List	body	Optional. The system tags.		3.10.0
userTags	List	body	Optional. The user tags.		3.10.0

API返回

返回示例

{   "inventory": {     "uuid": "33614668ae7d386c91d662928f60b23f",     "name": "Test-VM",     "description": "web server VM",     "zoneUuid": "62f048b02e353ba4bdb9184ad7f54170",     "clusterUuid": "ff753adc06c83d5ab2b0291f57b4745a",     "imageUuid": "9291412f184f37a284b484b0788b24ca",     "hostUuid": "0f9f5c6561d733d18a94577c4cd0976f",     "lastHostUuid": "dc452dde2f7832b29bf91a0ddb6a004c",     "instanceOfferingUuid": "b35adab33ba139b98ee20c1e2be702d3",     "rootVolumeUuid": "f54fc6d488133688a6a7635f5c44a288",     "platform": "Linux",     "defaultL3NetworkUuid": "d82e3c622f933054a1939fb66e07681e",     "type": "UserVm",     "hypervisorType": "KVM",     "memorySize": 8.589934592E9,     "cpuNum": 1.0,     "allocatorStrategy": "LastHostPreferredAllocatorStrategy",     "createDate": "Nov 14, 2017 10:20:57 PM",     "lastOpDate": "Nov 14, 2017 10:20:57 PM",     "state": "Running",     "vmNics": [       {         "uuid": "16198ebdef9c3f8084acd1a919eff4f2",         "vmInstanceUuid": "33614668ae7d386c91d662928f60b23f",         "usedIpUuid": "8eb3618f949a3e588acf9d8b0ee8293f",         "l3NetworkUuid": "d82e3c622f933054a1939fb66e07681e",         "ip": "192.168.1.10",         "mac": "00:0c:29:bd:99:fc",         "hypervisorType": "KVM",         "netmask": "255.255.255.0",         "gateway": "192.168.1.1",         "deviceId": 0.0,         "createDate": "Nov 14, 2017 10:20:57 PM",         "lastOpDate": "Nov 14, 2017 10:20:57 PM"       }     ],     "allVolumes": [       {         "uuid": "f54fc6d488133688a6a7635f5c44a288",         "name": "Root-Volume-For-VM-33614668ae7d386c91d662928f60b23f",         "primaryStorageUuid": "769061e63aec3278b1e6c3619d6da766",         "vmInstanceUuid": "33614668ae7d386c91d662928f60b23f",         "rootImageUuid": "9291412f184f37a284b484b0788b24ca",         "installPath": "/zstack_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-f54fc6d488133688a6a7635f5c44a288/f54fc6d488133688a6a7635f5c44a288.qcow2",         "type": "Root",         "format": "qcow2",         "size": 1.073741824E11,         "actualSize": 2.147483648E10,         "deviceId": 0.0,         "state": "Enabled",         "status": "Ready",         "createDate": "Nov 14, 2017 10:20:57 PM",         "lastOpDate": "Nov 14, 2017 10:20:57 PM"       }     ]   } }

Name	Type	Description	Starting Version
error	ErrorCode	The error code. If not null, the operation fails, or vice versa. For more information, see error.	3.10.0
inventory	VmInstanceInventory	See inventory.	3.10.0

#error

Name	Type	Description	Starting Version
code	String	The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001.	3.10.0
description	String	The brief description of the error.	3.10.0
details	String	The details about the error.	3.10.0
elaboration	String	The reserved field. Default value: null.	3.10.0
opaque	LinkedHashMap	The reserved field. Default value: null.	3.10.0
cause	ErrorCode	The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null.	3.10.0

#inventory

Name	Type	Description	Starting Version
uuid	String	The resource UUID.	3.10.0
name	String	The resource name.	3.10.0
description	String	The detailed description of the resource.	3.10.0
zoneUuid	String	The zone UUID.	3.10.0
clusterUuid	String	The cluster UUID.	3.10.0
imageUuid	String	The image UUID.	3.10.0
hostUuid	String	The host UUID.	3.10.0
lastHostUuid	String		3.10.0
instanceOfferingUuid	String	The instance offering UUID.	3.10.0
rootVolumeUuid	String	The root volume UUID.	3.10.0
platform	String		3.10.0
defaultL3NetworkUuid	String		3.10.0
type	String		3.10.0
hypervisorType	String		3.10.0
memorySize	Long		3.10.0
cpuNum	Integer		3.10.0
cpuSpeed	Long		3.10.0
allocatorStrategy	String		3.10.0
createDate	Timestamp	The creation date.	3.10.0
lastOpDate	Timestamp	The last operation date.	3.10.0
state	String		3.10.0
vmNics	List	See vmNics.	3.10.0
allVolumes	List	See allVolumes.	3.10.0

#vmNics

Name	Type	Description	Starting Version
uuid	String	The resource UUID.	3.10.0
vmInstanceUuid	String	The VM instance UUID.	3.10.0
l3NetworkUuid	String	The L3 network UUID.	3.10.0
ip	String	The IP address.	3.10.0
mac	String	The MAC address.	3.10.0
hypervisorType	String	The hypervisor type.	3.10.0
netmask	String	The netmask.	3.10.0
gateway	String	The gateway.	3.10.0
metaData	String	The reserved field for internal use.	3.10.0
ipVersion	Integer	The IP version.	3.10.0
deviceId	Integer	The device ID.	3.10.0
createDate	Timestamp	The creation date.	3.10.0
lastOpDate	Timestamp	The last operation date.	3.10.0
usedIps	List	See usedIps .	3.10.0

#usedIps

Name	Type	Description	Starting Version
uuid	String	The resource UUID.	3.10.0
ipRangeUuid	String	The IP range UUID.	3.10.0
l3NetworkUuid	String	The L3 network UUID.	3.10.0
ipVersion	Integer	The IP version.	3.10.0
ip	String	The IP address.	3.10.0
netmask	String	The netmask.	3.10.0
gateway	String	The gateway.	3.10.0
usedFor	String		3.10.0
ipInLong	long		3.10.0
vmNicUuid	String	The VM NIC　UUID ．	3.10.0
createDate	Timestamp	The creation date.	3.10.0
lastOpDate	Timestamp	The last operation date.	3.10.0

#allVolumes

Name	Type	Description	Starting Version
uuid	String	The resource UUID.	3.10.0
name	String	The resource name.	3.10.0
description	String	The detailed description of the resource.	3.10.0
primaryStorageUuid	String	The primary storage UUID.	3.10.0
vmInstanceUuid	String	The VM instance UUID.	3.10.0
diskOfferingUuid	String	The disk offering UUID.	3.10.0
rootImageUuid	String	The root image UUID.	3.10.0
installPath	String	The installation path of volume in the primary storage.	3.10.0
type	String	The volume type, including data volume and root volume.	3.10.0
format	String	The volume format.	3.10.0
size	Long	The volume size.	3.10.0
actualSize	Long	The actual volume size.	3.10.0
deviceId	Integer		3.10.0
state	String	Whether the volume is enabled.	3.10.0
status	String	The volume status.	3.10.0
createDate	Timestamp	The creation date.	3.10.0
lastOpDate	Timestamp	The last operation date.	3.10.0
isShareable	Boolean	Whether the volume is shared.	3.10.0
volumeQos	String	The volume QoS. Format: total=1048576.	3.10.0

SDK Sample

Java SDK

CreateVmInstanceFromVolumeAction action = new CreateVmInstanceFromVolumeAction(); action.name = "vm1"; action.description = "this is a vm"; action.instanceOfferingUuid = "80c606e35bc038bbb102e31cae191ea2"; action.l3NetworkUuids = asList("333817afcaf63f13a101f674761c8a77"); action.volumeUuid = "23984cd68b903fd4883aa962c70d83fc"; action.clusterUuid = "ada53eb6c42e34d3946ff1280718d9f2"; action.strategy = "InstantStart"; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; CreateVmInstanceFromVolumeAction.Result res = action.call();

Python SDK

CreateVmInstanceFromVolumeAction action = CreateVmInstanceFromVolumeAction() action.name = "vm1" action.description = "this is a vm" action.instanceOfferingUuid = "80c606e35bc038bbb102e31cae191ea2" action.l3NetworkUuids = [333817afcaf63f13a101f674761c8a77] action.volumeUuid = "23984cd68b903fd4883aa962c70d83fc" action.clusterUuid = "ada53eb6c42e34d3946ff1280718d9f2" action.strategy = "InstantStart" action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" CreateVmInstanceFromVolumeAction.Result res = action.call()

DestroyVmInstance

API Request

URLs

DELETE zstack/v1/vm-instances/{uuid}?deleteMode={deleteMode}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \ -H "Authorization: OAuth: 8d618c25ba3b4eb7bc6dda7e47d1b6b4" \ -X DELETE http://localhost:8080/zstack/v1/vm-instances/5e22e2b1c4ab40739cd0b7717368dfa7?deleteMode=Permissive

Request Parameters

Name	Type	Location	Description	Starting Version
uuid	String	url	The VM instance UUID.	0.6
deleteMode	String	body	Optional. The delete mode.	0.6
systemTags	List	body	Optional. The system tags.	0.6
userTags	List	body	Optional. The user tags.	0.6

API Response

When the API succeeded, an empty JSON structure {} is returned. When the API failed, the returned JSON structure includes an error field. For example,

{     "error": {         "code": "SYS.1001",         "description": "A message or a operation timeout",         "details": "Create VM on KVM timeout after 300s"     } }

SDK Sample

Java SDK

DestroyVmInstanceAction action = new DestroyVmInstanceAction(); action.uuid = "c0b82973fbed42a09f3a30ce142fb168"; action.deleteMode = "Permissive"; action.sessionId = "97ddb4b10e34452c90d8591927cf3de5"; DestroyVmInstanceAction.Result res = action.call();

Python SDK

DestroyVmInstanceAction action = DestroyVmInstanceAction() action.uuid = "0de3629902f1449d86256934552d5b3d" action.deleteMode = "Permissive" action.sessionId = "931c9e7e586c4b5fa44ed1155985ac1a" DestroyVmInstanceAction.Result res = action.call()

Resource Pool