Cosmic 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 |
| 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 |
| bootmenutimeout | Timeout (in ms) to for the boot menu | false |
| bootorder | Comma seperated list from which device to boot from first, can one of 'hd','cdrom','network' | false |
| customid | an optional field, in case you want to set a custom id to the resource. Allowed to Root Admins only | false |
| deploymentplanner | Deployment planner to use for vm allocation. Available to ROOT admin only | false |
| details | used to specify the custom parameters. | false |
| diskcontroller | the disk controller to use. Either 'IDE', 'VIRTIO' or 'SCSI' | 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. | 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 |
| 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 |
| macaddress | the MAC-Address for default vm's network | false |
| maintenancepolicy | either 'LiveMigrate' or 'ShutdownAndStart' when performing hypervisor maintenance | false |
| manufacturerstring | Manufacturer String to put in hardware info, defaults to 'Mission Critical Cloud' | 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 |
| optimisefor | Optimise for 'Windows' or 'Generic' | false |
| projectid | Deploy vm for the project | 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 |
| 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 2KB of data after base64 encoding. Using HTTP POST(via POST body), you can send up to 32K 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 |
| bootmenutimeout | Timeout of the boot menu (in ms) |
| bootorder | Boot order priority |
| cpunumber | the number of cpu this virtual machine is running with |
| cpuused | the amount of the vm's CPU currently used |
| created | the date when this virtual machine was created |
| 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 read (bytes) of disk on the vm |
| diskkbswrite | the write (bytes) of disk on the vm |
| diskofferingid | the ID of the disk offering of the virtual machine |
| diskofferingname | the name of the disk offering of the virtual machine |
| 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 |
| 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 |
| isdynamicallyscalable | true if vm contains XS 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 |
| keypair | ssh key-pair |
| laststartdate | Timestamp of last start of VM |
| laststartversion | What Cosmic version did the VM start with |
| maintenancepolicy | Maintenance Policy of the VM |
| manufacturerstring | Manufacturer String to put in hardware info, defaults to 'Mission Critical Cloud' |
| 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 |
| optimisefor | Optimise for 'Windows' or 'Generic' |
| 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 |
| 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 |
| restartrequired | true if VM needs to a stop/start to receive updated VM specs on the hypervisor |
| rootdevicecontroller | controller type of the root volume |
| 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 |
| 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 |
| 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 |
| 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 |
| zoneid | the ID of the availablility 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 |
| description | the description of the affinity group |
| domain | the domain name of the affinity group |
| domainid | the domain ID of the affinity group |
| 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 |
| 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 |
| mirroripaddress | the mirror ip address for the nic |
| mirrorkey | the mirror key for the nic |
| netmask | the netmask of the nic |
| networkid | the ID of the corresponding network |
| networkname | the name of the corresponding network |
| 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 |
| 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 |