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, firewall
vip	whether the user is vip or not
status	Status of the vm (unbuilt, 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:

[Virtual machine resource 1, Virtual machine resource 2, …]

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.

Virtual Machine Lock¶

Field	Explanation
description	Additional info about the lock
updated_at	Updated date
lock_type	lock type: Task, Snapshot, Admin
hypervisor_id	Hypervisor where the vm lock is
id	Lock identifier
created_at	Creation date
virtual_machine_id	Virtual Machine identifier

Virtual machine lock list resource:

[Virtual machine lock resource 1, Virtual machine lock resource 2, …]

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: max limit of memory. This parameter is deprecated and will be ignored.

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’)

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']"

Get segregated {resource_name} list¶

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

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

max_memory: max limit of memory. This parameter is deprecated and will be ignored.

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:

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",
    "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

Valid sort fields:

identifier

label

memory

operating_system

operating_system_distro

status

location_id

disks_size: the total amount of space taken by all the virtualmachine’s disks

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:

force: Set to true to force vm kill. Default false. Only applies to Oracle. Other providers ignore this parameter.

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.

max_memory: max limit of memory. This parameter is deprecated and will be ignored.

cpus: number of CPUs assigned to the VM.

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.

Get snapshots from Virtual Machine¶

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

List snapshots of the Virtual Machine.

Curl example¶

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

Delete all the snapshots from the Virtual Machine and merge all the pending changes to disks¶

Method: DELETE
Url: /account/<account_id>/virtual_machine/<virtual_machine_id>/snapshots
Success Code: 200
Returned Data: Empty content
Has Token: No

List snapshots of the Virtual Machine.

Curl example¶

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