block_volumes

Creates, updates, deletes, gets or lists a block_volumes resource.

Overview

Name	`block_volumes`
Type	Resource
Id	`ovh.public_cloud_storage.block_volumes`

Fields

The following fields are returned by SELECT queries:

get
list

successful operation

Name	Datatype	Description
`id`	`string (uuid)`	Unique identifier of the volume
`checksum`	`string`	Computed hash representing the current target specification value
`created_at`	`string (date-time)`	Creation date of the volume (wire: createdAt)
`current_state`	`object`	Current observed state of the volume from the infrastructure (wire: currentState)
`current_tasks`	`array`	Ongoing asynchronous tasks related to the volume (wire: currentTasks)
`resource_status`	`string`	Volume readiness in the system (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus)
`target_spec`	`object`	Last target specification of the volume (wire: targetSpec)
`updated_at`	`string (date-time)`	Last update date of the volume (wire: updatedAt)

A Public Cloud block storage volume

Name	Datatype	Description
`id`	`string (uuid)`	Unique identifier of the volume
`checksum`	`string`	Computed hash representing the current target specification value
`created_at`	`string (date-time)`	Creation date of the volume (wire: createdAt)
`current_state`	`object`	Current observed state of the volume from the infrastructure (wire: currentState)
`current_tasks`	`array`	Ongoing asynchronous tasks related to the volume (wire: currentTasks)
`resource_status`	`string`	Volume readiness in the system (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus)
`target_spec`	`object`	Last target specification of the volume (wire: targetSpec)
`updated_at`	`string (date-time)`	Last update date of the volume (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`id`, `project_id`		Returns the volume configuration and its current state, including the instances it is attached to.
`list`	`select`	`project_id`	`x_pagination_cursor`, `x_pagination_size`	Returns the volumes of the project.
`create`	`insert`	`project_id`, `target_spec`		Creates a volume, blank or from a backup, a snapshot or an image. `volumeType` is required for a blank volume or one created from an image. The source and the encryption can only be set at creation.
`update`	`update`	`id`, `project_id`, `target_spec`		Replaces the volume's target specification as a whole. The body carries the complete desired state of every field `publicCloud.blockStorage.BlockUpdateTargetSpec` exposes (`name`, `size` and `volumeType`), so read the volume first and restate every value you want to keep: a field left out of `targetSpec` is cleared, not carried over from the stored specification.<br /><br />The create-only fields `location`, `encryption` and `createFrom` cannot be changed once the volume exists. They are deliberately absent from the update model, and sending one is rejected with a 400.<br /><br />`name` and `size` are both required. `size` can only grow: restate the volume's current size to keep it, or send a larger value to extend it, because shrinking a volume is not supported. Leaving `size` out, or sending 0, is rejected with a 400. Restate `volumeType` to keep it. Sending a different type triggers an online retype (migration).<br /><br />The optional `checksum` guards against a lost update: when supplied it must match the volume's current checksum or the request is rejected with a 409 checksum mismatch. Omitting it skips the check and forces the write (last-write-wins).
`delete`	`delete`	`id`, `project_id`		Deletes the volume. An attached volume cannot be deleted: detach it first.
`action`	`exec`	`id`, `project_id`, `type`		Runs an action on the volume. The only action available is `RESTORE_FROM_BACKUP`, which restores the volume from the backup given in `parameters.backupId`.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`api_host`	`string`	The OVHcloud API host. Selected by OVH_ENDPOINT (ovh-eu, ovh-ca or ovh-us; default ovh-eu). (default: api.eu.ovhcloud.com, x-stackQL-envVarSelector: {"envVar":"OVH_ENDPOINT","default":"ovh-eu","values":{"ovh-eu":"api.eu.ovhcloud.com","ovh-ca":"api.ca.ovhcloud.com","ovh-us":"api.us.ovhcloud.com"}})
`id`	`string (uuid)`	Id
`project_id`	`string`	The Public Cloud project ID. Resolved from OVH_CLOUD_PROJECT_SERVICE when set.
`x_pagination_cursor`	`string`	Pagination cursor (wire: X-Pagination-Cursor)
`x_pagination_size`	`integer`	Pagination size (wire: X-Pagination-Size)

`SELECT` examples

get
list

Returns the volume configuration and its current state, including the instances it is attached to.

SELECT
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at
FROM ovh.public_cloud_storage.block_volumes
WHERE id = '{{ id }}' -- required
AND project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Returns the volumes of the project.

SELECT
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at
FROM ovh.public_cloud_storage.block_volumes
WHERE project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
AND x_pagination_cursor = '{{ x_pagination_cursor }}'
AND x_pagination_size = '{{ x_pagination_size }}'
;

`INSERT` examples

create
Manifest

Creates a volume, blank or from a backup, a snapshot or an image. volumeType is required for a blank volume or one created from an image. The source and the encryption can only be set at creation.

INSERT INTO ovh.public_cloud_storage.block_volumes (
target_spec,
project_id
)
SELECT 
'{{ target_spec }}' /* required */,
'{{ project_id }}'
RETURNING
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at
;

# Description fields are for documentation purposes
- name: block_volumes
props:
  - name: project_id
    value: "{{ project_id }}"
    description: Required parameter for the block_volumes resource.
  - name: target_spec
    description: |
      Desired target specification for the volume
    value:
      createFrom:
        backupId: "{{ backupId }}"
        imageId: "{{ imageId }}"
        snapshotId: "{{ snapshotId }}"
      encryption:
        enabled: {{ enabled }}
        kms:
          domainId: "{{ domainId }}"
          serviceKeyId: "{{ serviceKeyId }}"
      location:
        availabilityZone: "{{ availabilityZone }}"
        region: "{{ region }}"
      name: "{{ name }}"
      size: {{ size }}
      volumeType: "{{ volumeType }}"

`UPDATE` examples

update

Replaces the volume's target specification as a whole. The body carries the complete desired state of every field publicCloud.blockStorage.BlockUpdateTargetSpec exposes (name, size and volumeType), so read the volume first and restate every value you want to keep: a field left out of targetSpec is cleared, not carried over from the stored specification. The create-only fields location, encryption and createFrom cannot be changed once the volume exists. They are deliberately absent from the update model, and sending one is rejected with a 400. name and size are both required. size can only grow: restate the volume's current size to keep it, or send a larger value to extend it, because shrinking a volume is not supported. Leaving size out, or sending 0, is rejected with a 400. Restate volumeType to keep it. Sending a different type triggers an online retype (migration). The optional checksum guards against a lost update: when supplied it must match the volume's current checksum or the request is rejected with a 409 checksum mismatch. Omitting it skips the check and forces the write (last-write-wins).

UPDATE ovh.public_cloud_storage.block_volumes
SET 
checksum = '{{ checksum }}',
target_spec = '{{ target_spec }}'
WHERE 
id = '{{ id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
AND target_spec = '{{ target_spec }}' --required
RETURNING
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at;

`DELETE` examples

delete

Deletes the volume. An attached volume cannot be deleted: detach it first.

DELETE FROM ovh.public_cloud_storage.block_volumes
WHERE id = '{{ id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Lifecycle Methods

EXEC variables use wire (API) names.

action

Runs an action on the volume. The only action available is RESTORE_FROM_BACKUP, which restores the volume from the backup given in parameters.backupId.

EXEC ovh.public_cloud_storage.block_volumes.action 
@id='{{ id }}' --required, 
@project_id='{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"checksum": "{{ checksum }}", 
"parameters": "{{ parameters }}", 
"type": "{{ type }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​