openstack/manila
Code Issues Proposed changes
0ed8c74dc4
manila/api-ref/source/share-servers.inc
Goutham Pacha Ravi f185ff0f44 [api-ref] De-duplicate date and time parameters 
Many APIs present information when the resource
in question was 'created_at' and 'updated_at'.

Having common parameters is easier to maintain in
the documentation since the description is the same
across the board.

Change-Id: Ia5d4ac399fe0d7983c61f5c5e0245d0987e97d6a
Partial-Bug: #1760644
2019-04-04 15:59:32 +00:00

383 lines
8.4 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
=============
Share servers
=============
A share server is created by multi-tenant back-end drivers where
shares are hosted. For example, with the ``generic`` driver, shares
are hosted on Compute VMs.
Administrators can perform read and delete actions for share
servers. An administrator can delete an active share server only if
it contains no dependent shares. If an administrator deletes the
share server, the Shared File Systems service creates a share
server in response to a subsequent create share request.
An administrator can use the ``policy.json`` file to grant
permissions for share server actions to other roles.
The status of a share server indicates its current state. After you
successfully set up a share server, its status is ``active``. If
errors occur during set up such as when server data is not valid,
its status is ``error``.
The possible share servers statuses are:
**Share server statuses**
+--------------+------------------------------------------------------------------+
| Status | Description |
+--------------+------------------------------------------------------------------+
| ``active`` | Share server was successfully set up. |
+--------------+------------------------------------------------------------------+
| ``error`` | The set up or deletion of the share server failed. |
+--------------+------------------------------------------------------------------+
| ``deleting`` | The share server has no dependent shares and is being deleted. |
+--------------+------------------------------------------------------------------+
| ``creating`` | The share server is being created on the back end with data from |
| | the database. |
+--------------+------------------------------------------------------------------+
List share servers
==================
.. rest_method:: GET /v2/{project_id}/share-servers
Lists all share servers.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_server_id
- project_id: project_id
- status: status_share_server_body
- share_network_id: share_network_id
- share_network_name: share_network_name
- host: host_share_server_body
- updated_at: updated_at
Response example
----------------
.. literalinclude:: samples/share-servers-list-response.json
:language: javascript
Show share server
=================
.. rest_method:: GET /v2/{project_id}/share-servers/{share_server_id}
Show a share server's details.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_server_id: share_server_id
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_server_id
- project_id: project_id
- status: status_share_server_body
- backend_details: backend_details
- share_network_id: share_network_id_share_server_body
- share_network_name: share_network_name
- host: host_share_server_body
- created_at: created_at
- updated_at: updated_at
- identifier: share_server_show_identifier
- is_auto_deletable: share_server_show_is_auto_deletable
Response example
----------------
.. literalinclude:: samples/share-server-show-response.json
:language: javascript
Show share server back end details
==================================
.. rest_method:: GET /v2/{project_id}/share-servers/{share_server_id}/details
Shows back end details of a share server.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_server_id: share_server_id
Response parameters
-------------------
Response parameters can differ based on the back end used.
Each back end can store any key-value information that it requires.
For example, the generic back end driver might store the router ID.
Response example
----------------
.. literalinclude:: samples/share-server-show-details-response.json
:language: javascript
Delete share server
===================
.. rest_method:: DELETE /v2/{project_id}/share-servers/{share_server_id}
Deletes a share server.
An administrator can delete an active share server only if it
contains no dependent shares.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_server_id: share_server_id
Manage share server (since API v2.49)
=====================================
.. rest_method:: POST /v2/{project_id}/share-servers/manage
.. versionadded:: 2.49
Manages a share server
An administrator can bring a pre-existing share server if the back end driver
is operating in ``driver_handles_share_servers=True`` mode.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 403
- 422
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- host: manage_host
- identifier: identifier
- share_network: share_network_id
- driver_options: driver_options
Request example
---------------
.. literalinclude:: samples/share-server-manage-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_server_id
- project_id: project_id
- updated_at: updated_at
- status: share_server_status
- host: manage_host
- share_network_name: share_network_name
- share_network_id: share_network_id
- created_at: created_at
- backend_details: backend_details
- is_auto_deletable: is_auto_deletable
- identifier: identifier
Response examples
-----------------
.. literalinclude:: samples/share-server-manage-response.json
:language: javascript
Unmanage share server (since API v2.49)
=======================================
.. rest_method:: POST /v2/{project_id}/share-servers/{share_server_id}/action
.. versionadded:: 2.49
Unmanages a share server
An administrator can remove a share server from the Shared File System
service's management if there are no associated shares that the service is
aware of. The share server will not be torn down in the back end.
Preconditions
- Share server status must be either ``error``, ``manage_error``, ``active`` or
``unmanage_error``.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 404
Request parameters
------------------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_server_id: share_server_id
- force: force
- unmanage: share_server_unmanage
Request example
---------------
.. literalinclude:: samples/share-server-unmanage-request.json
:language: javascript
Response parameters
-------------------
There is no body content for the response.
Reset status (since API v2.49)
==============================
.. rest_method:: POST /v2/{project_id}/share-servers/{share_server_id}/action
.. versionadded:: 2.49
Resets a share server status
Administrator only. Explicitly updates the state of a share server.
Use the ``policy.json`` file to grant permissions for this action to other
roles.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 404
Request parameters
------------------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_server_id: share_server_id
- status: share_server_status
Request example
---------------
.. literalinclude:: samples/share-server-reset-state-request.json
:language: javascript
Response parameters
-------------------
There is no body content for the response.
View Git Blame Copy Permalink