Apache CloudStack 4.23.0.0 Root Admin API Reference
deployVirtualMachine
Creates and automatically starts an Instance based on a service offering, disk offering, and Template.
Request parameters
| Parameter Name | Description | Required |
| serviceofferingid | The ID of the Service offering for the Instance | true |
| zoneid | availability zone for the virtual machine | true |
| account | an optional account for the virtual machine. Must be used with domainId. | false |
| affinitygroupids | comma separated list of affinity groups id that are going to be applied to the virtual machine. Mutually exclusive with affinitygroupnames parameter | false |
| affinitygroupnames | comma separated list of affinity groups names that are going to be applied to the virtual machine.Mutually exclusive with affinitygroupids parameter | false |
| blankinstance | Whether to create a blank instance without storage and network | false |
| bootintosetup | Boot into hardware setup or not (ignored if startVm = false, only valid for vmware) | false |
| bootmode | Boot Mode [Legacy] or [Secure] Applicable when Boot Type Selected is UEFI, otherwise Legacy only for BIOS. Not applicable with VMware if the template is marked as deploy-as-is, as we honour what is defined in the template. | false |
| boottype | Guest VM Boot option either custom[UEFI] or default boot [BIOS]. Not applicable with VMware if the template is marked as deploy-as-is, as we honour what is defined in the template. | false |
| clusterid | Destination Cluster ID to deploy the Instance to - parameter available for root admin only | false |
| copyimagetags | if true the image tags (if any) will be copied to the VM, default value is false | false |
| customid | An optional field, in case you want to set a custom id to the resource. Allowed to Root Admins only | false |
| datadiskofferinglist | datadisk template to disk-offering mapping; an optional parameter used to create additional data disks from datadisk templates; can't be specified with diskOfferingId parameter | false |
| datadisksdetails | Disk offering details for creating multiple data volumes. Mutually exclusive with diskOfferingId. Example: datadisksdetails[0].diskofferingid=a2a73a84-19db-4852-8930-dfddef053341&datadisksdetails[0].size=10&datadisksdetails[0].miniops=100&datadisksdetails[0].maxiops=200&datadisksdetails[0].kmskeyid=<uuid> | false |
| deploymentplanner | Deployment planner to use for vm allocation. Available to ROOT admin only | false |
| details | used to specify the custom parameters. 'extraconfig' is not allowed to be passed in details | false |
| dhcpoptionsnetworklist | DHCP options which are passed to the VM on start up Example: dhcpoptionsnetworklist[0].dhcp:114=url&dhcpoptionsetworklist[0].networkid=networkid&dhcpoptionsetworklist[0].dhcp:66=www.test.com | false |
| diskofferingid | the ID of the disk offering for the virtual machine. If the template is of ISO format, the diskOfferingId is for the root disk volume. Otherwise this parameter is used to indicate the offering for the data disk volume. If the templateId parameter passed is from a Template object, the diskOfferingId refers to a DATA Disk Volume created. If the templateId parameter passed is from an ISO object, the diskOfferingId refers to a ROOT Disk Volume created. | false |
| displayname | an optional user generated name for the virtual machine | false |
| displayvm | an optional field, whether to the display the vm to the end user or not. | false |
| domainid | an optional domainId for the virtual machine. If the account parameter is used, domainId must also be used. If account is NOT provided then virtual machine will be assigned to the caller account and domain. | false |
| dynamicscalingenabled | true if virtual machine needs to be dynamically scalable | false |
| externaldetails | Details in key/value pairs using format externaldetails[i].keyname=keyvalue. Example: externaldetails[0].server.type=typevalue | false |
| extraconfig | an optional URL encoded string that can be passed to the virtual machine upon successful deployment | false |
| group | an optional group for the virtual machine | false |
| hostid | destination Host ID to deploy the VM to - parameter available for root admin only | false |
| hypervisor | the hypervisor on which to deploy the virtual machine. The parameter is required and respected only when hypervisor info is not set on the ISO/Template passed to the call | false |
| iodriverpolicy | Controls specific policies on IO | false |
| iothreadsenabled | IOThreads are dedicated event loop threads for supported disk devices to perform block I/O requests in order to improve scalability especially on an SMP host/guest with many LUNs. | false |
| ip6address | the ipv6 address for default vm's network | false |
| ipaddress | the ip address for default vm's network | false |
| iptonetworklist | ip to network mapping. Can't be specified with networkIds parameter. Example: iptonetworklist[0].ip=10.10.10.11&iptonetworklist[0].ipv6=fc00:1234:5678::abcd&iptonetworklist[0].networkid=uuid&iptonetworklist[0].mac=aa:bb:cc:dd:ee::ff - requests to use ip 10.10.10.11 in network id=uuid | false |
| keyboard | an optional keyboard device type for the virtual machine. valid value can be one of de,de-ch,es,es-latam,fi,fr,fr-be,fr-ch,is,it,jp,nl-be,no,pt,uk,us | false |
| keypair | name of the ssh key pair used to login to the virtual machine | false |
| keypairs | names of the ssh key pairs used to login to the virtual machine | false |
| leaseduration | Number of days instance is leased for. | false |
| leaseexpiryaction | Lease expiry action, valid values are STOP and DESTROY | false |
| macaddress | the mac address for default vm's network | false |
| name | host name for the virtual machine | false |
| networkids | list of network ids used by virtual machine. Can't be specified with ipToNetworkList parameter | false |
| nicmultiqueuenumber | The number of queues for multiqueue NICs. | false |
| nicnetworklist | VMware only: used to specify network mapping of a vApp VMware template registered "as-is". Example nicnetworklist[0].ip=Nic-101&nicnetworklist[0].network=uuid | false |
| nicpackedvirtqueuesenabled | Enable packed virtqueues or not. | false |
| overridediskofferingid | the ID of the disk offering for the virtual machine to be used for root volume instead of the disk offering mapped in service offering.In case of virtual machine deploying from ISO, then the diskofferingid specified for root volume is ignored and uses this override disk offering id | false |
| password | The password of the virtual machine. If null, a random password will be generated for the VM. | false |
| podid | Destination Pod ID to deploy the Instance to - parameter available for root admin only | false |
| projectid | Deploy vm for the project | false |
| properties | used to specify the vApp properties. | false |
| rootdiskkmskeyid | ID of the KMS Key to use for root disk encryption | false |
| rootdisksize | Optional field to resize root disk on deploy. Value is in GB. Only applies to template-based deployments. Analogous to details[0].rootdisksize, which takes precedence over this parameter if both are provided | false |
| securitygroupids | comma separated list of security groups id that going to be applied to the virtual machine. Should be passed only when vm is created from a zone with Basic Network support. Mutually exclusive with securitygroupnames parameter | false |
| securitygroupnames | comma separated list of security groups names that going to be applied to the virtual machine. Should be passed only when vm is created from a zone with Basic Network support. Mutually exclusive with securitygroupids parameter | false |
| size | the arbitrary size for the DATADISK volume. Mutually exclusive with diskOfferingId | false |
| snapshotid | false | |
| startvm | true if start vm after creating; defaulted to true if not specified | false |
| templateid | The ID of the Template for the Instance | false |
| userdata | an optional binary data that can be sent to the virtual machine upon a successful deployment. This binary data must be base64 encoded before adding it to the request. Using HTTP GET (via querystring), you can send up to 4KB of data after base64 encoding. Using HTTP POST (via POST body), you can send up to 1MB of data after base64 encoding. You also need to change vm.userdata.max.length value | false |
| userdatadetails | used to specify the parameters values for the variables in userdata. | false |
| userdataid | the ID of the Userdata | false |
| volumeid | false |
Response Tags
| Response Name | Description |
| id | The ID of the Instance |
| account | The Account associated with the Instance |
| alloweddetails | List of allowed Vm details as comma separated string if VM instance settings are read from OVA. |
| arch | CPU arch of the VM |
| autoscalevmgroupid | ID of AutoScale Instance group |
| autoscalevmgroupname | Name of AutoScale Instance group |
| backupofferingid | The ID of the backup offering of the Instance |
| backupofferingname | The name of the backup offering of the Instance |
| backupprovider | The name of the backup provider of the offering attached to the Instance |
| bootmode | Guest Instance Boot Mode |
| boottype | Guest Instance Boot Type |
| cpunumber | The number of vCPUs this Instance is using |
| cpuspeed | The speed of each vCPU |
| cpuused | The amount of the Instance's CPU currently used |
| created | The date when this Instance was created |
| deleteprotection | true if vm has delete protection. |
| details | Instance details in key/value pairs. |
| diskioread | The read (IO) of disk on the Instance |
| diskiowrite | The write (IO) of disk on the Instance |
| diskkbsread | The Instance's disk read in KiB |
| diskkbswrite | The Instance's disk write in KiB |
| diskofferingid | The ID of the disk offering of the Instance. This parameter should not be used for retrieving disk offering details of DATA volumes. Use listVolumes API instead |
| diskofferingname | The name of the disk offering of the Instance. This parameter should not be used for retrieving disk offering details of DATA volumes. Use listVolumes API instead |
| displayname | User generated name. The name of the Instance is returned if no displayname exists. |
| displayvm | An optional field whether to the display the Instance to the end user or not. |
| domain | The name of the domain in which the Instance exists |
| domainid | The ID of the domain in which the Instance exists |
| domainpath | Path of the domain in which the virtual machine exists |
| forvirtualnetwork | The virtual Network for the service offering |
| gpucardid | the ID of the gpu card to which service offering is linked |
| gpucardname | the name of the gpu card to which service offering is linked |
| gpucount | the count of GPUs on the virtual machine |
| group | The group name of the Instance |
| groupid | The group ID of the Instance |
| guestosid | OS type ID of the Instance |
| haenable | True if high-availability is enabled, false otherwise |
| hostcontrolstate | The control state of the host for the Instance |
| hostid | The ID of the host for the Instance |
| hostname | The name of the host for the Instance |
| hypervisor | The hypervisor on which the Template runs |
| icon | Base64 string representation of the resource icon |
| instancename | Instance name of the user Instance; this parameter is returned to the ROOT admin only |
| ipaddress | the VM's primary IP address |
| isdynamicallyscalable | True if Instance contains XS/VMWare tools in order to support dynamic scaling of Instance CPU/memory. |
| isodisplaytext | An alternate display text of the ISO attached to the Instance |
| isoid | The ID of the ISO attached to the Instance |
| isomaxcount | Maximum number of ISOs that may be attached to this Instance, after applying the cluster-scoped vm.iso.max.count and the hypervisor's own cap. |
| isoname | The name of the ISO attached to the Instance |
| keypairs | SSH key-pairs |
| lastupdated | The date when this Instance was updated last time |
| leaseduration | Instance lease duration in days |
| leaseexpiryaction | Instance lease expiry action |
| leaseexpirydate | Instance lease expiry date |
| maxheads | the maximum number of display heads |
| maxresolutionx | the maximum X resolution |
| maxresolutiony | the maximum Y resolution |
| memory | The memory allocated for the Instance |
| memoryintfreekbs | The internal memory (KiB) that's free in Instance or zero if it can not be calculated |
| memorykbs | The memory used by the Instance in KiB |
| memorytargetkbs | The target memory in Instance (KiB) |
| name | The name of the Instance |
| networkkbsread | The incoming Network traffic on the Instance in KiB |
| networkkbswrite | The outgoing Network traffic on the host in KiB |
| osdisplayname | OS name of the Instance |
| ostypeid | OS type id of the Instance |
| password | The password (if exists) of the Instance |
| passwordenabled | True if the password rest feature is enabled, false otherwise |
| pooltype | The pool type of the Instance |
| project | The project name of the Instance |
| projectid | The project ID of the Instance |
| publicip | Public IP address id associated with Instance via Static NAT rule |
| publicipid | Public IP address id associated with Instance via Static NAT rule |
| readonlydetails | List of read-only Instance details as comma separated string. |
| receivedbytes | The total number of Network traffic bytes received |
| rootdeviceid | Device ID of the root volume |
| rootdevicetype | Device type of the root volume |
| sentbytes | The total number of Network traffic bytes sent |
| serviceofferingid | The ID of the service offering of the Instance |
| serviceofferingname | The name of the service offering of the Instance |
| servicestate | State of the Service from LB rule |
| state | The state of the Instance |
| templatedisplaytext | An alternate display text of the Template for the Instance |
| templateformat | The format of the template for the virtual machine |
| templateid | The ID of the Template for the Instance. A -1 is returned if the Instance was created from an ISO file. |
| templatename | The name of the Template for the Instance |
| templatetype | The type of the template for the virtual machine |
| userdata | Base64 string containing the user data |
| userdatadetails | List of variables and values for the variables declared in userdata |
| userdataid | The ID of userdata used for the Instance |
| userdataname | The name of userdata used for the Instance |
| userdatapolicy | The userdata override policy with the userdata provided while deploying Instance |
| userid | The User's ID who deployed the Instance |
| username | The User's name who deployed the Instance |
| vgpu | The vGPU type used by the Instance |
| vgpuprofileid | the ID of the vgpu profile to which service offering is linked |
| vgpuprofilename | the name of the vgpu profile to which service offering is linked |
| videoram | the video RAM size in MB |
| vmtype | User VM type |
| vnfdetails | VNF details |
| vnfnics | NICs of the VNF appliance |
| zoneid | The ID of the availability zone for the Instance |
| zonename | The name of the availability zone for the Instance |
| affinitygroup(*) | List of Affinity groups associated with the Instance |
| id | The ID of the affinity group |
| account | The account owning the affinity group |
| dedicatedresources | dedicated resources associated with this affinity group |
| description | The description of the affinity group |
| domain | The domain name of the affinity group |
| domainid | The domain ID of the affinity group |
| domainpath | path of the Domain the affinity group belongs to |
| name | The name of the affinity group |
| project | The project name of the affinity group |
| projectid | The project ID of the affinity group |
| type | The type of the affinity group |
| virtualmachineIds | Instance IDs associated with this affinity group |
| isos(*) | All ISOs attached to the Instance, keyed by cdrom slot. The first entry mirrors isoid/isoname for back-compat. |
| id | The ID of the attached ISO |
| bootable | Whether this is the bootable ISO for the VM |
| deviceseq | The cdrom slot that holds this ISO (3=hdc, 4=hdd, ...) |
| displaytext | The display text of the attached ISO |
| name | The name of the attached ISO |
| nic(*) | The list of NICs associated with Instance |
| id | The ID of the NIC |
| adaptertype | Type of adapter if available |
| broadcasturi | The broadcast URI of the NIC |
| deviceid | Device ID for the Network when plugged into the Instance |
| enabled | whether the NIC is enabled or not |
| extradhcpoption | The extra DHCP options on the NIC |
| gateway | The gateway of the NIC |
| ip6address | The IPv6 address of Network |
| ip6cidr | The CIDR of IPv6 Network |
| ip6gateway | The gateway of IPv6 Network |
| ipaddress | The IP address of the NIC |
| ipaddresses | IP addresses associated with NIC found for unmanaged Instance |
| isdefault | True if NIC is default, false otherwise |
| isolatedpvlan | The isolated private VLAN if available |
| isolatedpvlantype | The isolated private VLAN type if available |
| isolationuri | The isolation URI of the NIC |
| macaddress | True if NIC is default, false otherwise |
| mtu | MTU configured on the NIC |
| netmask | The netmask of the NIC |
| networkid | The ID of the corresponding Network |
| networkname | The name of the corresponding Network |
| nicdnsname | DNS name associated with this NIC's IP address |
| nsxlogicalswitch | Id of the NSX Logical Switch (if NSX based), null otherwise |
| nsxlogicalswitchport | Id of the NSX Logical Switch Port (if NSX based), null otherwise |
| publicip | Public IP address associated with this NIC via Static NAT rule |
| publicipid | Public IP address ID associated with this NIC via Static NAT rule |
| secondaryip | The Secondary IPv4 addr of NIC |
| traffictype | The traffic type of the NIC |
| type | The type of the NIC |
| virtualmachineid | Id of the Instance to which the NIC belongs |
| vlanid | ID of the VLAN/VNI if available |
| vpcid | ID of the VPC to which the NIC belongs |
| vpcname | Name of the VPC to which the NIC belongs |
| securitygroup(*) | List of security groups associated with the Instance |
| id | The ID of the security group |
| account | The Account owning the security group |
| description | The description of the security group |
| domain | The domain name of the security group |
| domainid | The domain ID of the security group |
| domainpath | path of the Domain the security group belongs to |
| name | The name of the security group |
| project | The project name of the group |
| projectid | The project id of the group |
| virtualmachinecount | The number of Instances associated with this Security Group |
| virtualmachineids | The list of Instance IDs associated with this Security Group |
| egressrule(*) | The list of egress rules associated with the security group |
| account | Account owning the security group rule |
| cidr | The CIDR notation for the base IP address of the security group rule |
| endport | The ending IP of the security group rule |
| icmpcode | The code for the ICMP message response |
| icmptype | The type of the ICMP message response |
| protocol | The protocol of the security group rule |
| ruleid | The ID of the security group rule |
| securitygroupname | Security group name |
| startport | The starting IP of the security group rule |
| tags(*) | The list of resource tags associated with the rule |
| ingressrule(*) | The list of ingress rules associated with the security group |
| account | Account owning the security group rule |
| cidr | The CIDR notation for the base IP address of the security group rule |
| endport | The ending IP of the security group rule |
| icmpcode | The code for the ICMP message response |
| icmptype | The type of the ICMP message response |
| protocol | The protocol of the security group rule |
| ruleid | The ID of the security group rule |
| securitygroupname | Security group name |
| startport | The starting IP of the security group rule |
| tags(*) | The list of resource tags associated with the rule |
| tags(*) | The list of resource tags associated with the rule |
| account | The Account associated with the tag |
| customer | Customer associated with the tag |
| domain | The domain associated with the tag |
| domainid | The ID of the domain associated with the tag |
| domainpath | Path of the Domain associated with the tag |
| key | Tag key name |
| project | The project name where tag belongs to |
| projectid | The project ID the tag belongs to |
| resourceid | ID of the resource |
| resourcetype | Resource type |
| value | Tag value |
| jobid | the ID of the latest async job acting on this object |
| jobstatus | the current status of the latest async job acting on this object |
| jobid | the ID of the latest async job acting on this object |
| jobstatus | the current status of the latest async job acting on this object |