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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, 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 Cloud, you can enable SR-IOV by adding the enableSRIOV option to SystemTags.
    • Format of the enableSRIOV option: enableSRIOV::{L3_NETWORK_UUID}
    • Example: enableSRIOV::9e19dafe81c64fed8e34f72e27582339
  • When you create a VM instance in ZStack Cloud, you can use the systemTags parameter to specify whether the VM instance uses the virtio driver. You can set the value of the systemTags parameter to driver.
    • Format driver::virtio.
    • Example: driver::virtio.

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": "/Cloud_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()