Disk API Reference

Methods

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

Count the number of disks.

Parameters:
Returns:

int – number of disks
hosting.disk.create(apikey, disk_spec)
Create an empty disk with respect to the attributes specified by disk_spec.
It checks the available quota.

New in version 3.3.35: opened datacenter constraint

Parameters:
Returns:

struct – disk_create Operation
hosting.disk.create_from(apikey, disk_spec, src_disk_id)
Create a disk with the same data as the disk identified by src_disk_id.
kernel_id, kernel_cmdline, size, and label will be copied from the source disk.
Parameters:
Returns:

struct – disk_create operation
hosting.disk.delete(apikey, disk_id)
Delete a disk. ALL DATA WILL BE ERASED.
Free the quota used by the disk size.
The disk must not be attached to a VM.
Parameters:
  • apikey (string) – API connection key
  • disk_id (int) – disk unique identifier
Returns:

struct – disk_delete operation
hosting.disk.info(apikey, disk_id)

Get information about a disk.

Parameters:
  • apikey (struct) – API connection key
  • disk_id (int) – disk unique identifier
Returns:

struct – disk information
hosting.disk.list(apikey[, opts=nil])

List the disks.

Parameters:
Returns:

list of struct – list of disks
hosting.disk.list_kernels(apikey, datacenter_id)

List of available kernels for the given datacenter.

Parameters:
  • apikey (struct) – API connection key
  • datacenter_id (int) – datacenter unique identifier
Returns:

struct – list of kernels
hosting.disk.list_options(apikey, kernel_version)

List available options for the given kernel version.

Parameters:
  • apikey (struct) – API connection key
  • kernel_version (string) – version of the kernel
Returns:

struct – list of options and their parameters
hosting.disk.migrate(apikey, disk_id, target_dc)
Migrate a disk between datacenters.
Parameters:
  • apikey (string) – API connection key
  • disk_id (int) – disk unique identifier
  • target_dc (int) – datacenter unique identifier
Returns:

struct – hosting_migration_disk operation
hosting.disk.rollback_from(apikey, snapshot_id)
Rollback a disk to the last taken snapshot.

It creates a disk to get a new id, then asks the backend to rollback the disk with a ‘disk_rollback’ operation. The current source disk of the snapshot is put in state ‘rollback’. This state prevents modifications on the disk from some operations. The disk is not counted in the quota. The caller gets the new disk id in the returned operating mapping with op[‘id’].

Parameters:
  • apikey (struct) – API connection key
  • snapshot_id (int) – unique identifier of the snapshot to rollback
Returns:

struct – disk_rollback_from operation with the id of the new disk
hosting.disk.update(apikey, disk_id, disk_spec)
Update a disk with respect to the attributes specified by disk_spec.
By now, you can’t shrink a disk.

If you update kernel or kernel_cmdline, you will have to restart the VM where the disk is attached.

If the size is modified the logged user must have enough free disk quota.

When updating name or size, if the disk is attached to a VM, this VM will be automatically rebooted.

Parameters:
Returns:

struct – disk_update operation

Parameters

DiskCopyDescription

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

Changed in version 3.2.9: key snapshot_profile has changed.
snapshot_profile added to activate a snapshot profile when creating the disk.

Changed in version 3.2.14: key size has changed.
size parameter added to re``size`` the disk after creation.

Changed in version 3.1.9: key repulse_from has changed.
repulse_from attribute changed from an integer to an array of integers.

Name Default Type Mandatory
datacenter_id   int no
id of the datacenter
name   string no
name of the disk
repulse_from   array of int no
list of disk_id that will not be in the same storage
size   int no
disk size, in megabytes
snapshot_profile   int no
id of the
type data string no
disk type
DiskCountOptions

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

Name Default Type Mandatory
can_snapshot   boolean no
filter disks that support snapshot or not
datacenter_id   int or array of int no
id of the datacenter
date_created   array of string or string no
id   int or array of int no
id of the disk
name   array of string or string no
name of the disk
size   int or array of int no
filter disk size in megabytes (multiple of 1024)
source   int or array of int no
id of the disk used when
state   string no
filter disk state
type   string no
vm_id   int or array of int no
id of the vm
~name   string no
filter disk name that match this filter
DiskCreateFromType

used by DiskCopyDescription

Name Description
data -
snapshot -
snapshot_auto -
DiskCreateType

used by DiskDescription

Name Description
data -
backup -
DiskDescription

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

Changed in version 3.3.28: keys size, name have changed.
size parameter is now optional, and defaults to 10G.
name parameter is now optional.

Changed in version 3.2.9: key snapshot_profile has changed.
snapshot_profile added to activate a snapshot profile when creating the disk.

Changed in version 3.1.9: key repulse_from has changed.
repulse_from changed from a simple integer to an array of integers.

Name Default Type Mandatory
datacenter_id   int yes
id of the datacenter
name   string no
name of the disk
repulse_from   array of int no
list of disk_id that will not be in the same storage
size 10240 int no
disk size, in megabytes
snapshot_profile   int no
id of the :data:`snapshot
type data string no
disk type
DiskListOptions

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

Name Default Type Mandatory
can_snapshot   boolean no
filter disks that support snapshot or not
datacenter_id   int or array of int no
id of the datacenter
date_created   array of string or string no
id   int or array of int no
id of the disk
items_per_page 100 int no
number of items returned for the pagination
name   array of string or string no
filter disk name that match exactly this filter
page 0 int no
page number for pagination offset
size   int or array of int no
filter disk size in megabytes (multiple of 1024)
sort_by   string no
used to sort returned items: can_snapshot, datacenter_id, date_created, id, name, size, source, state, type, vm_id
source   int or array of int no
id of the disk used when
state   string no
filter disk state
type   string no
vm_id   int or array of int no
id of the vm
~name   string no
filter disk name that match this filter
DiskState

used by DiskCountOptions, DiskListOptions and DiskReturn

Changed in version 3.3.36: key added has changed.
added being_migrated state.

Name Description
being_created -
created -
rollback -
paused -
being_migrated -
redemption -
deleted -
DiskType

used by DiskCountOptions, DiskListOptions and DiskReturn

Name Description
system -
image -
data -
backup -
snapshot -
snapshot_auto -
DiskUpdate

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

Name Default Type Mandatory
cmdline   string no
kernel parameters used at the boot sequence. use hosting.disk.list_options() for available options.
cmdline_options   struct no
kernel parameters as a struct to build the cmdline. use hosting.disk.list_options() for available options.
kernel   string no
new kernel identifier to use if specified
name   string no
new name of the disk if specified
size   int no
new size of the disk in megabytes if specified
snapshot_profile   int or string no
id of the snapshot profile
DiskVisibility

used by DiskReturn

Name Description
all -
alpha -
private -
community -
hidden -

Returns

DiskReturn

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

used by VMReturn

Changed in version 3.3.36: key add has changed.
add is_migrating field.

Name Type
can_snapshot boolean
1 if the disk support snapshot
datacenter_id int
id of the datacenter
date_created dateTime.iso8601
date_updated dateTime.iso8601
entity_id string
id int
disk or snapshot unique identifier
is_boot_disk boolean
is_migrating boolean
kernel_cmdline struct
kernel options used according to hosting.disk.list_options()
only returned with method disk.info() and hosting.disk.info()
kernel_version string
version of the kernel
label string
name string
size int
size of the disk in megabyte
snapshot_profile struct
only returned with method disk.info() and hosting.disk.info()
snapshot_profile_id int
id of the snapshot profile
only returned with method disk.list() and hosting.disk.list()
snapshots_id struct
list of snapshot id for the disk. hosting.disk.info accept snapshot ``id`()
source int
id of the disk used when
state string
total_size int
size of the disk in megabyte including its snapshot profile quota_factor
type string
visibility string
vms_id struct
list of id of vm that mount the disk
KernelList

returned by disk.list_kernels() and hosting.disk.list_kernels()

array of kernels sorted by operating system.

key value
bsd list of kernel identifier (string)
linux list of kernel identifier (string)

Warning

bsd kernels are experimental and should not be used for production usage.

SnapshotProfileReturn

used by DiskReturn

Name Type
id int
identifier of the shapshot profile
kept_total int
number of snapshots to keep
name string
name of the snapshot
quota_factor int
financial cost multiplier applied to the total disk size to calculate its price. Used in PaaS only, which does not use Gandi credits
OperationReturn

returned by disk.create_from(), disk.create(), disk.delete(), disk.migrate(), disk.rollback_from(), disk.update(), hosting.disk.create_from(), hosting.disk.create(), hosting.disk.delete(), hosting.disk.migrate(), hosting.disk.rollback_from(), hosting.disk.update(), hosting.iface.create(), hosting.iface.delete(), hosting.iface.migrate(), hosting.iface.update(), hosting.ip.update(), hosting.vm.create_from(), hosting.vm.create(), hosting.vm.delete(), hosting.vm.disk_attach(), hosting.vm.disk_detach(), hosting.vm.disk_rollback(), hosting.vm.iface_attach(), hosting.vm.iface_detach(), hosting.vm.migrate(), hosting.vm.reboot(), hosting.vm.start(), hosting.vm.stop(), hosting.vm.update(), iface.create(), iface.delete(), iface.migrate(), iface.update(), ip.update(), vm.create_from(), vm.create(), vm.delete(), vm.disk_attach(), vm.disk_detach(), vm.disk_rollback(), vm.iface_attach(), vm.iface_detach(), vm.migrate(), vm.reboot(), vm.start(), vm.stop() and vm.update()

Name Type
date_created dateTime.iso8601
date_start dateTime.iso8601
date_updated dateTime.iso8601
disk_id int
id of the disk or nil
id int
operation unique identifier
iface_id int
id of the interface or nil
ip_id int
id of the IP or nil
source string
handle of the account that create the operation
step string
current step of the operation
type string
operation type
vm_id int
id of the VM or nil
Possible Errors
Error identifier Type
authorization_error support_recoverable
An authorization error happened
duplicate fatal
The wanted object is duplicate
missing_parameter client_recoverable
There is a missing parameter
ratelimit temporary
The query was ratelimited
timeout temporary
The query timeout
unknown unknown
Unknown