Apache CloudStack 4.20.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 Name | Description | Required |
| serviceofferingid | the ID of the service offering for the virtual machine | true |
| templateid | the ID of the template for the virtual machine | 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 |
| 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 VM 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 |
| 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 |
| 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,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 |
| 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 VM to - parameter available for root admin only | false |
| projectid | Deploy vm for the project | false |
| properties | used to specify the vApp properties. | 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 |
| startvm | true if start vm after creating; defaulted to true if not specified | 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 |
Response Tags
| Response Name | Description |
| id | the ID of the virtual machine |
| account | the account associated with the virtual machine |
| autoscalevmgroupid | ID of AutoScale VM group |
| autoscalevmgroupname | Name of AutoScale VM group |
| backupofferingid | the ID of the backup offering of the virtual machine |
| backupofferingname | the name of the backup offering of the virtual machine |
| bootmode | Guest vm Boot Mode |
| boottype | Guest vm Boot Type |
| cpunumber | the number of vCPUs this virtual machine is using |
| cpuspeed | the speed of each vCPU |
| cpuused | the amount of the vm's CPU currently used |
| created | the date when this virtual machine was created |
| deleteprotection | true if vm has delete protection. |
| details | Vm details in key/value pairs. |
| diskioread | the read (IO) of disk on the VM |
| diskiowrite | the write (IO) of disk on the VM |
| diskkbsread | the VM's disk read in KiB |
| diskkbswrite | the VM's disk write in KiB |
| diskofferingid | the 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 |
| diskofferingname | the 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 |
| displayname | user generated name. The name of the virtual machine is returned if no displayname exists. |
| displayvm | an optional field whether to the display the vm to the end user or not. |
| domain | the name of the domain in which the virtual machine exists |
| domainid | the ID of the domain in which the virtual machine exists |
| domainpath | path of the domain in which the virtual machine exists |
| forvirtualnetwork | the virtual network for the service offering |
| group | the group name of the virtual machine |
| groupid | the group ID of the virtual machine |
| guestosid | Os type ID of the virtual machine |
| haenable | true if high-availability is enabled, false otherwise |
| hostcontrolstate | the control state of the host for the virtual machine |
| hostid | the ID of the host for the virtual machine |
| hostname | the name of the host for the virtual machine |
| hypervisor | the hypervisor on which the template runs |
| icon | Base64 string representation of the resource icon |
| instancename | instance name of the user vm; this parameter is returned to the ROOT admin only |
| ipaddress | the VM's primary IP address |
| isdynamicallyscalable | true if vm contains XS/VMWare tools inorder to support dynamic scaling of VM cpu/memory. |
| isodisplaytext | an alternate display text of the ISO attached to the virtual machine |
| isoid | the ID of the ISO attached to the virtual machine |
| isoname | the name of the ISO attached to the virtual machine |
| keypairs | ssh key-pairs |
| lastupdated | the date when this virtual machine was updated last time |
| memory | the memory allocated for the virtual machine |
| memoryintfreekbs | the internal memory (KiB) that's free in VM or zero if it can not be calculated |
| memorykbs | the memory used by the VM in KiB |
| memorytargetkbs | the target memory in VM (KiB) |
| name | the name of the virtual machine |
| networkkbsread | the incoming network traffic on the VM in KiB |
| networkkbswrite | the outgoing network traffic on the host in KiB |
| osdisplayname | OS name of the vm |
| ostypeid | OS type id of the vm |
| password | the password (if exists) of the virtual machine |
| passwordenabled | true if the password rest feature is enabled, false otherwise |
| pooltype | the pool type of the virtual machine |
| project | the project name of the vm |
| projectid | the project id of the vm |
| publicip | public IP address id associated with vm via Static nat rule |
| publicipid | public IP address id associated with vm via Static nat rule |
| readonlydetails | List of read-only Vm 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 virtual machine |
| serviceofferingname | the name of the service offering of the virtual machine |
| servicestate | State of the Service from LB rule |
| state | the state of the virtual machine |
| templatedisplaytext | an alternate display text of the template for the virtual machine |
| templateformat | the format of the template for the virtual machine |
| templateid | the ID of the template for the virtual machine. A -1 is returned if the virtual machine was created from an ISO file. |
| templatename | the name of the template for the virtual machine |
| 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 VM |
| userdataname | the name of userdata used for the VM |
| userdatapolicy | the userdata override policy with the userdata provided while deploying VM |
| userid | the user's ID who deployed the virtual machine |
| username | the user's name who deployed the virtual machine |
| vgpu | the vGPU type used by the virtual machine |
| vmtype | User VM type |
| vnfdetails | VNF details |
| vnfnics | NICs of the VNF appliance |
| zoneid | the ID of the availability zone for the virtual machine |
| zonename | the name of the availability zone for the virtual machine |
| affinitygroup(*) | list of affinity groups associated with the virtual machine |
| 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 | virtual machine IDs associated with this affinity group |
| nic(*) | the list of nics associated with vm |
| 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 virtual machine |
| 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 VM |
| 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 |
| 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 vm 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 virtual machine |
| 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 virtualmachines associated with this securitygroup |
| virtualmachineids | the list of virtualmachine ids associated with this securitygroup |
| 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 |