Initrd (initial ramdisk) and actual volumes serve different purposes. An initrd is a file system loaded into memory during the boot process of the instance. Any new files created as well as any modifications made to files in the initrd are lost when the instance is stopped. In contrast, a volume is a persistent storage device that keeps data across restarts. In addition, it can be initialized with a set of files with one instance and then be detached and attached to a another one.
List Volumes
Return the current status and the configuration of one or more volumes specified by either UUID(s) or name(s). If no identifier is provided, all volumes are returned.
query Parameters
detailsWhether to include details about the volume in the response. By default this is set to true, meaning that all information about the volume will be included in the response. If set to false, only the basic information about the volume will be included, such as its name and UUID.
countThe maximum number of volumes to return. If set to 0 or not set, all volumes matching filters will be returned. When filtering by IDs, this should not be set.
fromIf set, the listing starts from the volume with the given UUID or at the given ISO8601 creation timestamp (inclusive). When count is 0 or not set, a UUID value may be used to match a specific volume by UUID.
tagsA list of tags to filter the volumes by.
orderThe sort order for the returned volumes.
Valid values are PAGINATION_ORDER_ASC (ascending, oldest first) and
PAGINATION_ORDER_DESC (descending, newest first). Defaults to
PAGINATION_ORDER_ASC.
sortbyThe field to sort the volumes by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
List Volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
List Volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Create Volume
Create a volume given the specified configuration parameters.
The volume is automatically initialized with an empty file system.
After initialization, the volume is in the available state and can be
attached to an instance with the PUT /v1/volumes/attach endpoint.
Note that, the size of a volume cannot be changed after creation.
Create Volume › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object | |
| type = object |
size_mbThe size of the volume in megabytes.
Create Volume › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Delete Volumes
Delete one or more volumes by their UUID(s) or name(s). If the volumes are still attached to an instance, the operation fails. After this call, the IDs associated with the volumes are no longer valid.
Delete Volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
Delete Volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Update Volumes
Update one or more volumes specified by either UUID(s) or name(s).
Update Volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the volume to update. Mutually exclusive with name.
Update Volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Attach Volumes
Attach one or more volumes specified by ID(s) (name or UUID) to instances
so that the volumes are mounted when the instances start. The volumes need
to be in available state and the instances must be in stopped state.
Attach Volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the volume to attach. Mutually exclusive with name. Exactly one of uuid or name must be provided.
Attach Volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Clone Volumes
Clone one or more volumes given by their ID(s) (name or UUID). The volumes to be cloned must not be mounted to any instance or only mounted as read-only. They also need to not be busy or in an error state. This operation is most useful when cloning template volumes.
Clone Volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the volume to clone. Mutually exclusive with name.
Clone Volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Detach Volumes
Detach volumes specified by ID(s) (name or UUID) from instances. If no particular instance is specified the volume is detached from all instances. The instances from which to detach must not have the volumes mounted. The API returns an error for each instance from which it was unable to detach the volume. If the volume has been created together with an instance, detaching the volume will make it persistent (i.e., it survives the deletion of the instance).
Detach Volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the volume to detach. Mutually exclusive with name. Exactly one of uuid or name must be provided.
Detach Volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
List template volumes
Return the current status and the configuration of one or more template volumes specified by either UUID(s) or name(s). If no identifier is provided, all template volumes are returned.
query Parameters
detailsWhether to include details about the template volumes in the response. By default this is set to true, meaning that all information about the templates will be included in the response. If set to false, only the basic information about the templates will be included, such as their name and UUID.
countThe maximum number of template volumes to return. If set to 0 or not set, all volumes matching filters will be returned. When filtering by IDs, this should not be set.
fromIf set, the listing starts from the template with the given UUID or at the given ISO8601 creation timestamp (inclusive). When count is 0 or not set, a UUID value may be used to match a specific template by UUID.
tagsA list of tags to filter the template volumes by.
orderThe sort order for the returned template volumes.
Valid values are PAGINATION_ORDER_ASC (ascending, oldest first) and
PAGINATION_ORDER_DESC (descending, newest first). Defaults to
PAGINATION_ORDER_ASC.
sortbyThe field to sort the template volumes by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
List template volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
List template volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Create template volume
Converts one or more existing volumes given by their ID(s) (name or UUID) into template volumes. This operation is irreversible in the sense that a template volume cannot be converted back into a regular volume.
The existing volume(s) must not be attached to any instance and must be in
the available state.
Create template volume › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
Create template volume › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Delete template volumes
Delete one or more template volumes by their UUID(s) or name(s). After this call, the IDs associated with the template volumes are no longer valid.
Delete template volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
Delete template volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Update template volumes
Update one or more template volumes specified by either UUID(s) or name(s).
Update template volumes › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the template volume to update. Mutually exclusive with name.
Update template volumes › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Get template volume by UUID
Return the current status and the configuration of a particular template volume by its UUID.
path Parameters
uuidThe UUID of the template volume to retrieve.
query Parameters
detailsWhether to include details about the template volume in the response. By default this is set to true, meaning that all information about the template will be included in the response. If set to false, only the basic information about the template will be included, such as its name and UUID.
Get template volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Delete template volume by UUID
Delete the specified template volume by its UUID. After this call, the IDs associated with the template volume are no longer valid.
path Parameters
uuidThe UUID of the template volume to delete.
Delete template volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Update template volume by UUID
Update the specified template volume by its UUID.
path Parameters
uuidThe UUID of the template volume to update.
Update template volume by UUID › Request Body
propThe property to modify.
opThe operation to perform.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe value for the update operation. The type depends on the property and operation:
- For "tags": array of Strings
- For "delete_lock": boolean
Update template volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Get Volume by UUID
Return the current status and the configuration of a particular volume by its UUID.
path Parameters
uuidThe UUID of the volume to retrieve.
query Parameters
detailsWhether to include details about the volume in the response. By default this is set to true, meaning that all information about the volume will be included in the response. If set to false, only the basic information about the volume will be included, such as its name and UUID.
Get Volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Delete Volume by UUID
Delete the specified volume by its UUID. If the volume is still attached to an instance, the operation fails. After this call, the IDs associated with the volume are no longer valid.
path Parameters
uuidThe UUID of the volume to delete.
Delete Volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Update Volume by UUID
Update the specified volume by its UUID.
path Parameters
uuidThe UUID of the volume to update.
Update Volume by UUID › Request Body
propThe property to modify.
opThe operation to perform.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe value for the update operation. The type depends on the property and operation:
- For "size_mb": unsigned integer
- For "quota_policy": "static" or "dynamic"
- For "tags": array of Strings
- For "delete_lock": boolean
Update Volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Attach Volume by UUID
Attach a volume by UUID to an instance so that the volume is mounted when
the instance starts. The volume needs to be in available state and the
instance must be in stopped state.
path Parameters
uuidThe UUID of the volume to attach.
Attach Volume by UUID › Request Body
UUID or name of the instance to attach the volume to.
at^/(?!.*\.\./|.*\.$|.… · requiredPath of the mountpoint.
The path must be absolute, not contain . and .. components, and not
contain colons (:). The path must point to an empty directory. If the
directory does not exist, it is created.
readonlyWhether the volume should be mounted read-only.
Attach Volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Clone Volume by UUID
Clone a volume given by its UUID. The volume to be cloned must not be mounted to any instance or only mounted as read-only. It also needs to not be busy or in an error state. This operation is most useful when cloning template volumes.
path Parameters
uuidThe UUID of the volume to clone.
Clone Volume by UUID › Request Body
vol_nameThe name of the new cloned volume. If not provided, a random name
of the form vol-X is generated for you, where X is a 5 character
long random alphanumeric suffix.
quota_policyThe quota policy for the new cloned volume. If not provided, the quota policy of the source volume is used.
tagsA list of tags to assign to the new cloned volume.
Clone Volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Detach Volume by UUID
Detach a volume by UUID from instances. If no particular instance is specified the volume is detached from all instances. The instances from which to detach must not have the volume mounted. The API returns an error for each instance from which it was unable to detach the volume. If the volume has been created together with an instance, detaching the volume will make it persistent (i.e., it survives the deletion of the instance).
path Parameters
uuidThe UUID of the volume to detach.
Detach Volume by UUID › Request Body
UUID or name of the instance to detach the volume from.
Detach Volume by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.