file_shares

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

Overview

Name	file_shares
Type	Resource
Id	ovh.public_cloud_storage.file_shares

Fields

The following fields are returned by SELECT queries:

get

successful operation

Name	Datatype	Description
id	string (uuid)	Unique identifier of the file storage
checksum	string	Computed hash representing the current target specification value
created_at	string (date-time)	Creation date of the file storage (wire: createdAt)
current_state	object	Current observed state of the file storage from the infrastructure (wire: currentState)
current_tasks	array	Ongoing asynchronous tasks related to the file storage (wire: currentTasks)
resource_status	string	File storage 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 file storage (wire: targetSpec)
updated_at	string (date-time)	Last update date of the file storage (wire: updatedAt)

list

A Public Cloud file storage (NFS share)

Name	Datatype	Description
id	string (uuid)	Unique identifier of the file storage
checksum	string	Computed hash representing the current target specification value
created_at	string (date-time)	Creation date of the file storage (wire: createdAt)
current_state	object	Current observed state of the file storage from the infrastructure (wire: currentState)
current_tasks	array	Ongoing asynchronous tasks related to the file storage (wire: currentTasks)
resource_status	string	File storage 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 file storage (wire: targetSpec)
updated_at	string (date-time)	Last update date of the file storage (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	file_storage_id, project_id		Returns the file storage configuration and its current state, including the NFS export paths to mount it.
list	select	project_id	x_pagination_cursor, x_pagination_size	Returns the file storages of the project.
create	insert	project_id, target_spec		Creates a file storage, either empty or from a snapshot.<br /><br />Without createFrom, shareType, shareNetwork and size are required.<br /><br />With createFrom.snapshotId, the file storage is created from that snapshot, which must belong to the same project and be in the region set in location.region. An unknown snapshot is rejected with a 404. The snapshot must be available: a snapshot in any other status is rejected with a 409. shareType and encryption are the values of the snapshot's source file storage and are returned in targetSpec: requesting encryption.enabled true from a snapshot of an unencrypted file storage is rejected as an invalid parameter, and requesting encryption.enabled false from a snapshot of an encrypted file storage is ignored. size is optional: when omitted, the snapshot's size is used and returned in targetSpec, and a size smaller than the snapshot's size is rejected. shareNetwork is optional: when omitted, the share network of the snapshot's source file storage is used and returned in targetSpec, and a different share network is rejected.<br /><br />createFrom is set at creation only and cannot be changed afterward.
update	update	file_storage_id, project_id, target_spec		Replaces the file storage's target specification as a whole. The body carries the complete desired state of every field publicCloud.storage.file.FileStorageUpdateTargetSpec exposes (description, name and size), so read the file storage first and restate every value you want to keep: a field left out of targetSpec is cleared, not carried over from the stored specification. Leaving description out clears the description.<br /><br />The create-only fields protocol, shareType, shareNetwork, location, encryption and createFrom cannot be changed once the file storage 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 current size to keep it, or send a larger value to extend the file storage, because shrinking one is not supported.<br /><br />The optional checksum guards against a lost update: when supplied it must match the file storage'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	file_storage_id, project_id		Deletes the file storage. A file storage that still has snapshots cannot be deleted: delete them first.

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"}})
file_storage_id	string (uuid)	File storage ID (wire: fileStorageId)
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

Returns the file storage configuration and its current state, including the NFS export paths to mount it.

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

list

Returns the file storages of the project.

SELECT
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at
FROM ovh.public_cloud_storage.file_shares
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

Creates a file storage, either empty or from a snapshot.<br /><br />Without createFrom, shareType, shareNetwork and size are required.<br /><br />With createFrom.snapshotId, the file storage is created from that snapshot, which must belong to the same project and be in the region set in location.region. An unknown snapshot is rejected with a 404. The snapshot must be available: a snapshot in any other status is rejected with a 409. shareType and encryption are the values of the snapshot's source file storage and are returned in targetSpec: requesting encryption.enabled true from a snapshot of an unencrypted file storage is rejected as an invalid parameter, and requesting encryption.enabled false from a snapshot of an encrypted file storage is ignored. size is optional: when omitted, the snapshot's size is used and returned in targetSpec, and a size smaller than the snapshot's size is rejected. shareNetwork is optional: when omitted, the share network of the snapshot's source file storage is used and returned in targetSpec, and a different share network is rejected.<br /><br />createFrom is set at creation only and cannot be changed afterward.

INSERT INTO ovh.public_cloud_storage.file_shares (
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
;

Manifest

# Description fields are for documentation purposes
- name: file_shares
props:
  - name: project_id
    value: "{{ project_id }}"
    description: Required parameter for the file_shares resource.
  - name: target_spec
    description: |
      Desired target specification for the file storage
    value:
      createFrom:
        snapshotId: "{{ snapshotId }}"
      description: "{{ description }}"
      encryption:
        enabled: {{ enabled }}
      location:
        availabilityZone: "{{ availabilityZone }}"
        region: "{{ region }}"
      name: "{{ name }}"
      protocol: "{{ protocol }}"
      shareNetwork:
        id: "{{ id }}"
      shareType: "{{ shareType }}"
      size: {{ size }}

UPDATE examples

update

Replaces the file storage's target specification as a whole. The body carries the complete desired state of every field publicCloud.storage.file.FileStorageUpdateTargetSpec exposes (description, name and size), so read the file storage first and restate every value you want to keep: a field left out of targetSpec is cleared, not carried over from the stored specification. Leaving description out clears the description.<br /><br />The create-only fields protocol, shareType, shareNetwork, location, encryption and createFrom cannot be changed once the file storage 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 current size to keep it, or send a larger value to extend the file storage, because shrinking one is not supported.<br /><br />The optional checksum guards against a lost update: when supplied it must match the file storage'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.file_shares
SET 
checksum = '{{ checksum }}',
target_spec = '{{ target_spec }}'
WHERE 
file_storage_id = '{{ file_storage_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 file storage. A file storage that still has snapshots cannot be deleted: delete them first.

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