Virtual Machines

Entities

Virtual Machine

Field Explanation
id vm identifier
label user-friendly vm description
memory vm memory
cpus vm cpus
cpu_shares share of hypervisor cpu guaranteed
hostname vm hostname
template_id Template to build the vm
initial_password vm initial password
note vm notes
hypervisor_id Hypervisor where the vm is
type type of vm standard, autoscaled, balancer, balancer_failover, firewall
vip whether the user is vip or not
status Status of the vm (unbuilt, recovery, offline, online)
locked Is vm busy with an operation?
suspended Is vm suspended?
strict_virtual_machine_id Keep vm in a different hypervisor from vm_id
operating_system name of the installed operating system
operating_system_distro name of the installed OS distribution
created_at creation date
updated_at latest update date
cdrom does vm have a device CDROM?
boot_type boot device of the vm
location_id location of the vm

Virtual machine list resource:

CPU usage resource

Field Explanation
lapse Timing of the report
machine_id Machine identifier
data List of CPU usages. Empty if not available
time_units Unit of time for the list of CPU usages

Network usage resource

Field Explanation
date_from Start time of the report (UNIX timestamp)
date_to End time of the report (UNIX timestamp)
traffic network usage traffic resource

Note

if data is not available, traffic is an empty dictionary

Network usage traffic resource

Field Explanation
network_id Network identifier
is_public Is public interface? Accepted values: true or false
interface_id Network interface identifier
data network usage traffic data list resource

Network usage traffic data list resource

{
    "0": {
        "traffic_out": 0,
        "traffic_in": 3
    },
    "1": {
        "traffic_out": 33,
        "traffic_in": 55
    },
}

Note

network_usage_traffic_data_list_resource data uses bytes as unit

Parameters format

  • hostname: A string up to 25 characters not starting with a number that can be a combination of letters [A-Za-z], digits [0-9] and dashes (-).
  • initial_root_password: A string of 6-32 characters that can be a combination of letters [A-Za-z], digits [0-9], dashes (-) and lower dashes (_). You can use both lower and uppercase letters.

Operations

Edit virtual machine data

Method:PUT
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>
Success Code:202/200
Returned Data:Virtual machine resource
Has Token:Yes

Edit virtual machine configuration. Some of them might require a reboot.

Parameters:

  • memory: amount of RAM assigned to the VM
  • max_memory
  • cpus: number of CPUs assigned to the VM
  • label: user-friendly VM description
  • hostname: the vm hostname. Notice that this field is just informative so no changes will be made inside the vm.
  • primary_disk_size: new primary disk size in Gigabytes
  • note: user notes for the vm
  • status: (‘online’, ‘offline’, ‘recovery’)
  • cpu_type: changes the cpu type. Reboot is required to apply changes. Accepted values are: amd, intel
  • boot_type: changes the boot device of the vm. Accepted values are: default, cdrom
  • force
  • template_id
  • required_startup
  • noreboot
  • rate_limit

Curl examples

How to change the amount of memory:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"memory": "1024"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Hot to change the amount of CPUs:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"cpus": "4"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

How to change the label:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"label": "NewLabel"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

How to change the hostname:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"hostname": "NewHostname"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

How to change the primary disk size:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"primary_disk_size": "NN"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

How to change the virtualmachine’s notes:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"note": "This is a note."}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"cpu_type": "intel|amd"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

How to change the boot type:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"boot_type": "default|cdrom"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Rebuild a virtual machines

Method:PUT
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Set up the Virtual Machine from the beginning, zeroing disk volumes, and creating the server from zero. It also applies the Operating System again, and the network configuration.

Mandatory parameters:

  • template_id: the ID of a template from which a VM should be rebuilt

Optional parameters:

  • required_startup: set false if you don’t want to start a VM after it’s built. Default is true

Curl example

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"template_id": "TEMPLATE_ID"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Stop/shutdown virtual machine

Method:PUT
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Turn off the virtual machine.

Mandatory parameters:

  • status: offline.

Extra parameters:

  • force: Set to true to force vm shutdown. Default false.

Curl example

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"status": "offline", "force": "true"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Start virtual machine

Method:PUT
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Turn on the virtual machine

Mandatory parameters:

  • status: online

Curl example

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -d '{"status": "online"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Destroy a virtual machine

Method:DELETE
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>
Success Code:202
Returned Data:No data is returned
Has Token:Yes

Destroys a virtual machine, freeing it’s resources. It also deletes any other resource attached to the virtual machine: Disk Volumes, Network Interfaces, IP Addresses, and associated Backups.

Curl example

curl -i -X DELETE https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Get virtual machine

Method:GET
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>
Success Code:200
Returned Data:Virtual machine resource
Has Token:No

Get virtual machine resource.

Curl example

curl -s -X GET https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID -H "Authorization: $TOKEN" -H "Content-Type: application/json" | python -c "import sys, json; print json.load(sys.stdin)['status']"

Segregate Virtual Machine

Method:PUT
Url:/account/<account_id>/virtual_machine/<origin_id>/segregation/<target_id>
Success Code:200
Returned Data:Virtual machine resource
Has Token:No

Note

actual segregation will take place on reboot

Keep this Virtual Machine in a different hypervisor that target Virtual Machine.

Remove segregation between Virtual Machine

Method:DELETE
Url:/account/<account_id>/virtual_machine/<origin_id>/segregation/<target_id>
Success Code:200
Returned Data:Virtual machine resource
Has Token:No

Remove segregation

Create a new virtual machine

Method:POST
Url:/account/<account_id>/virtual_machine
Success Code:Success return Code: 202
Returned Data:Virtual machine resource
Has Token:Yes

Creates a virtual machine if the user has enough resources to build it.

Mandatory parameters:

  • memory: amount of RAM assigned to the VM
  • cpus: number of CPUs assigned to the VM
  • hostname: set the host name for this VM.
  • label: user-friendly VM description
  • primary_disk_size: set the disk space in Gigabytes for this VM for the main disk
  • One of these:
    • template_id: the ID of a template from which a VM should be built
    • iso_id: the ID of an uploaded ISO
    • iso_url: the url of a public ISO
  • location_id: the ID of a location to attach.

Optional parameters to be sent:

  • max_memory: max limit of memory.
  • cpu_type: intel or amd.
  • cpu_shares: number of shared cpus.
  • swap_disk_size: set swap space in Gigabytes. Useless for windows based machines.
  • initial_root_password: the root password for a VM. If none specified, the system will provide a random password.
  • primary_network_id: the ID of the primary network.
  • primary_network_group_id: the ID of the primary network group
  • selected_ip_address: assign the IP address
  • selected_ip_netmask: assign the netmask
  • selected_ip_gateway: assign the gateway
  • required_virtual_machine_build: set true to build VM automatically. true by default
  • data_store_group_primary_id: id of the data store group where to build the primary disk
  • data_store_group_id: id of the data_store_group
  • data_store_group_secondary_id: the data store group id to secondary disks.
  • note: a brief description for the VM
  • secondary_disk_size: size of a secondary disk for the virtual machine. Send this parameter as many times as secondary disks will be created, and with the same order that data_store_group_secondary_id.
  • data_store_group_swap_id: id of the data store group where to build the secondary disk. Send this parameter as many times as secondary disks will be created, and with the same order that secondary_disk_size.
  • rate_limit: set max port speed in Mb, 0 for unlimited. Unlimited by default in private networks, an admin established value in public networks.

Example:

{
    "updated_at": "2018-05-29T08:20:49",
    "vip": false,
    "suspended": 0,
    "label": "testapi",
    "location_id": "178931012",
    "id": "178931011513",
    "template_label": null,
    "is_deletion_machine": false,
    "hostname": "testapi",
    "custom": false,
    "note": null,
    "local_remote_access_port": null,
    "boot_type": "default",
    "memory": 256,
    "type": "standard",
    "virtualization_type": null,
    "status": "unbuilt",
    "initial_password": "rYXtg8cCdLQI",
    "console_lang": "en",
    "operating_system_distro": null,
    "hypervisor_id": "178931017",
    "booted_from": "hd",
    "cpus": 1,
    "strict_virtual_machine_id": null,
    "cdrom": 0,
    "user_id": "178931011324",
    "disk_type": "vd",
    "operating_system": null,
    "locked": 1,
    "created_at": "2018-05-29T08:20:49",
    "remote_access_password": null,
    "cpu_type": "amd",
    "error": 0,
    "identifier": "3geg9n6kbswbq4",
    "template_id": "1789310154",
    "cpu_shares": 1,
    "account_id": 17893,
    "queue_token": "7d9c9446-e2bd-4992-90e6-2c3930dfc757"
}

Curl example

curl -i -X POST https://api.gigas.com/account/ACCOUNT_ID/virtual_machine -d '{ "memory": "128", "cpus": "1", "label": "pruebaApi", "primary_disk_size": "5", "swap_disk_size": "1", "hostname": "pruebaApi", "location_id": 2, "template_id": "1789310154" }' -H "Authorization: apitoken" -H "Content-Type: application/json"

Get bandwith stats from Virtual Machine

Method:GET
Url:/account/<account_id>/virtual_machine/<machine_id>/bw_stats
Success Code:200
Returned Data:network usage resource
Has Token:No

Stats for network usage of a given Virtual Machine

Mandatory parameters:

  • period: period reported. Accepted values: -1H for one hour, -1day for one day, -1M for one month, -1Y for one year.

Example:

{
    "date_from": 1407060000,
    "traffic": [
        [
            {
                "network_id": 1,
                "is_public": true,
                "data": {
                    "0": {
                        "traffic_out": 0,
                        "traffic_in": 0
                    },
                    "1": {
                        "traffic_out": 130438.94177359999,
                        "traffic_in": 42158.54180338
                    }
                },
                "interface_id": 45
            }
        ],
        [
            {
                "network_id": 709,
                "is_public": false,
                "data": {
                    "0": {
                        "traffic_out": 0,
                        "traffic_in": 9022.86425421
                    },
                    "1": {
                        "traffic_out": 100.937692002,
                        "traffic_in": 61278.65241551
                    }
                },
                "interface_id": 46
            }
        ]
    ],
    "date_to": 1409745600
}

Get cpu stats from Virtual Machine

Method:GET
Url:/account/<account_id>/virtual_machine/<machine_id>/cpu_stats
Success Code:200
Returned Data:cpu usage resource
Has Token:No

Stats for cpu usage of a given Virtual Machine

Mandatory parameters:

  • period: period reported. Accepted values: -1H for 1 hour, -30days for 30 days.

Example:

{
    "lapse": "last hour",
    "machine_id": 24,
    "data": [
        10.1541275294,
        10.3190670489,
        10.0094700689,
        10.1866869822,
        10.3192486906,
        10.1546309261,
        10.1858532339,
        10.1536288994,
        10.1871109861,
        10.1537344633,
        10.1534351567,
        0
    ],
    "time_units": "5 minutes"
}

Note

Stats are splitted in smaller chunks, for example the 30 days report returns data divided in 30 units. In this example every unit would represent a day.

Get the list of virtual machines

Method:GET
Url:/account/<account_id>/virtual_machines
Success Code:200
Returned Data:Virtual machines list
Has Token:No

Get a list of virtual machines belonging to the user.

Optional parameters:

  • id: the VM ID, shows only one result(if found)
  • type
  • cpu_type
  • status: online/offline/unbuilt
  • hostname: filter by VM which contains the string in it’s hostname
  • ip_address: VMs which has the ip
  • locked: filter by VM is locked
  • suspended
  • location_id: filter by vm location
  • disk_type: sd/vd
  • label

Reset root password

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/reset_password
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Change root password on the machine in case it’s been lost.

Reboot Virtual Machine

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/reboot
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Restart the Virtual Machine

Optional parameters:

  • recovery: True. in order to reboot in recovery mode

Curl example

curl -i -X POST https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID/reboot -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Rebuild network

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/rebuild_network
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Rebuild the network to apply changes

Apply firewall rules

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/apply_firewall_rules
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Apply changes for firewall.

Apply disks to Virtual Machine

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/apply_disks
Success Code:200
Returned Data:None
Has Token:No

Apply disks to Virtual Machine

Parameters:

  • required_format_disk

Get disks from Virtual Machine

Method:GET
Url:/account/<account_id>/virtual_machine/([0-9]+)/disks
Success Code:200
Returned Data:disk resource list
Has Token:No

List disk attached to the Virtual Machine.

Curl example

curl -i -X GET https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID/disks -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Add new interface to Virtual Machine

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/network_interface
Success Code:201/202
Returned Data:interface resource
Has Token:Yes

Create a new network interface on the vm to connect it to a network.

Parameters:

  • network_id: set the ID of a physical network used to attach this network interface
  • label: give the label of a network interface you wish to attach
  • primary: set true if the interface is primary (set it to have a gateway), false otherwise. Using this parameter you will set to “secondary” any other former primary interface in that vm.
  • rate_limit: set max port speed in Mb, 0 for unlimited. Unlimited by default in private networks, an admin stablished value in public networks.
  • network_interface_id

Curl example

curl -i -X POST https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID/network_interface -d '{ "network_id": "NETWORK_ID", "primary": "true|false", "label": "ethN", "rate_limit": "0|50|100"}' -H "Authorization: $TOKEN" -H "Content-Type: application/json"

Note

Asking for a new interface on a public network where there is already one will result in an error (412).

Note

Returns status code 201 if virtual machine is offline

Get interfaces from Virtual Machine

Method:GET
Url:/account/<account_id>/virtual_machine/([0-9]+)/network_interfaces
Success Code:200
Returned Data:network interface resource list
Has Token:No

List interfaces attached to the Virtual Machine.

Filters:

  • interface_label
  • network_id
  • public

Curl example

curl -i -X GET https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID/network_interfaces -H "Authorization: $TOKEN" -H "Content-Type: application/json"

List Virtual Machine ip addresses

Method:GET
Url:/account/<account_id>/virtual_machine/([0-9]+)/ip_addresses
Success Code:200
Returned Data:IP list resource
Has Token:No

Get the list of IP addresses assigned to the Virtual Machine

Filters:

  • network_id
  • interface_id
  • public

Curl example

curl -i -X GET https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/VM_ID/ip_addresses -H "Authorization: $TOKEN" -H "Content-Type: application/json"

List Virtual Machine firewall rules

Method:GET
Url:/account/<account_id>/virtual_machine/([0-9]+)/firewall_rules
Success Code:200
Returned Data:Firewall rules list
Has Token:No

Get firewall configuration for the Virtual Machine

Filters:

  • command (accept/drop)
  • port
  • address

Get ISO mounted in a Virtual Machine

Method:GET
Url:/account/<account_id>/virtual_machine/([0-9]+)/isos
Success Code:200
Returned Data:Iso Join Resource
Has Token:No

Get the ISO mounted in a virtual machine

Mount an ISO

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/iso
Success Code:200
Returned Data:Virtual machine resource
Has Token:Yes

Mount an ISO in a virtual machine

One of these params should be sent:

  • iso_id: id of an uploaded ISO
  • iso_url: url of an iso (http, https, ftp and ftps protocols are supported)

Example:

{
    "iso_id": 100
}

Unmount an ISO

Method:DELETE
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/iso/<iso_join_id>
Success Code:200
Returned Data:Virtual machine resource
Has Token:Yes

Unmount an ISO from a virtual machine

Note

id passed will be the id of the Iso Join between iso and virtual machine

Create template

Create template from virtual machine

Method:POST
Url:/account/<account_id>/virtual_machine/<id>/template
Success Code:202
Returned Data:Template resource
Has Token:Yes

Optional parameters:

  • label

Get console from a vm

Method:GET
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/remote_console
Success Code:200
Returned Data:Console resource
Has Token:No

Get the console from a virtual machine.

Clone vm

Method:POST
Url:/account/<account_id>/virtual_machine/<virtual_machine_id>/clone
Success Code:202
Returned Data:Virtual machine resource
Has Token:Yes

Clone the source virtual machine identified by the provided ID.

Mandatory parameters:

  • hostname: set the host name for this VM.
  • label: user-friendly VM description.

Optional parameters to be sent:

  • memory: amount of RAM assigned to the VM.
  • cpus: number of CPUs assigned to the VM.
  • max_memory: max limit of memory.
  • cpu_type: intel or amd.
  • secondary_disk_size: size of a secondary disk for the virtual machine. Send this parameter as many times as secondary disks will be created, and with the same order that data_store_group_secondary_id.
  • data_store_group_secondary_id: ID of the data store group where to build the secondary disk. Send this parameter as many times as secondary disks will be created, and with the same order that secondary_disk_size.
  • clone_user_id: the user to whom the virtual machine will be cloned.
  • clone_disk_id: a disk ID from the source VM whose size and data store group must be changed in the new VM. Send this parameter as many times as you wish, once per source disk.
  • clone_disk_size: the new sizes for the disks listed by clone_disk_id. Send this parameter as many times as clone_disk_id and with the same order.
  • clone_disk_data_store_group_id: new data store groups for the disks listed by clone_disk_id. Send this parameter as many times as clone_disk_id and with the same order.
  • required_startup: set true if you want the VM to be started up after it’s cloned. Default is false.