.. -*- 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
