CreateVmInstance

POST/zstack/v1/vm-instances

Operation ID

CreateVmInstance

Since

0.6

Execution Mode

Synchronous

Auth Context

Auth Required

Auth Context

Send these values as request headers when calling this API.

AuthorizationstringRequired

Bearer Token

X-Tenant-IDstring

X-Tenant-ID

Request Inputs

application/json

Body Fields

params
ObjectRequired
Request body parameter object.
- name
  StringRequired
  The VM instance name.
- instanceOfferingUuid
  StringRequired
  The instance offering UUID. Specifies the CPU, memory, and other parameters of the VM instance.
- imageUuid
  StringRequired
  The image UUID. Specifies the image from which the root volume of the VM instance is created.
- l3NetworkUuids
  ListRequired
  The L3 network UUID list. You can specify one or more L3 networks. Then the VM instance will create a NIC on each network.
- type
  String
  Optional. The VM instance type. This parameter is a reserved field for internal use.
- rootDiskOfferingUuid
  String
  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.
- dataDiskSizes
  List
  Optional. List of custom volume sizes. You can specify one or more volume sizes (repeatable) to create one or more data volumes for the VM instances.
- dataDiskOfferingUuids
  List
  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.)
- zoneUuid
  String
  Optional. The zone UUID. If specified, the VM instance will be created in the specified zone.
- clusterUuid
  String
  Optional. The cluster UUID. If specified, the VM instance will be created in the specified cluster. This parameter can override zoneUuid.
- hostUuid
  String
  Optional. The host UUID. If specified, the VM instance will be created on the specified host. This parameter can override zoneUuid and clusterUuid.
- primaryStorageUuidForRootVolume
  String
  Optional. The primary storage UUID. If specified, the root volume of the VM instance will be created on the specified primary storage.
- description
  String
  Optional. The detailed description of the VM instance.
- defaultL3NetworkUuid
  String
  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.
- resourceUuid
  String
  Optional. The resource UUID. If specified, the VM instance will use the specified value as UUID.
- tagUuids
  List
  Optional. The tag UUID list.
- strategy
  String
  Optional. The VM instance creation strategy. Start the VM instance immediately after creation. Do not start the VM instance after creation.
- dataVolumeSystemTagsOnIndex
  Map
  Optional. The required system label mapping requited for data volume index.
systemTags
List
Optional. The system tags of the VM instance.
userTags
List
Optional. The user tags of the VM instance.

Responses

200 OK

On success, this API returns the following response structure.

error
ErrorCodeRequired
The error code. If not null, the operation fails, or vice versa. For more information, see error.
- code
  StringRequired
  The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001.
- description
  StringRequired
  The brief description of the error.
- details
  StringRequired
  The details about the error.
- elaboration
  StringRequired
  The reserved field. Default value: null.
- opaque
  LinkedHashMapRequired
  The reserved field. Default value: null.
- cause
  ErrorCodeRequired
  The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null.
inventory
VmInstanceInventoryRequired
See inventory.
- uuid
  StringRequired
  The resource UUID.
- name
  StringRequired
  The resource name.
- description
  StringRequired
  The detailed description of the resource.
- zoneUuid
  StringRequired
  The zone UUID.
- clusterUuid
  StringRequired
  The cluster UUID.
- imageUuid
  StringRequired
  The image UUID.
- hostUuid
  StringRequired
  The host UUID.
- lastHostUuid
  StringRequired
  The UUID of the host on which the VM instance was running last time.
- instanceOfferingUuid
  StringRequired
  The instance offering UUID.
- rootVolumeUuid
  StringRequired
  The root volume UUID.
- platform
  StringRequired
  The platform on which the VM instance is running.
- defaultL3NetworkUuid
  StringRequired
  The UUID of the default L3 network.
- type
  StringRequired
  The VM instance type.
- hypervisorType
  StringRequired
  The hypervisor type of the VM instance.
- memorySize
  LongRequired
  The memory size.
- cpuNum
  IntegerRequired
  The CPU count.
- cpuSpeed
  LongRequired
  The CPU speed.
- allocatorStrategy
  StringRequired
  The allocator strategy.
- createDate
  TimestampRequired
  The creation date.
- lastOpDate
  TimestampRequired
  The last operation date.
- state
  StringRequired
  The state of the VM instance.
- vmNics
  ListRequired
  See vmNics.
  uuid
  StringRequired
  The resource UUID.
  vmInstanceUuid
  StringRequired
  The VM instance UUID.
  l3NetworkUuid
  StringRequired
  The L3 network UUID.
  ip
  StringRequired
  The IP address.
  mac
  StringRequired
  The MAC address.
  netmask
  StringRequired
  The netmask.
  gateway
  StringRequired
  The gateway.
  metaData
  StringRequired
  The reserved field for internal use.
  deviceId
  IntegerRequired
  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.
  createDate
  TimestampRequired
  The creation date.
  lastOpDate
  TimestampRequired
  The last operation date.
- allVolumes
  ListRequired
  See allVolumes.
  uuid
  StringRequired
  The resource UUID.
  name
  StringRequired
  The resource name.
  description
  StringRequired
  The detailed description of the resource.
  primaryStorageUuid
  StringRequired
  The primary storage UUID.
  vmInstanceUuid
  StringRequired
  The VM instance UUID.
  diskOfferingUuid
  StringRequired
  The disk offering UUID.
  rootImageUuid
  StringRequired
  The UUID of the root volume image.
  installPath
  StringRequired
  The installation path.
  type
  StringRequired
  The volume type.
  format
  StringRequired
  The volume format.
  size
  LongRequired
  The virtual size of the volume.
  actualSize
  LongRequired
  The actual size of the volume.
  deviceId
  IntegerRequired
  The device ID.
  state
  StringRequired
  The state of the volume.
  status
  StringRequired
  The status of the volume.
  createDate
  TimestampRequired
  The creation date.
  lastOpDate
  TimestampRequired
  The last operation date.
  isShareable
  BooleanRequired
  Whether the volume can be shared.

Request Example

curl -X POST '{host}/zstack/v1/vm-instances' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "name": "{name}",
    "instanceOfferingUuid": "{instanceOfferingUuid}",
    "imageUuid": "{imageUuid}",
    "l3NetworkUuids": [
      "{l3NetworkUuids}"
    ],
    "type": "{type}",
    "rootDiskOfferingUuid": "{rootDiskOfferingUuid}",
    "dataDiskSizes": [
      "{dataDiskSizes}"
    ],
    "dataDiskOfferingUuids": [
      "{dataDiskOfferingUuids}"
    ],
    "zoneUuid": "{zoneUuid}",
    "clusterUuid": "{clusterUuid}",
    "hostUuid": "{hostUuid}",
    "primaryStorageUuidForRootVolume": "{primaryStorageUuidForRootVolume}",
    "description": "{description}",
    "defaultL3NetworkUuid": "{defaultL3NetworkUuid}",
    "resourceUuid": "{resourceUuid}",
    "tagUuids": [
      "{tagUuids}"
    ],
    "strategy": "{strategy}",
    "dataVolumeSystemTagsOnIndex": {}
  },
  "systemTags": [
    "{systemTags}"
  ],
  "userTags": [
    "{userTags}"
  ]
}'

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 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,
        "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": 107374182400,
        "actualSize": 21474836480,
        "deviceId": 0,
        "state": "Enabled",
        "status": "Ready",
        "createDate": "Nov 14, 2017 10:20:57 PM",
        "lastOpDate": "Nov 14, 2017 10:20:57 PM"
      }
    ]
  }
}

VM Instance Operations

Volume Operations

Image Operations

Affinity Group Operations

VM Scheduling Rule Group Operations

Instance Offering Operations

Disk Offering Operations

Auto-Scaling Group Operations

Snapshot Group Operations

SSH Key Operations

Zone Operations

Cluster Operations

Host Operations

GPU Device Operations

Primary Storage Operations

Backup Storage Operations

SAN Storage Operations

Physical Network Operations

PCI Device Operations

USB Redirection Operations

USB Pass-through Operations

SR-IOV Operations

Loongarch SE Operations

Hygon SE Operations

Local Storage Operations

NFS Primary Storage Operations

Shared Mount Point Primary Storage Operations

Ceph Primary Storage Operations

Shared Block Primary Storage Operations

XStor Block Primary Storage Operations

ImageStore Backup Storage Operations

Ceph Backup Storage Operations

iSCSI Server Operations

FC Storage Operations

NVMe Storage Operations

Hardware SDN Controller Operations

L2 Network Operations

L3 Network Operations

Route Resource Operations

VPC Operations

OSPF Operations

Multicast Routing Operations

Policy Routing Operations

vRouter Route Table Operations

Network Service Operations

VPC Firewall Operations

Security Group Operations

VIP Operations

EIP Operations

Port Forwarding Operations

Load Balancing Operations

IPsec Operations

NetFlow APIs

Port Mirroring APIs

Shared Bandwidth Operations

Network Security Policy Schedule Operations

CloudFormation Operations

Bare Metal Management Operations

Installation Service Operations

Elastic Bare Metal Management(Plus)

vCenter Operations

Capacity Management Operations

SNS Operations

Metric Operations

Event Operations

Alarm Operations

Event Subscription Operations

Text Template Operations

Audit Operations

CBT Operations

Backup Service Operations

CDP Operations

Script Library

XML Hook

Job Scheduling APIs

Tag Operations

Migration Service Operations

Organization Operations

Project Operations

Ticket Operations