Create VM

POST/zstack/v1/vm-instances

Request

cURL

curl --request POST \
  --url '/v1/vm-instances' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "status": "ok",
  "method": "POST",
  "path": "/v1/vm-instances"
}

Create a new Virtual Machine.

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "name": "vm1",
    "l3NetworkUuids": [
      "19d22d051b063d379a2816daaf431838"
    ],
    "clusterUuid": "a0468dc645223f67bd0f2ab95276bbae",
    "description": "this is a vm",
    "strategy": "InstantStart",
    "diskAOs": [
      {
        "boot": true,
        "platform": "Linux",
        "guestOsType": "Helix 8",
        "architecture": "x86_64",
        "primaryStorageUuid": "ff0359abb8443d2f8077cc368afa7c00",
        "size": 0,
        "sourceType": "VolumeVO",
        "sourceUuid": "ff0eb5a723e9316bb1053ed7e4bb3100",
        "systemTags": [
          "volumeProvisioningStrategy::ThickProvisioning"
        ],
        "name": "root-volume"
      },
      {
        "boot": false,
        "primaryStorageUuid": "ff0359abb8443d2f8077cc368afa7c00",
        "size": 0,
        "name": "data-volume"
      }
    ],
    "devices": {
      "tpm": {
        "enable": true,
        "keyProviderUuid": "ff03c7091617357eb4022d11c6860e00",
        "resourceKeyCreatedNew": false
      }
    }
  },
  "systemTags": [],
  "userTags": []
}

In the example above, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X POST -d '{"params":{"name":"vm1","l3NetworkUuids":["19d22d051b063d379a2816daaf431838"],"clusterUuid":"a0468dc645223f67bd0f2ab95276bbae","description":"this is a vm","strategy":"InstantStart","diskAOs":[{"boot":true,"platform":"Linux","guestOsType":"Helix 8","architecture":"x86_64","primaryStorageUuid":"ff0359abb8443d2f8077cc368afa7c00","size":0,"sourceType":"VolumeVO","sourceUuid":"ff0eb5a723e9316bb1053ed7e4bb3100","systemTags":["volumeProvisioningStrategy::ThickProvisioning"],"name":"root-volume"},{"boot":false,"primaryStorageUuid":"ff0359abb8443d2f8077cc368afa7c00","size":0,"name":"data-volume"}],"devices":{"tpm":{"enable":true,"keyProviderUuid":"ff03c7091617357eb4022d11c6860e00","resourceKeyCreatedNew":false}}}}'
http://localhost:8080/zstack/v1/vm-instances

Parameter List

Name	Type	Location	Description	Allowed Values	Starting Version
name	String	body (included in params structure)	Virtual Machine name		0.6
instanceOfferingUuid (Optional)	String	body (included in params structure)	Compute offering UUID- Specifies the CPU, memory, and other parameters of the Virtual Machine.		0.6
imageUuid (Optional)	String	body (included in params structure)	Image UUID- The root disk of the Virtual Machine is created from the Image specified by this field.		0.6
l3NetworkUuids (Optional)	List	body (included in params structure)	Distributed Port Group UUID list- Specifies one or more Distributed Port Groups. The Virtual Machine creates a NIC on each Distributed Port Group.		0.6
vmNicParams (Optional)	String	body (included in params structure)	NIC information		4.7.0
type (Optional)	String	body (included in params structure)	Virtual Machine type- Reserved field, no need to specify.	UserVm ApplianceVm	0.6
rootDiskOfferingUuid (Optional)	String	body (included in params structure)	Root disk offering UUID- If the Image type specified by the imageUuid field is ISO, this field must be specified to determine the root disk size to be created. If the Image type is non-ISO, this field does not need to be specified.		0.6
dataDiskSizes (Optional)	List	body (included in params structure)	Custom disk size list. Specifies one or more disk sizes (can be repeated) to create one or more Data Disks for the Virtual Machine.		4.4.6
dataDiskOfferingUuids (Optional)	List	body (included in params structure)	Disk offering UUID list- Specifies one or more disk offering UUIDs (UUID can be repeated) to create one or more Data Disks for the Virtual Machine.		0.6
zoneUuid (Optional)	String	body (included in params structure)	Data Center UUID- If specified, the Virtual Machine is created in the specified Data Center.		0.6
clusterUuid (Optional)	String	body (included in params structure)	Cluster UUID- If specified, the Virtual Machine is created in the specified Cluster. This field has higher priority than zoneUuid.		0.6
hostUuid (Optional)	String	body (included in params structure)	Host UUID- If specified, the Virtual Machine is created on the specified Host. This field has higher priority than zoneUuid and clusterUuid.		0.6
primaryStorageUuidForRootVolume (Optional)	String	body (included in params structure)	Data Storage UUID- If specified, the root disk of the Virtual Machine is created in the specified Data Storage.		1.8
description (Optional)	String	body (included in params structure)	Virtual Machine description		0.6
defaultL3NetworkUuid (Optional)	String	body (included in params structure)	Default Distributed Port Group UUID- When l3NetworkUuids specifies multiple Distributed Port Groups, this field specifies the Distributed Port Group that provides the default route. If not specified, the first network in `l3NetworkUuids` is selected as the default network.		0.6
resourceUuid (Optional)	String	body (included in params structure)	Resource UUID- If specified, the Virtual Machine uses this value as its UUID.		0.6
tagUuids (Optional)	List	body (included in params structure)	Tag UUID list		3.4.0
systemTags (Optional)	List	body	Virtual Machine system tags		0.6
userTags (Optional)	List	body	Virtual Machine user tags		0.6
strategy (Optional)	String	body (included in params structure)	Virtual Machine creation policy- Start immediately after creation Do not start after creation	InstantStart JustCreate CreateStopped	0.6
rootVolumeSystemTags (Optional)	List	body (included in params structure)	System tags required for the Virtual Machine root disk		3.0
dataVolumeSystemTags (Optional)	List	body (included in params structure)	System tags required for the Virtual Machine data disk		3.0
cpuNum (Optional)	Integer	body (included in params structure)			3.4.0
memorySize (Optional)	Long	body (included in params structure)			3.4.0
rootDiskSize (Optional)	Long	body (included in params structure)			3.4.0
dataVolumeSystemTagsOnIndex (Optional)	Map	body (included in params structure)			4.4.24
sshKeyPairUuids (Optional)	List	body (included in params structure)			4.7.21
dataVolumeTemplateUuids (Optional)	List	body (included in params structure)			4.7.0
diskAOs (Optional)	List	body (included in params structure)	boot=true indicates diskAO is used to set the Virtual Machine platform, architecture, operating system and root disk bus; diskAO.boot=false indicates loaded disk		4.7.0
platform	String	body (included in params structure)			4.7.0
guestOsType	String	body (included in params structure)			4.7.0
architecture	String	body (included in params structure)			4.7.21
reservedMemorySize (Optional)	Long	body (included in params structure)			4.7.21
virtio (Optional)	Boolean	body (included in params structure)			4.7.0

API Response

Response Example

{
  "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": 8589934592,
    "cpuNum": 1,
    "allocatorStrategy": "LastHostPreferredAllocatorStrategy",
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2: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",
        "hypervisorType": "KVM",
        "netmask": "255.255.255.0",
        "gateway": "192.168.1.1",
        "deviceId": 0,
        "createDate": "Nov 14, 2017 2:20:57 PM",
        "lastOpDate": "Nov 14, 2017 2: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": 107374182400,
        "actualSize": 21474836480,
        "deviceId": 0,
        "state": "Enabled",
        "status": "Ready",
        "createDate": "Nov 14, 2017 2:20:57 PM",
        "lastOpDate": "Nov 14, 2017 2:20:57 PM"
      }
    ]
  }
}

Name	Type	Description	Starting Version
success	boolean		0.6
error	ErrorCode	Error code. If not null, the operation failed. If null, the operation succeeded. See error	0.6
inventory	VmInstanceInventory	See inventory for details.	0.6

error

Name	Type	Description	Starting Version
code	String	Error code number, globally unique identifier for the error, for example SYS.1000, HOST.1001	0.6
description	String	Brief description of the error	0.6
details	String	Detailed error information	0.6
elaboration	String	Reserved field, defaults to null	0.6
opaque	LinkedHashMap	Reserved field, defaults to null	0.6
cause	ErrorCode	Root error. The error that caused this error. If there is no original error, this field is null	0.6

inventory

Name	Type	Description	Starting Version
uuid	String	Resource UUID. Uniquely identifies the resource	0.6
name	String	Resource name	0.6
description	String	Resource description	0.6
zoneUuid	String	Data Center UUID	0.6
clusterUuid	String	Cluster UUID	0.6
imageUuid	String	Image UUID	0.6
hostUuid	String	Host UUID	0.6
lastHostUuid	String	Host UUID where the Virtual Machine last ran	0.6
instanceOfferingUuid	String	Compute offering UUID	0.6
rootVolumeUuid	String	Root disk UUID	0.6
platform	String	Virtual Machine running platform	0.6
architecture	String		0.6
defaultL3NetworkUuid	String	Default Distributed Port Group UUID	0.6
type	String	Virtual Machine type	0.6
hypervisorType	String	Hypervisor type of the Virtual Machine	0.6
memorySize	Long	Memory size	0.6
cpuNum	Integer	CPU number	0.6
cpuSpeed	Long	CPU speed	0.6
allocatorStrategy	String	Allocation strategy	0.6
createDate	Timestamp	Create time	0.6
lastOpDate	Timestamp	Last modification time	0.6
state	String	Virtual Machine availability state	0.6
guestOsType	String		4.1.2
vmNics	List	See vmNics for details.	0.6
allVolumes	List	See allVolumes for details.	0.6
vmCdRoms	List	See vmCdRoms for details.	0.6

vmNics

Name	Type	Description	Starting Version
uuid	String	Resource UUID. Uniquely identifies the resource	4.7.13
vmInstanceUuid	String	Virtual Machine UUID	4.7.13
l3NetworkUuid	String	Distributed Port Group UUID	4.7.13
ip	String		4.7.13
mac	String		4.7.13
hypervisorType	String		4.7.13
netmask	String		4.7.13
gateway	String		4.7.13
metaData	String		4.7.13
ipVersion	Integer		4.7.13
driverType	String		4.7.13
internalName	String		4.7.13
deviceId	Integer		4.7.13
type	String		4.7.13
state	String	NIC status	4.7.13
createDate	Timestamp	Create time	4.7.13
lastOpDate	Timestamp	Last modification time	4.7.13
usedIps	List	See usedIps for details.	4.7.13

usedIps

Name	Type	Description	Starting Version
uuid	String	Resource UUID. Uniquely identifies the resource	4.7.13
ipRangeUuid	String	IP range UUID	4.7.13
l3NetworkUuid	String	Distributed Port Group UUID	4.7.13
ipVersion	Integer		4.7.13
ip	String		4.7.13
netmask	String		4.7.13
gateway	String		4.7.13
usedFor	String		4.7.13
ipInLong	long		4.7.13
vmNicUuid	String	Virtual Machine NIC UUID	4.7.13
createDate	Timestamp	Create time	4.7.13
lastOpDate	Timestamp	Last modification time	4.7.13

allVolumes

Name	Type	Description	Starting Version
uuid	String	Resource UUID. Uniquely identifies the resource	4.7.13
name	String	Resource name	4.7.13
description	String	Resource description	4.7.13
primaryStorageUuid	String	Data Storage UUID	4.7.13
vmInstanceUuid	String	Virtual Machine UUID	4.7.13
diskOfferingUuid	String	Disk offering UUID	4.7.13
rootImageUuid	String		4.7.13
installPath	String		4.7.13
type	String		4.7.13
format	String		4.7.13
size	Long		4.7.13
actualSize	Long		4.7.13
deviceId	Integer		4.7.13
state	String		4.7.13
status	String		4.7.13
createDate	Timestamp	Create time	4.7.13
lastOpDate	Timestamp	Last modification time	4.7.13
isShareable	Boolean		4.7.13
volumeQos	String		4.7.13
lastDetachDate	Timestamp		4.7.13
lastVmInstanceUuid	String		4.7.13

vmCdRoms

Name	Type	Description	Starting Version
uuid	String	Resource UUID. Uniquely identifies the resource	4.7.13
vmInstanceUuid	String	Virtual Machine UUID	4.7.13
deviceId	Integer		4.7.13
isoUuid	String		4.7.13
isoInstallPath	String		4.7.13
name	String	Resource name	4.7.13
description	String	Resource description	4.7.13
createDate	Timestamp	Create time	4.7.13
lastOpDate	Timestamp	Last modification time	4.7.13

SDK Examples

Java SDK

CreateVmInstanceAction action = new CreateVmInstanceAction();
action.name = "vm1";
action.l3NetworkUuids = asList("19d22d051b063d379a2816daaf431838");
action.clusterUuid = "a0468dc645223f67bd0f2ab95276bbae";
action.description = "this is a vm";
action.strategy = "InstantStart";
action.diskAOs = asList([boot:true, platform:Linux, guestOsType:Helix 8, architecture:x86_64, primaryStorageUuid:ff0359abb8443d2f8077cc368afa7c00, size:0, sourceType:VolumeVO, sourceUuid:ff0eb5a723e9316bb1053ed7e4bb3100, systemTags:[volumeProvisioningStrategy::ThickProvisioning], name:root-volume],[boot:false, primaryStorageUuid:ff0359abb8443d2f8077cc368afa7c00, size:0, name:data-volume]);
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateVmInstanceAction.Result res = action.call();

Python SDK

action = CreateVmInstanceAction()
action.name = "vm1"
action.l3NetworkUuids = [19d22d051b063d379a2816daaf431838]
action.clusterUuid = "a0468dc645223f67bd0f2ab95276bbae"
action.description = "this is a vm"
action.strategy = "InstantStart"
action.diskAOs = [[boot:true, platform:Linux, guestOsType:Helix 8, architecture:x86_64, primaryStorageUuid:ff0359abb8443d2f8077cc368afa7c00, size:0, sourceType:VolumeVO, sourceUuid:ff0eb5a723e9316bb1053ed7e4bb3100, systemTags:[volumeProvisioningStrategy::ThickProvisioning], name:root-volume], [boot:false, primaryStorageUuid:ff0359abb8443d2f8077cc368afa7c00, size:0, name:data-volume]]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()