Virtual Machine API Reference¶
Methods¶
-
hosting.vm.
can_migrate
(apikey, vm_id)¶ - Check if a vm can migrate between datacenters.
Parameters: - apikey (string) – API connection key
- vm_id (int) – VM unique identifier
Returns: struct –
migration capabilities for vm
-
hosting.vm.
count
(apikey[, opts=nil])¶ Count virtual machines.
Parameters: - apikey (string) – API connection key
- opts (struct) –
Filtering options
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: - apikey (string) – API connection key
- vm_spec (struct) –
specifications of the VM to create
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: - apikey (string) – API connection key
- vm_spec (struct) –
specifications of the VM to create
- disk_spec (struct) –
specifications of the Disk to create
- src_disk_id (int) – source disk unique identifier
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: - apikey (string) – API connection key
- opts (struct) –
Filtering options
Returns: struct –
list of VMs descriptions
-
hosting.vm.
migrate
(apikey, vm_id[, finalize_migration=False])¶ - Migrate a vm between datacenters.
Parameters: - apikey (string) – API connection key
- vm_id (int) – VM unique identifier
- finalize_migration (boolean) – finalize migration
Returns: struct –
hosting_migration_vm operation
-
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[, params=nil])¶ Start a virtual machine.
Parameters: - apikey (string) – API connection key
- vm_id (int) – VM unique identifier
- params (struct) –
Optional parameters passed to the VM during the boot process.
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.migrate()
,disk.rollback_from()
,disk.update()
,hosting.disk.create_from()
,hosting.disk.delete()
,hosting.disk.info()
,hosting.disk.migrate()
,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()
andvm.disk_rollback()
used by
VMDescription
Iface
¶parameter of
hosting.iface.delete()
,hosting.iface.info()
,hosting.iface.migrate()
,hosting.iface.update()
,hosting.vm.iface_attach()
,hosting.vm.iface_detach()
,iface.delete()
,iface.info()
,iface.migrate()
,iface.update()
,vm.iface_attach()
andvm.iface_detach()
used by
VMCreateFromDescription
andVMDescription
IPVersion
¶used by
IPCountOptions
,IPListOptions
,IfaceDescription
,VMCreateFromDescription
andVMDescription
Name Description 4 ipv4 6 ipv6 4 ipv4 6 ipv6
VM
¶parameter of
hosting.vm.can_migrate()
,hosting.vm.delete()
,hosting.vm.disk_attach()
,hosting.vm.disk_detach()
,hosting.vm.iface_attach()
,hosting.vm.iface_detach()
,hosting.vm.info()
,hosting.vm.migrate()
,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.migrate()
,vm.reboot()
,vm.start()
,vm.stop()
andvm.update()
VMCountOptions
¶parameter of
hosting.vm.count()
andvm.count()
Name Default Type Mandatory cores int or array of int no datacenter_id
int or array of int no date_created string no farm array of string or string 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()
andvm.create_from()
Changed in version 3.3.36: key
ai_active
is deprecated and will be removed in the next major release.
.Changed in version 3.3.34: keys
farm
,ssh_key
have changed.
farm
optional parameter added.
ssh_key
might also be a List.Changed in version 3.3.28: key
hostname
has changed.
hostname
parameter is now optional.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 thedatacenter
ai_active 0 int no this parameter has no effect, keep for compatibility bandwidth 102400 double no network bandwidth in bit/s used to create the VM’s first cores 1 int no number of cpu farm string no hostname string no hostname of the VM iface_id int no id
of theinterface
the vm will beip_version
4 string no version of the created ip if iface_id
is providedkeys
array of int no ids of existing ssh keys to use login string no login to create on the VM memory 512 int no quantity of RAM in Megabytes to allocate. multiple of 64 password string no password to set to the root account and the created run string no shell command that will run at the first startup of a VM. script string no script contents, that will run at the first startup of a script_args string no shares int no this parameter has no effect, keep for compatibility ssh_key array of string or string no ssh public key to authorize to connect to the root vm_max_memory int no maximum quantity of RAM in megabytes to allocate
VMDescription
¶parameter of
hosting.vm.create()
andvm.create()
Changed in version 3.3.36: key
ai_active
is deprecated and will be removed in the next major release.
.Changed in version 3.3.34: key
farm
has changed.
farm
optional parameter added.Changed in version 3.3.28: key
hostname
has changed.
hostname
parameter is now optional.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 thedatacenter
sys_disk_id int yes id
of thesystem disk
used toai_active 0 int no this parameter has no effect, keep for compatibility bandwidth 102400 double no network bandwidth in bit/s used to create the VM’s first cores 1 int no number of cpu farm string no hostname string no hostname of the VM iface_id int no id
of theinterface
the vm will beip_version
4 string no version of the created ip if iface_id
is providedkeys
array of int no ids of existing ssh keys to use login string no login to create on the VM memory 512 int no quantity of RAM in Megabytes to allocate. multiple of 64 password string no password to set to the root account and the created run string no shell command that will run at the first startup of a VM. script string no script contents, that will run at the first startup of a script_args string no shares int no this parameter has no effect, keep for compatibility ssh_key array of string or string no ssh public key to authorize to connect to the root vm_max_memory int no maximum quantity of RAM in megabytes to allocate
VMDiskAttachOptions
¶parameter of
hosting.vm.disk_attach()
andvm.disk_attach()
Name Default Type Mandatory access
string no read
orread/write
position int no the desired position of the disk
VMGraphURLs
¶used by
ServerReturn
andVMReturn
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()
andvm.list()
Name Default Type Mandatory cores int or array of int no datacenter_id
int or array of int no date_created string no farm array of string or string no hostname array of string or string no id int or array of int no items_per_page 100 int no number of items returned 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, date_created, farm, hostname, id, memory, state state
string no ~hostname string no
VMStart
¶parameter of
hosting.vm.start()
andvm.start()
Changed in version 3.3.34: key
ssh_key
has changed.
ssh_key
might also be a List.
Name Default Type Mandatory farm string no keys
array of int no login string no password string no run string no script string no script_args string no ssh_key array of string or string no
VMState
¶used by
VMCountOptions
,VMListOptions
andVMReturn
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 being_migrated vm is being migrated to another DC
VMUpdate
¶parameter of
hosting.vm.update()
andvm.update()
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 vm_max_memory int no maximum quantity of RAM in megabytes to allocate
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¶
PublicVMCanMigrate
¶returned by
hosting.vm.can_migrate()
VMReturn
¶returned by
hosting.vm.info()
,hosting.vm.list()
,vm.info()
andvm.list()
Changed in version 3.3.36: key
is_migrating
has been added.
is_migrating
parameter.Changed in version 3.3.34: key
farm
has been added.
farm
parameter.Changed in version 3.3.30: key
hvm_state
has been added.
hvm_state
parameter.Changed in version 3.3.3: keys
flex_shares
,triggers
are deprecated and will be removed in the next major release.
.
.Changed in version 3.3.25: key
graph_urls
is 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()
andvm.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()
andvm.info()
disks_id struct entity_id string farm string flex_shares int graph_urls
struct only returned with method hosting.vm.info()
andvm.info()
hostname string hvm_state
string only returned with method hosting.vm.info()
andvm.info()
id int ifaces
array of struct only returned with method hosting.vm.info()
andvm.info()
ifaces_id struct is_migrating boolean memory int probes
struct only returned with method hosting.vm.info()
andvm.info()
state
string triggers
array of struct only returned with method hosting.vm.info()
andvm.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