Apache CloudStack v4.1.0 User 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 |
| 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 |
| domainid | an optional domainId for the virtual machine. If the account parameter is used, domainId must also be used. | 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 | 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 - 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 |
| 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 |
| projectid | Deploy vm for the project | 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 network offering supports specifying ip ranges; 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. Currently only HTTP GET is supported. Using HTTP GET (via querystring), you can send up to 2KB of data after base64 encoding. | false |
Response Tags
| Response Name | Description |
| id | the ID of the virtual machine |
| account | the account associated with the virtual machine |
| cpunumber | the number of cpu this virtual machine is running with |
| cpuspeed | the speed of each cpu |
| cpuused | the amount of the vm's CPU currently used |
| created | the date when this virtual machine was created |
| displayname | user generated name. The name of the virtual machine is returned if no displayname exists. |
| domain | the name of the domain in which the virtual machine exists |
| domainid | the ID 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 |
| 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 |
| instancename | instance name of the user vm; this parameter is returned to the ROOT admin only |
| 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 |
| keypair | ssh key-pair |
| memory | the memory allocated for the virtual machine |
| name | the name of the virtual machine |
| networkkbsread | the incoming network traffic on the vm |
| networkkbswrite | the outgoing network traffic on the host |
| password | the password (if exists) of the virtual machine |
| passwordenabled | true if the password rest feature is enabled, false otherwise |
| 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 |
| rootdeviceid | device ID of the root volume |
| rootdevicetype | device type of the root volume |
| serviceofferingid | the ID of the service offering of the virtual machine |
| serviceofferingname | the name of the service offering of the virtual machine |
| state | the state of the virtual machine |
| templatedisplaytext | an alternate display text 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 |
| zoneid | the ID of the availablility zone for the virtual machine |
| zonename | the name of the availability zone for the virtual machine |
| nic(*) | the list of nics associated with vm |
| id | the ID of the nic |
| broadcasturi | the broadcast uri of 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 |
| isdefault | true if nic is default, false otherwise |
| isolationuri | the isolation uri of the nic |
| macaddress | true if nic is default, false otherwise |
| netmask | the netmask of the nic |
| networkid | the ID of the corresponding network |
| networkname | the name of the corresponding network |
| traffictype | the traffic type of the nic |
| type | the type of the nic |
| 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 |
| name | the name of the security group |
| project | the project name of the group |
| projectid | the project id of the 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 |
| 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 |
| 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 |
| 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 |
| tags(*) | the list of resource tags associated with vm |
| 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 |
| 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 |