Volume (do.volume)¶
Block Storage volumes provide expanded storage capacity for your Droplets and can be moved between Droplets within a specific region. Volumes function as raw block devices, meaning they appear to the operating system as locally attached storage which can be formatted using any file system supported by the OS. They may be created in sizes from 1GiB to 16TiB.
Data Structures¶
Volume¶
- id - string - The unique identifier for the Block Storage volume.
- region - dict - The region that the Block Storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a Block Storage volume, the entire region dict will be returned.
- droplet_ids - list - A list containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
- name - string - A human-readable name for the Block Storage volume. Must be lowercase and be composed only of numbers, letters and “-”, up to a limit of 64 characters.
- description - string - An optional free-form text field to describe a Block Storage volume.
- size_gigabytes - number - The size of the Block Storage volume in GiB (1024^3).
- created_at - string - A time value given in ISO8601 combined date and time format that represents when the Block Storage volume was created.
- droplet_ids - list - This attribute is a list of the Droplets that the volume is attached to.
List all volumes¶
-
do.volume.
list
(region=None)¶
- region - string - Region slug for listing on snapshots from that region - optional
Returns:
- A list of Volume data structures
Related:
Create a new volume¶
-
do.volume.
create
(attribs, wait=False, poll=5, timeout=300)¶
- attribs - dict - Volume information to create by
- size_gigabytes - number - The size of the Block Storage volume in GiB (1024^3). - required
- name - string - A human-readable name for the Block Storage volume. Must be lowercase and be composed only of numbers, letters and “-”, up to a limit of 64 characters. - required
- description - string - An optional free-form text field to describe a Block Storage volume.
- region - string - The region where the Block Storage volume will be created. When setting a region, the value should be the slug identifier for the region. When you query a Block Storage volume, the entire region dict will be returned. Should not be specified with a snapshot_id.
- snapshot_id - string - The unique identifier for the volume snapshot from which to create the volume. Should not be specified with a region_id.
- wait - boolean - Whether to wait until the droplet is ready
- poll - number - Number of seconds between checks (min 1 sec)
- timeout - number - How many seconds before giving up
Returns:
- A Volume data structure
Related:
Create a new volume if name not already present¶
-
do.volume.
present
(attribs, wait=False, poll=5, timeout=300)¶
- attribs - dict - Volume information to create by
- size_gigabytes - number - The size of the Block Storage volume in GiB (1024^3). - required
- name - string - A human-readable name for the Block Storage volume. Must be lowercase and be composed only of numbers, letters and “-”, up to a limit of 64 characters. - required
- description - string - An optional free-form text field to describe a Block Storage volume.
- region - string - The region where the Block Storage volume will be created. When setting a region, the value should be the slug identifier for the region. When you query a Block Storage volume, the entire region dict will be returned. Should not be specified with a snapshot_id.
- snapshot_id - string - The unique identifier for the volume snapshot from which to create the volume. Should not be specified with a region_id.
- wait - boolean - Whether to wait until the droplet is ready
- poll - number - Number of seconds between checks (min 1 sec)
- timeout - number - How many seconds before giving up
Returns:
- A tuple of Volume data structures, the intended and created (None if already exists)
Related:
Retrieve an existing volume by id or name and region¶
-
do.volume.
info
(id=None, name=None, region=None)¶
- id - number - The id of the volume
- name - string - The name of the volume if no id
- region - string - The region slug of the volume if no id
Returns:
- A Volume data structure
Related:
Delete a volume by id or name and region¶
-
do.volume.
destroy
(id=None, name=None, region=None)¶
- id - number - The id of the volume
- name - string - The name of the volume if no id
- region - string - The region slug of the volume if no id
Returns:
- None. A DOBOTOException is thrown if an issue is encountered.
Related:
List snapshots for a volume¶
-
do.volume.
snapshot_list
(id)¶
- id - number - The id of the volume
Returns:
- A list of Image data structures
Related:
Create a snapshot for a volume¶
-
do.volume.
snapshot_create
(id, snapshot_name, wait=False, poll=5, timeout=300)¶
- id - number - The id of the volume
- snapshot_name - string - The name of the snapshot
- wait - boolean - Whether to wait until the droplet is ready
- poll - number - Number of seconds between checks (min 1 sec)
- timeout - number - How many seconds before giving up
Returns:
- An Image data structure
Related:
Attach a volume by id or name to a droplet¶
-
do.volume.
attach
(id=None, name=None, region=None, droplet_id=None, wait=False, poll=5, timeout=300)¶
- id - number - The id of the volume
- name - string - The name of the volume if no id
- region - string - The region slug of the volume if no id
- droplet_id - number - The id of the droplet
- wait - boolean - Whether to wait until the droplet is ready
- poll - number - Number of seconds between checks (min 1 sec)
- timeout - number - How many seconds before giving up
Returns:
- An Action data structure
Related:
Remove a volume by id or name from a droplet¶
-
do.volume.
detach
(id=None, name=None, region=None, droplet_id=None, wait=False, poll=5, timeout=300)¶
- id - number - The id of the volume
- name - string - The name of the volume if no id
- region - string - The region slug of the volume if no id
- droplet_id - number - The id of the droplet
- wait - boolean - Whether to wait until the droplet is ready
- poll - number - Number of seconds between checks (min 1 sec)
- timeout - number - How many seconds before giving up
Returns:
- An Action data structure
Related:
Resize a volume¶
-
do.volume.
resize
(id, size, region=None, wait=False, poll=5, timeout=300)¶
- id - number - The id of the volume
- size_gigabytes - int - The new size of the Block Storage volume in GiB (1024^3). - true
- region - string - The slug identifier for the region the volume is located in. -
Returns:
- An Action data structure
Related:
List all actions for a volume¶
-
do.volume.
action_list
(id)¶
- id - number - The id of the volume
Returns:
- A list of Action data structures
Related: