Gandi

Table Of Contents

Previous topic

IP Address API Reference

Next topic

Http Reverse proxy API Reference

Virtual Machine API Reference

Warning

Legacy access to vm.* methods will be removed soon, you will need to use hosting.vm.* instead

Methods

hosting.vm.count(apikey[, opts=nil])

Count virtual machines.

Parameters:
Returns:

int – number of VMs

hosting.vm.create(apikey, vm_spec)
Create a new virtual machine using attributes specified by vm_spec.
Disk, iface, and vm must be in the same datacenter.
Parameters:
Returns:

list of struct – iface_create operation if an iface was created, vm_create operation

hosting.vm.create_from(apikey, vm_spec, disk_spec, src_disk_id)
Create a disk and a virtual machine.
This is a convenient method to do the disk.create and vm.create in a single API call.
Parameters:
Returns:

list of struct – disk_create, iface_create and vm_create operation

hosting.vm.delete(apikey, vm_id)
Delete a VM.
Delete the disk attached in position 0, i.e. the disk used as system disk.
Also delete the first network interface.
Detach all extra disks and network interfaces.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – vm_delete operation

hosting.vm.disk_attach(apikey, vm_id, disk_id[, options=nil])
Attach a disk to a virtual machine.
To access the disk data inside the VM, it MUST be attached to the VM.
When options.position is 0, swaps position with current disk 0.
A disk can be attached to only one VM.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • disk_id (int) – unique identifier of the disk to attach
  • options (struct) – options for the disk attachment
Returns:

struct – disk_attach operation

hosting.vm.disk_detach(apikey, vm_id, disk_id)
Detach a disk from a virtual machine.
If the disk position is 0, i.e. the system disk, the virtual machine must be halted to detach the disk.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • disk_id (int) – unique identifier of the disk to attach
Returns:

struct – disk_detach operation

hosting.vm.disk_rollback(apikey, snapshot_id)
Helper method to rollback a disk (instead of hosting.disk.rollback_from()).

Rollbacking a disk is done by creating a new disk using the given snapshot as source, the old disk is deleted afterwards. So, if the disk you try to rollback is attached to the VM, this method will create operations to stop the VM, detach the old disk, create and attach the new one, and start the VM.

Parameters:
  • apikey (string) – API connection key
  • snapshot_id (int) – snapshot unique identifier
Returns:

list of struct – operations

hosting.vm.iface_attach(apikey, vm_id, iface_id)
Attach a network interface to the VM.
No magic update is made on the interface bandwidth when attaching.
You have to manually update interface bandwidth as you desire.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • iface_id (int) – network interface unique identifier
Returns:

struct – iface_attach operation

hosting.vm.iface_detach(apikey, vm_id, iface_id)
Detach a network interface from the VM.
There is no restriction on detaching every interface.
The VM will be unreachable if you choose to detach all interfaces.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • iface_id (int) – network interface unique identifier
Returns:

struct – iface_detach operation

hosting.vm.info(apikey, vm_id)

Get information about a virtual machine.

Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – VM information

hosting.vm.list(apikey[, opts=nil])

List virtual machines.

Parameters:
Returns:

struct – list of VMs descriptions

hosting.vm.reboot(apikey, vm_id)
Reboot a Virtual Machine.
A reboot message is sent to the VM. If it does not reboot properly after 2 minutes, it is hard-reset (“power cycled”).
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – vm_reboot operation

hosting.vm.start(apikey, vm_id)

Start a virtual machine.

Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – vm_start operation

hosting.vm.stop(apikey, vm_id)
Stop a virtual machine.
A stop message is sent to the VM. If it does not shutdown properly after two stop messages and 5 minutes, the VM is “power switched”.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – vm_stop operation

hosting.vm.update(apikey, vm_id, update_spec)

Update a virtual machine using attributes specified by update_spec.

Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • update_spec (struct) – specifications of the virtual machine to update
Returns:

struct – vm_update operation

Parameters

Disk

parameter of disk.create_from(), disk.delete(), disk.info(), disk.rollback_from(), disk.update(), hosting.disk.create_from(), hosting.disk.delete(), hosting.disk.info(), hosting.disk.rollback_from(), hosting.disk.update(), hosting.vm.create_from(), hosting.vm.disk_attach(), hosting.vm.disk_detach(), hosting.vm.disk_rollback(), vm.create_from(), vm.disk_attach(), vm.disk_detach() and vm.disk_rollback()

used by VMDescription

Iface

parameter of hosting.iface.delete(), hosting.iface.info(), hosting.iface.update(), hosting.vm.iface_attach(), hosting.vm.iface_detach(), iface.delete(), iface.info(), iface.update(), vm.iface_attach() and vm.iface_detach()

used by VMCreateFromDescription and VMDescription

IPVersion

used by IPCountOptions, IPListOptions, IfaceDescription, VMCreateFromDescription and VMDescription

Name Description
4 ipv4
6 ipv6
4 ipv4
6 ipv6
VM

parameter of hosting.vm.delete(), hosting.vm.disk_attach(), hosting.vm.disk_detach(), hosting.vm.iface_attach(), hosting.vm.iface_detach(), hosting.vm.info(), hosting.vm.reboot(), hosting.vm.start(), hosting.vm.stop(), hosting.vm.update(), vm.delete(), vm.disk_attach(), vm.disk_detach(), vm.iface_attach(), vm.iface_detach(), vm.info(), vm.reboot(), vm.start(), vm.stop() and vm.update()

VMCountOptions

parameter of hosting.vm.count() and vm.count()

Name Default Type Mandatory
cores   int or array of int no
datacenter_id   int or array of int no
hostname   array of string or string no
id   int or array of int no
memory   int or array of int no
state   string no
~hostname   string no
VMCreateFromDescription

parameter of hosting.vm.create_from() and vm.create_from()

Changed in version 3.3.0: key shares is deprecated and will be removed in the next major release

Name Default Type Mandatory
datacenter_id   int yes
id of the datacenter where the VM will be spawned
hostname   string yes
hostname of the VM
memory 512 int yes
quantity of RAM in Megabytes to allocate. multiple of 64
ai_active 0 int no
1 to activate Gandi AI
bandwidth 102400 double no
network bandwidth in bit/s used to create the VM’s first network interface in case no iface_id provided
cores 1 int no
number of cpu
iface_id   int no
id of the interface the vm will be attached to
ip_version 4 string no
version of the created ip if iface_id is provided
keys   array of int no
ids of existing ssh keys to use
login   string no
login to create on the VM
password   string no
password to set to the root account and the created login
run   string no
shell command that will run at the first startup of a VM. This command will run with root privileges in the / directory at the end of its boot: network interfaces and disks are mounted
shares   int no
this parameter has no effect, keep for compatibility
ssh_key   string no
ssh public key to authorize to connect to the root account and the created login
vm_max_memory   int no
maximum quantity of RAM in megabytes to allocate for the VM. If the update of memory exceeds the current value of
VMDescription

parameter of hosting.vm.create() and vm.create()

Changed in version 3.3.0: key shares is deprecated and will be removed in the next major release

Name Default Type Mandatory
datacenter_id   int yes
id of the datacenter where the VM will be spawned
hostname   string yes
hostname of the VM
memory 512 int yes
quantity of RAM in Megabytes to allocate. multiple of 64
sys_disk_id   int yes
id of the system disk used to boot the vm
ai_active 0 int no
1 to activate Gandi AI
bandwidth 102400 double no
network bandwidth in bit/s used to create the VM’s first network interface in case no iface_id provided
cores 1 int no
number of cpu
iface_id   int no
id of the interface the vm will be attached to
ip_version 4 string no
version of the created ip if iface_id is provided
keys   array of int no
ids of existing ssh keys to use
login   string no
login to create on the VM
password   string no
password to set to the root account and the created login
run   string no
shell command that will run at the first startup of a VM. This command will run with root privileges in the / directory at the end of its boot: network interfaces and disks are mounted
shares   int no
this parameter has no effect, keep for compatibility
ssh_key   string no
ssh public key to authorize to connect to the root account and the created login
vm_max_memory   int no
maximum quantity of RAM in megabytes to allocate for the VM. If the update of memory exceeds the current value of
VMDiskAttachOptions

parameter of hosting.vm.disk_attach() and vm.disk_attach()

Name Default Type Mandatory
access   string no
read or read/write
position   int no
the desired position of the disk
VMGraphURLs

used by ServerReturn and VMReturn

Name Default Type Mandatory
vcpu   array of string yes
vdi   array of string yes
vif   array of string yes
VMListOptions

parameter of hosting.vm.list() and vm.list()

Name Default Type Mandatory
cores   int or array of int no
datacenter_id   int or array of int no
hostname   array of string or string no
id   int or array of int no
items_per_page 100 int no
number of items returns for the pagination
memory   int or array of int no
page 0 int no
page number for pagination offset
sort_by   string no
used to sort returned items: cores, datacenter_id, hostname, id, memory, state
state   string no
~hostname   string no
VMState

used by VMCountOptions, VMListOptions and VMReturn

Name Description
paused vm is alive but not running
running vm is alive and running
halted vm is stopped
locked vm is paused by Gandi for a legal reason
being_created vm does not exist yet
deleted vm is deleted
VMUpdate

parameter of hosting.vm.update() and vm.update()

Changed in version 3.3.0: key shares is deprecated and will be removed in the next major release

Name Default Type Mandatory
console   boolean no
activate the console
cores   int no
number of cpu
memory   int no
quantity of RAM in megabytes. A multiple of 64
password   string no
shares   int no
compatibility reason, do nothing
ssh_key   string no
vm_max_memory   int no
maximum quantity of RAM in megabytes to allocate for the VM. If the update of memory exceeds the current value of
ProbeReturn

used by VMReturn

Name Type
datasource string
probe device datasource in:
date_created dateTime.iso8601
probe creation date
device_type string
probe device type in: ‘cpu’, ‘iface’,
id int
id of the probe
name string
name of the probe
status string
the probe is active and should be used

Returns

VMReturn

returned by hosting.vm.info(), hosting.vm.list(), vm.info() and vm.list()

Changed in version 3.3.3: keys flex_shares, triggers are deprecated and will be removed in the next major release

Name Type
ai_active int
console int
console_url string
only returned with method hosting.vm.info() and vm.info()
cores int
datacenter_id int
date_created dateTime.iso8601
date_updated dateTime.iso8601
description string
disks array of struct
only returned with method hosting.vm.info() and vm.info()
disks_id struct
flex_shares int
graph_urls struct
only returned with method hosting.vm.info() and vm.info()
hostname string
id int
ifaces array of struct
only returned with method hosting.vm.info() and vm.info()
ifaces_id struct
memory int
probes struct
only returned with method hosting.vm.info() and vm.info()
state string
triggers array of struct
only returned with method hosting.vm.info() and vm.info()
vm_max_memory int
VMTriggersReturn

used by VMReturn

Name Type
datasource string
date_created dateTime.iso8601
device_number int
device_type string
duration int
id int
max_value int
min_value int
recovery_duration int
vm_id int