REST - Cloud Servers

Creating a Server

Request

PUT /v2/virtual-machines

Adds a task to create a server with the specified parameters.

Request body

{
   "create_vm": {
       "cpus": $cpus,
       "ram": $memory,
       "compute_zone_id": "$zone_id",
       "name": "$name",
       "boot_type": "$boot_type",
       "cdrom": "$iso_name",
       "os": "$template_id",
       "password": "$password",
       "key_id": "$key_id",
       "user_data": "$user_data",
   }
}

Description of parameters

$cpus (int) - number of VCPUs
$memory (int) - size of RAM memory (in MB)
$zone_id (string) - UUID of the availability zone where the server should be created
$name (string) - name of the server
$boot_type (string) - device from which the virtual machine should boot. Available values:
- image - the system disk will have the system with UUID specified in the $os variable installed
- cdrom - the machine will boot from an ISO image on a virtual CDROM drive
$cdrom - name of the ISO image from which the server should boot - required if $boot_type == ‘cdrom’
$os - ID of the system that should be installed on the system disk - required if $boot_type == ‘image’ - see also: listing operating systems
$password - password passed for installation, if $boot_type == ‘image’ and the selected image supports setting the password
$key_id - SSH key ID specified for installation, if $boot_type == ‘image’ and the selected image supports setting the SSH key
$user_data - Cloud-init content, if $boot_type == ‘image’ and the selected image supports Cloud-init

Response

{  
  "success":true,
  "virtual_machine": {
      "id": $vm_id
  }
}

Returned information

$vm_id (string) - UUID of the new server

Listing Servers

Request

GET /v2/virtual-machines

Returns an array with the list of existing servers.

Response

{  
  "success":true,
  "virtual_machines": [
     {
       "id":"$vm_id",
       "label":"$vm_label",
       "cores": $vm_cpu,
       "ram": $vm_memory,
       "adm": $vm_managed,
       "system": {
           "id": "$system_id",
           "name": "$system_name"
       },
       "cost_per_hour": $vm_cost,
       "state": $vm_state,
       "transfer_used": $vm_transfer,
       "owner": {
           "id": "$owner_id",
           "name": "$owner_name"
       },
       "public_interface": {
           "primary_ip_ipv4address": "$primary_ip",
           "ipv4_addresses": [
               {
                   "id": "$ip_address_id",
                   "ipv4_address": "$ip_address"
               }, { ... }
           ]
       },
       "storage_volumes": [
           {
               "id": "$volume_id",
               "size": $volume_size,
               "system_disk": $volume_is_system
           }, { ... }
       ],
       "zone": {
           "id": "$zone_id",
           "name": "$zone_label"
       },
       "networks": [
           {
               "id": "$network_id",
               "label": "$network_label",
               "mac_address": "$network_mac",
               "type": "$network_type"
           }, { ... }
       ],
       "groups": [
           {
               "id": "$group_id",
               "name": "$group_name"
           }, { ... }
       ]
     }, 
     { ... }
  ]
}

Returned information

$vm_id (string) - UUID of the server
$vm_label (string) - name of the server
$vm_cpu (int) - number of VCPUs assigned to the server
$vm_memory (int) - number of MBs of RAM assigned to the server
$vm_managed (bool) - true if the machine is managed, false if it is not
$system_id (int) - ID of the system installed on the system disk (from /v2/templates)
$system_name (string) - name of the system installed on the system disk
$vm_cost (float) - hourly cost
$vm_state (string) - server state. Possible values:
- online - the machine is on
- offline - the machine is off
- installing - the machine is being installed
- deleting - the machine is being deleted
$vm_transfer (float) - outgoing network transfer charged on the public network interface (in GB)
$owner_id (string) - UUID of the server’s owner
$owner_name (string) - name of the server’s owner
$primary_ip (string) - primary IPv4 address
$ip_address_id (string) - UUID of the network address
$ip_address (string) - IPv4 address
$volume_id (string) - UUID of the disk volume
$volume_size (int) - size of the disk volume (in GB)
$volume_is_system (bool) - true if the volume is a system volume, false otherwise
$zone_id (string) - UUID of the server’s availability zone
$zone_label (string) - name of the server’s availability zone
$network_id (string/int) - ID of the virtual network, in the case of a VLAN network $network_id will be of type int
$network_label (string) - name of the virtual network
$network_mac (string) - MAC address of the interface connected to the virtual network
$network_type (string) - specifies the network type, VLAN or VxLAN, in the case of a VLAN network $network_id will be of type int
$group_id (string) - UUID of the group
$group_name (string) - name of the group

Retrieving server information

Request

GET /v2/virtual-machines/$VM_ID

Returns information about a single server with the given $VM_ID.

Response

{  
  "success":true,
  "virtual_machine": [
     {
       "id":"$vm_id",
       "label":"$vm_label",
       "cores": $vm_cpu,
       "ram": $vm_memory,
       "adm": $vm_managed,
       "system": {
           "id": "$system_id",
           "name": "$system_name"
       },
       "cost_per_hour": $vm_cost,
       "state": $vm_state,
       "transfer_used": $vm_transfer,
       "owner": {
           "id": "$owner_id",
           "name": "$owner_name"
       },
       "public_interface": {
           "primary_ip_ipv4address": "$primary_ip",
           "ipv4_addresses": [
               {
                   "id": "$ip_address_id",
                   "ipv4_address": "$ip_address"
               }, { ... }
           ]
       },
       "storage_volumes": [
           {
               "id": "$volume_id",
               "size": $volume_size,
               "system_disk": $volume_is_system
           }, { ... }
       ],
       "zone": {
           "id": "$zone_id",
           "name": "$zone_label"
       },
       "networks": [
           {
               "id": "$network_id",
               "label": "$network_label",
               "mac_address": "$network_mac",
               "type": "$network_type"
           }, { ... }
       ],
       "groups": [
           {
               "id": "$group_id",
               "name": "$group_name"
           }, { ... }
       ]
     }, 
     { ... }
  ]
}

Returned information

$vm_id (string) - UUID of the server
$vm_label (string) - server name
$vm_cpu (int) - number of VCPUs assigned to the server
$vm_memory (int) - amount of RAM (in MB) assigned to the server
$vm_managed (bool) - true if the machine is managed, false if it is not
$system_id (int) - ID of the system installed on the system disk (from /v2/templates)
$system_name (string) - name of the system installed on the system disk
$vm_cost (float) - hourly cost
$vm_state (string) - server state. Possible values:
- online - the machine is powered on
- offline - the machine is powered off
- installing - the machine is being installed
- deleting - the machine is being deleted
$vm_transfer (float) - outgoing transfer charged from the public network interface (in GB)
$owner_id (string) - UUID of the server owner
$owner_name (string) - name of the server owner
$primary_ip (string) - primary IPv4 address
$ip_address_id (string) - UUID of the network address
$ip_address (string) - IPv4 address
$volume_id (string) - UUID of the disk volume
$volume_size (int) - size of the disk volume (in GB)
$volume_is_system (bool) - true if the volume is a system volume, false if it is not
$zone_id (string) - UUID of the server availability zone
$zone_label (string) - name of the server availability zone
$network_id (string/int) - UUID of the virtual network, in the case of VLAN network type $network_id will be of type int
$network_label (string) - name of the virtual network
$network_mac (string) - MAC address of the interface connected to the virtual network
$network_type (string) - specifies the type of VLAN or VXLAN network, in the case of VLAN network type $network_id will be of type int
$group_id (string) - UUID of the group
$group_name (string) - name of the group

Server scaling

Request

POST /v2/virtual-machines/$VM_ID/resize

Adds a task to resize the server with the given $VM_ID to the desired number of VCPU and RAM size. If the machine is turned on, it will be shut down by sending an ACPI request with a maximum waiting time of $wait_for minutes. If the system does not shut down after $wait_for minutes, the machine is turned off anyway.

Request Content

{
   "cores": $cores,
   "ram": $memory,
   "wait_for": $wait_for
}

Parameter Description

$cores (int) - the desired number of VCPU
$memory (int) - the desired RAM size (in MB)
$wait_for (int) - how many minutes to wait for the server to shut down. Default value: 4

{  
  "success":true
}

Shutting down the server (via ACPI)

Request

POST /v2/virtual-machines/$VM_ID/shutdown

Adds a task to shut down the server with the given $VM_ID. The shutdown request is passed through ACPI, which requires support from the server’s operating system but gives it the ability to orderly close services and the system. If the system does not shut down after $wait_for minutes, the machine is turned off anyway.

Request Content

{
   "wait_for": $wait_for
}

Parameter Description

$wait_for (int) - how many minutes to wait before forcing the system to shut down. Optional parameter, default value: 4

Response

{  
  "success":true
}

Restart the server (via ACPI)

Request

POST /v2/virtual-machines/$VM_ID/reboot

Adds a task to reboot the server with the given $VM_ID. Reboot occurs via ACPI, which requires support from the server’s operating system.

Response

{  
  "success":true
}

Restart the server (via hardware)

Request

POST /v2/virtual-machines/$VM_ID/restart

Adds a task to reboot the server with the given $VM_ID. Restart occurs through simulation of a hard hardware restart.

Response

{  
  "success":true
}

Launching the server console

Request

POST /v2/virtual-machines/$VM_ID/console

Launches the virtual machine console with the given $VM_ID.

Response

{  
  "console": { 
      "port": port, 
      "password": password, 
      "host": host
   }
}

Changing the server name

Request

POST /v2/virtual-machines/$VM_ID/rename

Changes the name of the server with the given $VM_ID.

Request Content

{
   "name": "$vm_label"
}

Parameter Description

$vm_label (string) - the new server name

Response

{  
  "success":true
}

Deleting the server

Request

DELETE /v2/virtual-machines/$VM_ID

Adds a task to delete the server with the given $VM_ID.

Request Content

{
   "deleteResources": $delete_resources
}

Parameter Description

$delete_resources (int) - 0 if additional resources should be detached, 1 if they should be deleted

Response

{  
  "success":true
}

Updated on 18 Nov 2024