3e86e3deac
The API Documentation team has requires [1] that projects maintain their api-reference in-tree and build it to the developer.openstack.org website. This version of the API reference uses os-api-ref and compiles API documentation close to that of the OpenStack compute service (nova). Co-Authored-By: Goutham Pacha Ravi <gouthamr@netapp.com> [0] http://lists.openstack.org/pipermail/openstack-dev/2016-May/093765.html Implements: bp move-manila-api-reference-in-tree Change-Id: I67bb3354162d6e0e00fa2788edde864cc14920ee
510 lines
14 KiB
ReStructuredText
510 lines
14 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
======
|
|
Shares
|
|
======
|
|
|
|
A share is a remote, mountable file system. You can mount a share
|
|
to and access a share from several hosts by several users at a
|
|
time.
|
|
|
|
You can create a share and associate it with a network, list
|
|
shares, and show information for, update, and delete a share.
|
|
|
|
To create a share, specify one of these supported protocols:
|
|
|
|
- ``NFS``. Network File System (NFS).
|
|
|
|
- ``CIFS``. Common Internet File System (CIFS).
|
|
|
|
- ``GLUSTERFS``. Gluster file system (GlusterFS).
|
|
|
|
- ``HDFS``. Hadoop Distributed File System (HDFS).
|
|
|
|
- ``CEPHFS``. Ceph File System (CephFS).
|
|
|
|
You can also create snapshots of shares. To create a snapshot, you
|
|
specify the ID of the share that you want to snapshot.
|
|
|
|
A share has one of these status values:
|
|
|
|
**Share statuses**
|
|
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| Status | Description |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``creating`` | The share is being created. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``deleting`` | The share is being deleted. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``error`` | An error occurred during share creation. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``error_deleting`` | An error occurred during share deletion. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``available`` | The share is ready to use. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``manage_starting`` | Share manage started. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``manage_error`` | Share manage failed. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``unmanage_starting`` | Share unmanage started. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``unmanage_error`` | Share cannot be unmanaged. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``unmanaged`` | Share was unmanaged. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``extending`` | The extend, or increase, share size request was issued |
|
|
| | successfully. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``extending_error`` | Extend share failed. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``shrinking`` | Share is being shrunk. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``shrinking_error`` | Failed to update quota on share shrinking. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
| ``shrinking_possible_data_loss_error`` | Shrink share failed due to possible data loss. |
|
|
+----------------------------------------+--------------------------------------------------------+
|
|
|
|
|
|
List shares
|
|
===========
|
|
|
|
.. rest_method:: GET /v2/{tenant_id}/shares
|
|
|
|
Lists all shares.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- all_tenants: all_tenants
|
|
- name: name_5
|
|
- status: status_6
|
|
- share_server_id: share_server_id
|
|
- metadata: metadata
|
|
- extra_specs: extra_specs
|
|
- share_type_id: share_type_id
|
|
- limit: limit
|
|
- offset: offset
|
|
- sort_key: sort_key
|
|
- sort_dir: sort_dir
|
|
- snapshot_id: snapshot_id_2
|
|
- host: host_1
|
|
- share_network_id: share_network_id
|
|
- project_id: project_id_6
|
|
- is_public: is_public
|
|
- consistency_group_id: consistency_group_id_6
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_4
|
|
- links: links
|
|
- name: name
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/shares-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
List shares with details
|
|
========================
|
|
|
|
.. rest_method:: GET /v2/{tenant_id}/shares/detail
|
|
|
|
Lists all shares, with details.
|
|
|
|
Normal response codes: 202
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- all_tenants: all_tenants
|
|
- name: name_5
|
|
- status: status_6
|
|
- share_server_id: share_server_id
|
|
- metadata: metadata
|
|
- extra_specs: extra_specs
|
|
- share_type_id: share_type_id
|
|
- limit: limit
|
|
- offset: offset
|
|
- sort_key: sort_key
|
|
- sort_dir: sort_dir
|
|
- snapshot_id: snapshot_id_2
|
|
- host: host_1
|
|
- share_network_id: share_network_id
|
|
- project_id: project_id_6
|
|
- is_public: is_public
|
|
- consistency_group_id: consistency_group_id_6
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_type_name: share_type_name
|
|
- links: links
|
|
- availability_zone: availability_zone
|
|
- share_network_id: share_network_id
|
|
- export_locations: export_locations
|
|
- share_server_id: share_server_id
|
|
- snapshot_id: snapshot_id_3
|
|
- id: id_4
|
|
- size: size_2
|
|
- share_type: share_type_1
|
|
- export_location: export_location
|
|
- consistency_group_id: consistency_group_id_3
|
|
- project_id: project_id_4
|
|
- metadata: metadata
|
|
- status: status
|
|
- description: description_5
|
|
- host: host_1
|
|
- access_rules_status: access_rules_status
|
|
- is_public: is_public
|
|
- task_state: task_state
|
|
- snapshot_support: snapshot_support
|
|
- name: name_5
|
|
- has_replicas: has_replicas
|
|
- replication_type: replication_type
|
|
- created_at: created_at_4
|
|
- share_proto: share_proto
|
|
- volume_type: volume_type
|
|
- source_cgsnapshot_member_id: source_cgsnapshot_member_id
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/shares-list-detailed-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show share details
|
|
==================
|
|
|
|
.. rest_method:: GET /v2/{tenant_id}/shares/{share_id}
|
|
|
|
Shows details for a share.
|
|
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_id: share_id_4
|
|
- tenant_id: tenant_id_1
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_type_name: share_type_name
|
|
- links: links
|
|
- availability_zone: availability_zone_1
|
|
- share_network_id: share_network_id
|
|
- export_locations: export_locations
|
|
- share_server_id: share_server_id
|
|
- snapshot_id: snapshot_id_3
|
|
- id: id_4
|
|
- size: size_2
|
|
- share_type: share_type_1
|
|
- export_location: export_location
|
|
- consistency_group_id: consistency_group_id_6
|
|
- project_id: project_id_4
|
|
- metadata: metadata
|
|
- status: status_16
|
|
- description: description_5
|
|
- host: host_9
|
|
- access_rules_status: access_rules_status
|
|
- is_public: is_public
|
|
- task_state: task_state
|
|
- snapshot_support: snapshot_support
|
|
- name: name_5
|
|
- has_replicas: has_replicas
|
|
- replication_type: replication_type
|
|
- created_at: created_at_4
|
|
- share_proto: share_proto
|
|
- volume_type: volume_type
|
|
- source_cgsnapshot_member_id: source_cgsnapshot_member_id
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-show-response.json
|
|
:language: javascript
|
|
|
|
|
|
Create share
|
|
============
|
|
|
|
.. rest_method:: POST /v2/{tenant_id}/shares
|
|
|
|
Creates a share.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), conflict(409), unprocessableEntity(422)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- share_proto: share_proto
|
|
- size: size
|
|
- name: name_5
|
|
- description: description_5
|
|
- display_name: display_name
|
|
- display_description: display_description
|
|
- share_type: share_type
|
|
- volume_type: volume_type
|
|
- snapshot_id: snapshot_id
|
|
- is_public: is_public
|
|
- metadata: metadata
|
|
- share_network_id: share_network_id_2
|
|
- consistency_group_id: consistency_group_id_1
|
|
- availability_zone: availability_zone
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-create-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_4
|
|
- status: status_3
|
|
- links: links
|
|
- project_id: project_id_6
|
|
- share_proto: share_proto
|
|
- size: size
|
|
- name: name_5
|
|
- description: description_5
|
|
- display_name: display_name
|
|
- display_description: display_description
|
|
- share_type: share_type_1
|
|
- share_type_name: share_type_name
|
|
- has_replicas: has_replicas
|
|
- replication_type: replication_type
|
|
- volume_type: volume_type
|
|
- snapshot_id: snapshot_id
|
|
- is_public: is_public
|
|
- metadata: metadata
|
|
- share_network_id: share_network_id
|
|
- availability_zone: availability_zone_1
|
|
- export_location: export_location
|
|
- export_locations: export_locations
|
|
- host: host_1
|
|
- task_state: task_state
|
|
- share_server_id: share_server_id
|
|
- consistency_group_id: consistency_group_id_6
|
|
- snapshot_support: snapshot_support
|
|
- source_cgsnapshot_member_id: source_cgsnapshot_member_id
|
|
- created_at: created_at_4
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-create-response.json
|
|
:language: javascript
|
|
|
|
|
|
Manage share
|
|
============
|
|
|
|
.. rest_method:: GET /v2/{tenant_id}/shares/manage
|
|
|
|
Configures Shared File Systems to manage a share.
|
|
This API is available for API versions later than or equal to 2.7
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), conflict(409), unprocessableEntity(422)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- share: share
|
|
- protocol: protocol
|
|
- name: name_5
|
|
- share_type: share_type_2
|
|
- driver_options: driver_options
|
|
- export_path: export_path
|
|
- service_host: service_host
|
|
- is_public: is_public
|
|
- description: description_5
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-manage-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share: share
|
|
- links: links
|
|
- availability_zone: availability_zone_1
|
|
- share_network_id: share_network_id
|
|
- export_locations: export_locations
|
|
- share_server_id: share_server_id
|
|
- snapshot_id: snapshot_id_3
|
|
- id: id_4
|
|
- size: size_2
|
|
- share_type: share_type_1
|
|
- share_type_name: share_type_name
|
|
- has_replicas: has_replicas
|
|
- replication_type: replication_type
|
|
- export_location: export_location
|
|
- consistency_group_id: consistency_group_id_6
|
|
- project_id: project_id_4
|
|
- metadata: metadata
|
|
- status: status_8
|
|
- description: description_5
|
|
- host: host_9
|
|
- is_public: is_public
|
|
- snapshot_support: snapshot_support
|
|
- name: name_5
|
|
- created_at: created_at_4
|
|
- share_proto: share_proto
|
|
- volume_type: volume_type
|
|
- source_cgsnapshot_member_id: source_cgsnapshot_member_id
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-manage-response.json
|
|
:language: javascript
|
|
|
|
|
|
Update share
|
|
============
|
|
|
|
.. rest_method:: PUT /v2/{tenant_id}/shares/{share_id}
|
|
|
|
Updates a share.
|
|
|
|
You can update these attributes:
|
|
|
|
- ``display_name``, which also changes the ``name`` of the share.
|
|
|
|
- ``display_description``, which also changes the ``description`` of
|
|
the share.
|
|
|
|
- ``is_public``. Changes the level of visibility.
|
|
|
|
If you try to update other attributes, they retain their previous
|
|
values.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), unprocessableEntity(422)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- is_public: is_public
|
|
- display_name: display_name_3
|
|
- display_description: display_description_3
|
|
- share_id: share_id_4
|
|
- tenant_id: tenant_id_1
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-update-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_type_name: share_type_name
|
|
- links: links
|
|
- availability_zone: availability_zone_1
|
|
- share_network_id: share_network_id
|
|
- export_locations: export_locations
|
|
- share_server_id: share_server_id
|
|
- snapshot_id: snapshot_id_3
|
|
- id: id_4
|
|
- size: size_2
|
|
- share_type: share_type_1
|
|
- export_location: export_location
|
|
- consistency_group_id: consistency_group_id_6
|
|
- project_id: project_id_4
|
|
- metadata: metadata
|
|
- status: status_16
|
|
- description: description_5
|
|
- host: host_9
|
|
- access_rules_status: access_rules_status
|
|
- is_public: is_public
|
|
- task_state: task_state
|
|
- snapshot_support: snapshot_support
|
|
- name: name_5
|
|
- has_replicas: has_replicas
|
|
- replication_type: replication_type
|
|
- created_at: created_at_4
|
|
- share_proto: share_proto
|
|
- volume_type: volume_type
|
|
- source_cgsnapshot_member_id: source_cgsnapshot_member_id
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-update-response.json
|
|
:language: javascript
|
|
|
|
|
|
Delete share
|
|
============
|
|
|
|
.. rest_method:: DELETE /v2/{tenant_id}/shares/{share_id}
|
|
|
|
Deletes a share.
|
|
|
|
Normal response codes: 202
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_id: share_id
|
|
- tenant_id: tenant_id_1
|
|
- consistency_group_id: consistency_group_id_3
|