Add VS

To add a VS, use the following request:

POST /virtual_machines.xml
POST /virtual_machines.json 

XML Request example

curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d 
'<virtual_machine><template_id>8</template_id><label>zaza</label><hostname>zaza</hostname><domain>localdomain</domain><hypervisor_group_id>14</hypervisor_group_id><hypervisor_id>1</hypervisor_id><initial_root_password>ehgebhewvtwh</initial_root_password><memory>128</memory><cpus>1</cpus><cpu_shares>1</cpu_shares><cpu_sockets>12</cpu_sockets><data_store_group_primary_id>18</data_store_group_primary_id><primary_disk_size>5</primary_disk_size><primary_disk_min_iops>100</primary_disk_min_iops><location_id>12</location_id><licensing_server_id>38</licensing_server_id><licensing_type>kms</licensing_type><licensing_key>keyexample</licensing_key><data_store_group_swap_id>18</data_store_group_swap_id><swap_disk_size>1</swap_disk_size><swap_disk_min_iops>100</swap_disk_min_iops><primary_network_group_id>19</primary_network_group_id><selected_ip_address>5.1.1.12</selected_ip_address><rate_limit>1</rate_limit><required_automatic_backup>0</required_automatic_backup><required_virtual_machine_build>1</required_virtual_machine_build><required_virtual_machine_startup>1</required_virtual_machine_startup><time_zone>Atlantic Time (Canada)</time_zone><enable_autoscale>0</enable_autoscale><acceleration_allowed>true</acceleration_allowed><custom_recipe_variables><custom_recipe_variable><name>varname</name><value>value</value><enabled>1</enabled><recipe_joins_attributes type='array'><recipe_id>11</recipe_id></recipe_joins_attributes></custom_recipe_variable></custom_recipe_variables><service_addon_ids type="array"><service_addon_id>273</service_addon_id><service_addon_id>274</service_addon_id></service_addon_ids></virtual_machine>' --url http://onapp.test/virtual_machines.xml

JSON Request example

curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '
{
  "virtual_machine": {
    "acceleration_allowed": "true",
    "cpu_shares": "1",
    "cpu_sockets": "12",
    "cpus": "1",
    "custom_recipe_variables_attributes": [
      {
        "enabled": "1",
        "name": "var_name_1",
        "value": "var_value_1"
      },
      {
        "enabled": "1",
        "name": "var_name_2",
        "value": "var_value_2"
      }
    ],
    "service_addon_ids": [
      273,
      274
    ],
    "data_store_group_primary_id": "18",
    "data_store_group_swap_id": "18",
    "domain": "localdomain",
    "enable_autoscale": "0",
    "hostname": "zaza",
    "hypervisor_group_id": "14",
    "hypervisor_id": "1",
    "initial_root_password": "tyrhsghj657th",
    "label": "zaza",
    "licensing_key": "keyexample",
    "licensing_server_id": "38",
    "licensing_type": "kms",
    "location_id": "12",
    "memory": "128",
    "primary_disk_min_iops": "100",
    "primary_disk_size": "5",
    "primary_network_group_id": "19",
    "rate_limit": "1",
    "recipe_joins_attributes": {
      "123":{"recipe_id":"11"}
    },
    "required_automatic_backup": "0",
    "required_virtual_machine_build": "1",
    "required_virtual_machine_startup": "1",
    "selected_ip_address": "5.1.1.12",
    "swap_disk_min_iops": "100",
    "swap_disk_size": "1",
    "template_id": "8",
    "time_zone": "Atlantic Time (Canada)"
  }
}' --url http://onapp.test/virtual_machines.json

Where:

acceleration_allowed - true if acceleration is enabled for the VS; otherwise false

memory* - amount of RAM assigned to the VS, MB

cpus* - number of CPUs assigned to the VS. For KVM compute resources, this parameter sets CPU sockets by default, unless CPU topology is enabled.

cpu_shares* - required parameter. For KVM compute resource the CPU priority value is always 100. For XEN, set a custom value. The default value for XEN is 1

cpu_units - the amount of CPU units per core if the CPU priority is replaced with CPU units in user bucket.

cpu_sockets - the amount of CPU sockets. This parameter can be set for KVM compute resources only by those users who have Enable CPU topology permission granted.

hostname* - set the host name for this VS

domain - specify the domain for this VS. The default value is localdomain. You can edit the default value for domain in /onapp/interface/config/on_app.yml. This parameter is not applicable to Windows virtual servers. 

instance_package_id - ID of the instance package that will be used to build the VS

label* - user-friendly VS description

location_id - set the ID of the location where the VS should be created

primary_disk_size* - set the disk space for this VS, GB

swap_disk_size* - set swap space. There is no swap disk for Windows-based VSs

primary_disk_min_iops - minimum number of  IO operations per second for primary disk (this is a SolidFire related parameter)

swap_disk_min_iops - minimum number of  IO operations per second for swap disk (this is a SolidFire related parameter)

type_of_format - type of filesystem - ext4. For Linux templates, you can choose ext4 file system instead of the ext3 default one

data_store_group_primary_id - set the ID of the data store zone to which this primary disk is allocated

data_store_group_swap_id - set the ID of the data store zone to which this swap disk is allocated

network_id - the ID of the primary network. Optional parameter that can be used only if it is assigned to the network zone.

primary_network_group_id - the ID of the primary network group. Optional parameter

required_automatic_backup - set 1 if you need automatic backups

rate_limit - set max port speed in Mbps or set 0 to get maximum port speed allowed by your bucket. If this parameter is omitted or sent without value, the default port speed will be configured for the VS. The default port speed depends on the maximum port speed set in your bucket and the Max network interface port speed parameter at Control Panel > Settings >Configuration. The system identifies which of the two values (in the bucket or in the configuration) is lower and sets it as the default port speed during VS creation.

required_virtual_machine_build * - set 1 to build VS automatically

required_virtual_machine_startup - set 1 to start up the VS automatically, otherwise set 0 (default state is "1")

time_zone - the time zone set for the VS. This parameter is applicable only to Windows virtual servers.

selected_ip_address - an IP address to assign to this VS

admin_note - enter a brief comment for the VS. Optional parameter

note - a brief comment a user can add to a VS

template_id * - the ID of a template from which a VS should be built

licensing_server_id * - the ID of a template group where the KMS server details are indicated and to which the template belongs (either directly or through the child group). This parameter is for Windows virtual machines with KMS licensing type only

licensing_type * - the type of a license: mak, km, or user own license. This parameter is required for Windows virtual machines only

licensing_key * - the key of a license, required if you have selected own licensing type, and not required for MAK and KMS licensing types

hypervisor_group_id - the ID of the compute zone in which the VS will be created. Optional: if no compute zone is set, the VS will be built in any available compute zone

hypervisor_id - the ID of a compute resource where the VS will be built. Optional: if no compute resource ID is specified, the VS will be built on the compute resource with the least available RAM (but sufficient RAM for the VS)

initial_root_password - the root password for a VS. Optional, if none specified, the system will provide a random password. It can consist of 6-32 characters, letters [A-Za-z], digits [0-9], dash [ - ] and lower dash [ _ ], and the following special characters: ~ ! @ # $ * _ - + = ` \\ { } [ ] : ; ' , . ? /. You can use both lower- and uppercase letters.

The following characters are not allowed for Windows-based virtual servers:

• percent sign [%]
• double quotation marks [“]
• brackets [<,>]
• vertical bar [|]
• caret [^]
• ampersand [&]
• parentheses [(,)]

initial_root_password_encryption_key - specify the password encryption passphrase

recipe_joins_attributes - an array of recipes to run on the virtual server provisioning with the details:

• sequence_number - must be unique
  • recipe_id - the ID of the recipe 

custom_recipe_variables_attributes - an array of custom variables with the details. 

• enabled - true, if the variable is enabled, otherwise false
• name - variable name
• value - variable value script

service_addon_ids - an array of service add-on IDs, which you want to add to VS

XML Output Example

<virtual_machine>
  <add_to_marketplace nil="true"/>
  <admin_note nil="true"/>
  <allow_resize_without_reboot type="boolean">false</allow_resize_without_reboot>
  <allowed_hot_migrate type="boolean">true</allowed_hot_migrate>
  <allowed_swap type="boolean">true</allowed_swap>
  <booted type="boolean">false</booted>
  <built type="boolean">false</built>
  <cpu_shares type="integer">1</cpu_shares>
  <cpus type="integer">1</cpus>
  <created_at type="datetime">2013-06-11T16:03:58+03:00</created_at>
  <customer_network_id nil="true"/>
  <deleted_at nil="true"/>
  <domain>localdomain</domain>
  <edge_server_type nil="true"/>
  <enable_autoscale type="boolean">false</enable_autoscale>
  <enable_monitis type="boolean">false</enable_monitis>
  <firewall_notrack type="boolean">false</firewall_notrack>
  <hostname>zaza</hostname>
  <hypervisor_id type="integer">1</hypervisor_id>
  <id type="integer">15</id>
  <identifier>l2lnf62bs44bjf</identifier>
<initial_root_password>ehgebhewvtwh</initial_root_password>
  <initial_root_password_encrypted type="boolean">false</initial_root_password_encrypted>
  <label>zaza</label>
<local_remote_access_ip_address>109.123.91.35</local_remote_access_ip_address>
  <local_remote_access_port nil="true"/>
  <locked type="boolean">true</locked>
  <memory type="integer">128</memory>
  <min_disk_size type="integer">5</min_disk_size>
  <note nil="true"/>
  <operating_system>linux</operating_system>
<operating_system_distro>ubuntu</operating_system_distro>
  <preferred_hvs type="array"/>
  <recovery_mode nil="true"/>
<remote_access_password>x9yk3fIMXZBG</remote_access_password>
  <service_password nil="true"/>
  <state>new</state>
  <storage_server_type nil="true"/>
  <strict_virtual_machine_id nil="true"/>
  <suspended type="boolean">false</suspended>
  <template_id type="integer">8</template_id>
  <template_label>Ubuntu 13.04 x64</template_label>
  <time_zone>Atlantic Time (Canada)</time_zone>
  <updated_at type="datetime">2013-06-11T16:03:59+03:00</updated_at>
  <user_id type="integer">1</user_id>
  <vip nil="true"/>
  <xen_id nil="true"/>
  <ip_addresses type="array">
    <ip_address>
      <address>109.123.91.171</address>
      <broadcast>109.123.91.191</broadcast>
      <created_at type="datetime">2013-06-11T14:16:21+03:00</created_at>
      <customer_network_id nil="true"/>
      <disallowed_primary type="boolean">false</disallowed_primary>
      <gateway>109.123.91.129</gateway>
      <hypervisor_id nil="true"/>
      <id type="integer">386</id>
      <ip_address_pool_id nil="true"/>
      <network_address>109.123.91.128</network_address>
      <network_id type="integer">9</network_id>
      <pxe type="boolean">false</pxe>
      <updated_at type="datetime">2013-06-11T14:16:21+03:00</updated_at>
      <user_id nil="true"/>
      <free type="boolean">false</free>
      <netmask>255.255.255.192</netmask>
    </ip_address>
  </ip_addresses>
  <monthly_bandwidth_used>0</monthly_bandwidth_used>
  <total_disk_size type="integer">6</total_disk_size>
</virtual_machine>

Where:

add_to_marketplace - true, if the edge server is added to marketplace. The default value is "false". This parameter is for CDN servers only.

admin_note - administrator comment for the VS

allowed_resize_without_reboot - true if resize without reboot is allowed, otherwise false

allowed_hot_migrate - true if hot migration is allowed, otherwise false

allowed_swap - true if swap is allowed, otherwise false

booted - true, if the VS is boothed, otherwise false

built - true, if the VS is built, otherwise false

cpu_shares - the percentage of allocated CPU priority resource

cpus - number of CPUs assigned to the VS

created_at - the date when the VS was created in the [YYYY][MM][DD]T[hh][mm][ss] format

updated_at - the date when the VS was updated in the [YYYY][MM][DD]T[hh][mm][ss] format

customer_network_id - ID of the customer network

edge_server_type - type of the CDN edge server. This parameter is for CDN servers only.

enable_autoscale - true if autoscaling is allowed for this VS

enable_monitis - deprecated attribute

firewall notrack - parameter for adding firewall rules. It is true for edge servers only. 

hostname - VS hostname

hypervisor_id - the ID of the compute resource, on which the server is deployed

id - the VS ID in OnApp CP database

identifier - the VS identifier

initial_root_password - the VS root password

initial_root_password_encrypted - true, if the root password is encrypted, otherwise false

label - user-friendly VS description

local_remote_access_ip_address - IP address for remote connection

local_remote_access_port - port for remote connection

locked - true if the VS is locked; otherwise false

memory - the RAM size allocated to this VS, MB

min_disk_size - the minimum disk size required to build a VS from a specified template

operating_system - operating system used by the VS

operating_system_distro - the distribution of the OS from which this VS is built

recovery_mode - true if recovery mode allowed, otherwise false

remote_access_password - the password for the remote access

service_password - password of a service user

strict_virtual_machine_id - the ID of a virtual machine that will never reside on the same compute resource with this VS

suspended - true if VS is suspended, otherwise false

template_id - the ID of the template the VS is based on

template_label - the name of the template from which this VS is built

user_id - the ID of a user assigned to this VS

vip - true if the VS has VIP status (gives migration priority)

xen_id - the VS ID set by the virtualization engine

 ip_addresses - an array of IP addresses with the following parameters:

• address - IP address
• broadcast - broadcast address
• created_at - the date when the IP address was created in the [YYYY][MM][DD]T[hh][mm][ss]Z format
• disallowed_primary - true if not allowed to be used as the primary (for VS build), otherwise false
• gateway - gateway address
• id - the ID of the IP address
• ip_address_pool_id - ID of the IP address pool to the IP address belongs to
• network_address - the address of the network
• network_id - the ID of the network
• updated_at - the date when the IP address was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format
• user_id - the ID of a user associated with this IP address
• free - true if free, otherwise false
• netmask - netmask for the IP address

monthly_bandwidth_used - VS monthly bandwidth in KB

 virsh_console - set true to enable Virsh console for the VS, otherwise, false

total_disk_size - total VS disk size

Page History

v. 6.3 Edge 1

• removed required_ip_address_assignment parameter

v. 6.1 Edge 2

• added the virsh_console parameter

v.6.0

• replaced location_group_id with location_id parameter

v.5.8

• removed cpu_threads parameter

v.5.5

• added service_addon_ids parameter 

v.5.4

• added the following parameters:

  • domain 

  • selected_ip_address
• removed selected_ip_address_id parameter

v.5.3

• recipe_ids replaced with recipe_joins_attributes parameter 

• custom_variables replaced with custom_recipe_variables_attributes parameter 

v.5.2

• recipe_ids will be replaced with recipe_joins_attributes parameter in OnApp 5.3
• custom_variables will be replaced with custom_recipe_variables_attributes parameter in OnApp 5.3

v. 4.1

• added the following parameters:
  • location_group_id
  • time_zone

v.4.0 

• added location_group_id parameter

v.3.3.2:

• added the following parameters:
  • cpu_sockets
  • cpu_threads

v. 3.3:

• added cpu_units parameter 

v. 3.1 :

• added the following parameters:
  • custom_variables
  • enabled
  • id
  • name
  • value