Apache CloudStack 4.19.0.0 Root Admin API Reference

deployVirtualMachine

Creates and automatically starts a virtual machine based on a service offering, disk offering, and template.

Request parameters

Parameter NameDescriptionRequired
serviceofferingidthe ID of the service offering for the virtual machinetrue
templateidthe ID of the template for the virtual machinetrue
zoneidavailability zone for the virtual machinetrue
accountan optional account for the virtual machine. Must be used with domainId.false
affinitygroupidscomma separated list of affinity groups id that are going to be applied to the virtual machine. Mutually exclusive with affinitygroupnames parameterfalse
affinitygroupnamescomma separated list of affinity groups names that are going to be applied to the virtual machine.Mutually exclusive with affinitygroupids parameterfalse
bootintosetupBoot into hardware setup or not (ignored if startVm = false, only valid for vmware)false
bootmodeBoot 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
boottypeGuest 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
clusteriddestination Cluster ID to deploy the VM to - parameter available for root admin onlyfalse
copyimagetagsif true the image tags (if any) will be copied to the VM, default value is falsefalse
customidan optional field, in case you want to set a custom id to the resource. Allowed to Root Admins onlyfalse
datadiskofferinglistdatadisk template to disk-offering mapping; an optional parameter used to create additional data disks from datadisk templates; can't be specified with diskOfferingId parameterfalse
deploymentplannerDeployment planner to use for vm allocation. Available to ROOT admin onlyfalse
detailsused to specify the custom parameters. 'extraconfig' is not allowed to be passed in detailsfalse
dhcpoptionsnetworklistDHCP 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.comfalse
diskofferingidthe 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
displaynamean optional user generated name for the virtual machinefalse
displayvman optional field, whether to the display the vm to the end user or not.false
domainidan 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
dynamicscalingenabledtrue if virtual machine needs to be dynamically scalablefalse
extraconfigan optional URL encoded string that can be passed to the virtual machine upon successful deploymentfalse
groupan optional group for the virtual machinefalse
hostiddestination Host ID to deploy the VM to - parameter available for root admin onlyfalse
hypervisorthe 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 callfalse
iodriverpolicyControls specific policies on IOfalse
iothreadsenabledIOThreads 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
ip6addressthe ipv6 address for default vm's networkfalse
ipaddressthe ip address for default vm's networkfalse
iptonetworklistip 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=uuidfalse
keyboardan optional keyboard device type for the virtual machine. valid value can be one of de,de-ch,es,fi,fr,fr-be,fr-ch,is,it,jp,nl-be,no,pt,uk,usfalse
keypairname of the ssh key pair used to login to the virtual machinefalse
keypairsnames of the ssh key pairs used to login to the virtual machinefalse
macaddressthe mac address for default vm's networkfalse
namehost name for the virtual machinefalse
networkidslist of network ids used by virtual machine. Can't be specified with ipToNetworkList parameterfalse
nicmultiqueuenumberThe number of queues for multiqueue NICs.false
nicnetworklistVMware only: used to specify network mapping of a vApp VMware template registered "as-is". Example nicnetworklist[0].ip=Nic-101&nicnetworklist[0].network=uuidfalse
nicpackedvirtqueuesenabledEnable packed virtqueues or not.false
overridediskofferingidthe 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 idfalse
passwordThe password of the virtual machine. If null, a random password will be generated for the VM.false
podiddestination Pod ID to deploy the VM to - parameter available for root admin onlyfalse
projectidDeploy vm for the projectfalse
propertiesused to specify the vApp properties.false
rootdisksizeOptional 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 providedfalse
securitygroupidscomma 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 parameterfalse
securitygroupnamescomma 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 parameterfalse
sizethe arbitrary size for the DATADISK volume. Mutually exclusive with diskOfferingIdfalse
startvmtrue if start vm after creating; defaulted to true if not specifiedfalse
userdataan 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.false
userdatadetailsused to specify the parameters values for the variables in userdata.false
userdataidthe ID of the Userdatafalse

Response Tags

Response NameDescription
idthe ID of the virtual machine
accountthe account associated with the virtual machine
autoscalevmgroupidID of AutoScale VM group
autoscalevmgroupnameName of AutoScale VM group
backupofferingidthe ID of the backup offering of the virtual machine
backupofferingnamethe name of the backup offering of the virtual machine
bootmodeGuest vm Boot Mode
boottypeGuest vm Boot Type
cpunumberthe number of vCPUs this virtual machine is using
cpuspeedthe speed of each vCPU
cpuusedthe amount of the vm's CPU currently used
createdthe date when this virtual machine was created
detailsVm details in key/value pairs.
diskioreadthe read (IO) of disk on the VM
diskiowritethe write (IO) of disk on the VM
diskkbsreadthe VM's disk read in KiB
diskkbswritethe VM's disk write in KiB
diskofferingidthe ID of the disk offering of the virtual machine. This parameter should not be used for retrieving disk offering details of DATA volumes. Use listVolumes API instead
diskofferingnamethe name of the disk offering of the virtual machine. This parameter should not be used for retrieving disk offering details of DATA volumes. Use listVolumes API instead
displaynameuser generated name. The name of the virtual machine is returned if no displayname exists.
displayvman optional field whether to the display the vm to the end user or not.
domainthe name of the domain in which the virtual machine exists
domainidthe ID of the domain in which the virtual machine exists
forvirtualnetworkthe virtual network for the service offering
groupthe group name of the virtual machine
groupidthe group ID of the virtual machine
guestosidOs type ID of the virtual machine
haenabletrue if high-availability is enabled, false otherwise
hostcontrolstatethe control state of the host for the virtual machine
hostidthe ID of the host for the virtual machine
hostnamethe name of the host for the virtual machine
hypervisorthe hypervisor on which the template runs
iconBase64 string representation of the resource icon
instancenameinstance name of the user vm; this parameter is returned to the ROOT admin only
isdynamicallyscalabletrue if vm contains XS/VMWare tools inorder to support dynamic scaling of VM cpu/memory.
isodisplaytextan alternate display text of the ISO attached to the virtual machine
isoidthe ID of the ISO attached to the virtual machine
isonamethe name of the ISO attached to the virtual machine
keypairsssh key-pairs
lastupdatedthe date when this virtual machine was updated last time
memorythe memory allocated for the virtual machine
memoryintfreekbsthe internal memory (KiB) that's free in VM or zero if it can not be calculated
memorykbsthe memory used by the VM in KiB
memorytargetkbsthe target memory in VM (KiB)
namethe name of the virtual machine
networkkbsreadthe incoming network traffic on the VM in KiB
networkkbswritethe outgoing network traffic on the host in KiB
osdisplaynameOS name of the vm
ostypeidOS type id of the vm
passwordthe password (if exists) of the virtual machine
passwordenabledtrue if the password rest feature is enabled, false otherwise
pooltypethe pool type of the virtual machine
projectthe project name of the vm
projectidthe project id of the vm
publicippublic IP address id associated with vm via Static nat rule
publicipidpublic IP address id associated with vm via Static nat rule
readonlydetailsList of read-only Vm details as comma separated string.
receivedbytesthe total number of network traffic bytes received
rootdeviceiddevice ID of the root volume
rootdevicetypedevice type of the root volume
sentbytesthe total number of network traffic bytes sent
serviceofferingidthe ID of the service offering of the virtual machine
serviceofferingnamethe name of the service offering of the virtual machine
servicestateState of the Service from LB rule
statethe state of the virtual machine
templatedisplaytext an alternate display text of the template for the virtual machine
templateidthe ID of the template for the virtual machine. A -1 is returned if the virtual machine was created from an ISO file.
templatenamethe name of the template for the virtual machine
templatetypethe type of the template for the virtual machine
userdataBase64 string containing the user data
userdatadetailslist of variables and values for the variables declared in userdata
userdataidthe id of userdata used for the VM
userdatanamethe name of userdata used for the VM
userdatapolicythe userdata override policy with the userdata provided while deploying VM
useridthe user's ID who deployed the virtual machine
usernamethe user's name who deployed the virtual machine
vgputhe vGPU type used by the virtual machine
vnfdetailsVNF details
vnfnicsNICs of the VNF appliance
zoneidthe ID of the availability zone for the virtual machine
zonenamethe name of the availability zone for the virtual machine
affinitygroup(*)list of affinity groups associated with the virtual machine
idthe ID of the affinity group
accountthe account owning the affinity group
descriptionthe description of the affinity group
domainthe domain name of the affinity group
domainidthe domain ID of the affinity group
namethe name of the affinity group
projectthe project name of the affinity group
projectidthe project ID of the affinity group
typethe type of the affinity group
virtualmachineIdsvirtual machine IDs associated with this affinity group
nic(*)the list of nics associated with vm
idthe ID of the nic
adaptertypeType of adapter if available
broadcasturithe broadcast uri of the nic
deviceiddevice id for the network when plugged into the virtual machine
extradhcpoptionthe extra dhcp options on the nic
gatewaythe gateway of the nic
ip6addressthe IPv6 address of network
ip6cidrthe cidr of IPv6 network
ip6gatewaythe gateway of IPv6 network
ipaddressthe ip address of the nic
ipaddressesIP addresses associated with NIC found for unmanaged VM
isdefaulttrue if nic is default, false otherwise
isolatedpvlanthe isolated private VLAN if available
isolatedpvlantypethe isolated private VLAN type if available
isolationurithe isolation uri of the nic
macaddresstrue if nic is default, false otherwise
mtuMTU configured on the NIC
netmaskthe netmask of the nic
networkidthe ID of the corresponding network
networknamethe name of the corresponding network
nsxlogicalswitchId of the NSX Logical Switch (if NSX based), null otherwise
nsxlogicalswitchportId of the NSX Logical Switch Port (if NSX based), null otherwise
publicippublic IP address associated with this nic via Static nat rule
publicipidpublic IP address id associated with this nic via Static nat rule
secondaryipthe Secondary ipv4 addr of nic
traffictypethe traffic type of the nic
typethe type of the nic
virtualmachineidId of the vm to which the nic belongs
vlanidID of the VLAN/VNI if available
vpcidId of the vpc to which the nic belongs
vpcnamename of the vpc to which the nic belongs
securitygroup(*)list of security groups associated with the virtual machine
idthe ID of the security group
accountthe account owning the security group
descriptionthe description of the security group
domainthe domain name of the security group
domainidthe domain ID of the security group
namethe name of the security group
projectthe project name of the group
projectidthe project id of the group
virtualmachinecountthe number of virtualmachines associated with this securitygroup
virtualmachineidsthe list of virtualmachine ids associated with this securitygroup
egressrule(*)the list of egress rules associated with the security group
accountaccount owning the security group rule
cidrthe CIDR notation for the base IP address of the security group rule
endportthe ending IP of the security group rule
icmpcodethe code for the ICMP message response
icmptypethe type of the ICMP message response
protocolthe protocol of the security group rule
ruleidthe id of the security group rule
securitygroupnamesecurity group name
startportthe 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
accountaccount owning the security group rule
cidrthe CIDR notation for the base IP address of the security group rule
endportthe ending IP of the security group rule
icmpcodethe code for the ICMP message response
icmptypethe type of the ICMP message response
protocolthe protocol of the security group rule
ruleidthe id of the security group rule
securitygroupnamesecurity group name
startportthe 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
accountthe account associated with the tag
customercustomer associated with the tag
domainthe domain associated with the tag
domainidthe ID of the domain associated with the tag
keytag key name
projectthe project name where tag belongs to
projectidthe project id the tag belongs to
resourceidid of the resource
resourcetyperesource type
valuetag value
jobidthe ID of the latest async job acting on this object
jobstatusthe current status of the latest async job acting on this object
jobidthe ID of the latest async job acting on this object
jobstatusthe current status of the latest async job acting on this object