0f82690ddd
Access rules rules allow API will now take three additional parameters: - lock_visibility: when True, only services, administrators and the same user will be able to see the content of ``access_to`` and access_key. - lock_deletion: when True, the access rule will be locked for deletion. Only services, administrators or the user that placed the lock will be able to drop the access rule. - lock_reason: a reason for the lock. This parameter should only be provided in the presence of at least one of the former parameters. In order to delete an access rule that is currently locked, the requester will need to specify ``unrestrict=True`` in the request. In case a service placed the restrictions, only the own service or the system administrator will be able to release it. This change also implements filters to the access list API. It is now possible to filter access rules based on `access_to`, `access_type`, `access_level` and `access_key`. DocImpact Change-Id: Iea422c9d6bc99a81cd88c5f4b7055d6a1cf97fdc
611 lines
12 KiB
ReStructuredText
611 lines
12 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
.. _get-access-rules-before-2-45:
|
|
|
|
Share actions
|
|
=============
|
|
|
|
Share actions include granting or revoking share access, listing the
|
|
available access rules for a share, explicitly updating the state of a
|
|
share, resizing a share and un-managing a share.
|
|
|
|
As administrator, you can reset the state of a share and force-
|
|
delete a share in any state. Use the ``policy.yaml`` file to grant
|
|
permissions for this action to other roles.
|
|
|
|
You can set the state of a share to one of these supported states:
|
|
|
|
- ``available``
|
|
|
|
- ``error``
|
|
|
|
- ``creating``
|
|
|
|
- ``deleting``
|
|
|
|
- ``error_deleting``
|
|
|
|
If API version 1.0-2.6 is used then all share actions, defined
|
|
below, should include prefix ``os-`` in top element of request
|
|
JSON's body.
|
|
|
|
For example: {"access_list": null} is valid for v2.7+. And {"os-
|
|
access_list": null} is valid for v1.0-2.6
|
|
|
|
|
|
Grant access
|
|
~~~~~~~~~~~~
|
|
|
|
All manila shares begin with no access. Clients must be provided with
|
|
explicit access via this API.
|
|
|
|
To grant access, specify one of these supported share access levels:
|
|
|
|
- ``rw``. Read and write (RW) access.
|
|
|
|
- ``ro``. Read-only (RO) access.
|
|
|
|
You must also specify one of these supported authentication
|
|
methods:
|
|
|
|
- ``ip``. Authenticates an instance through its IP address.
|
|
The value specified should be a valid IPv4 or an IPv6 address,
|
|
or a subnet in CIDR notation.
|
|
A valid format is ``X:X:X:X:X:X:X:X``, ``X:X:X:X:X:X:X:X/XX``,
|
|
``XX.XX.XX.XX``, or ``XX.XX.XX.XX/XX``, etc. For
|
|
example ``0.0.0.0/0`` or ``::/0``.
|
|
|
|
.. important::
|
|
|
|
IPv6 based access is only supported with API version 2.38 and beyond.
|
|
|
|
.. note::
|
|
Starting from API version 2.82, it is possible to lock the deletion,
|
|
restrict the visibility of sensible fields of the access rules, and specify a
|
|
reason for such locks while invoking the grant access API through the
|
|
parameters ``lock_deletion``, ``lock_visibility`` and ``lock_reason``
|
|
respectively.
|
|
|
|
- ``cert``. Authenticates an instance through a TLS certificate.
|
|
Specify the TLS identity as the IDENTKEY. A valid value is any
|
|
string up to 64 characters long in the common name (CN) of the
|
|
certificate. The meaning of a string depends on its
|
|
interpretation.
|
|
|
|
- ``user``. Authenticates by a user or group name. A valid value is
|
|
an alphanumeric string that can contain some special characters
|
|
and is from 4 to 255 characters long.
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
Grants access to a share.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 202
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- share_id: share_id
|
|
- allow_access: allow_access
|
|
- access_level: access_level
|
|
- access_type: access_type
|
|
- access_to: access_to
|
|
- metadata: access_metadata_grant_access
|
|
- lock_visibility: lock_visibility
|
|
- lock_deletion: lock_deletion
|
|
- lock_reason: resource_lock_lock_reason
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-grant-access-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_id: access_share_id
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- access_type: access_type
|
|
- access_to: access_to
|
|
- access_key: access_key
|
|
- access: access
|
|
- access_level: access_level
|
|
- id: access_rule_id
|
|
- metadata: access_metadata
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-actions-grant-access-response.json
|
|
:language: javascript
|
|
|
|
|
|
Revoke access
|
|
~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
The shared file systems service stores each access rule in its database and
|
|
assigns it a unique ID. This ID can be used to revoke access after access
|
|
has been requested.
|
|
|
|
.. note::
|
|
In case the access rule had its deletion locked, it will be necessary to
|
|
provide the ``unrestrict`` parameter in the revoke access request.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 202
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- share_id: share_id
|
|
- deny_access: deny_access
|
|
- access_id: access_id
|
|
- unrestrict: unrestrict_access
|
|
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-revoke-access-request.json
|
|
:language: javascript
|
|
|
|
|
|
List access rules (DEPRECATED)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. warning::
|
|
|
|
This API is deprecated starting with microversion 2.45 and requests to
|
|
this API will fail with a 404 starting from microversion 2.45. Use
|
|
:ref:`List share access rules <get-access-rules-after-2-45>` API
|
|
instead of this API from version 2.45.
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
Lists access rules for a share. The Access ID returned is necessary to deny
|
|
access.
|
|
|
|
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_id: share_id
|
|
- access_list: access_list
|
|
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-list-access-rules-request.json
|
|
:language: javascript
|
|
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- access_type: access_type
|
|
- access_key: access_key
|
|
- access_to: access_to
|
|
- access_level: access_level
|
|
- state: state
|
|
- access_list: access_list
|
|
- id: access_rule_id
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-actions-list-access-rules-response.json
|
|
:language: javascript
|
|
|
|
|
|
Reset share state
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
Administrator only. Explicitly updates the state of a share.
|
|
|
|
Use the ``policy.yaml`` 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
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- share_id: share_id
|
|
- reset_status: reset_status
|
|
- status: share_status_request
|
|
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-reset-state-request.json
|
|
:language: javascript
|
|
|
|
|
|
Force-delete share
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
Administrator only. Force-deletes a share in any state.
|
|
|
|
Use the ``policy.yaml`` 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
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- share_id: share_id
|
|
- force_delete: share_force_delete
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-force-delete-request.json
|
|
:language: javascript
|
|
|
|
|
|
Extend share
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
Increases the size of a share.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 202
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- share_id: share_id
|
|
- extend: extend
|
|
- new_size: share_new_size
|
|
- force: share_force_extend
|
|
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-extend-request.json
|
|
:language: javascript
|
|
|
|
|
|
Shrink share
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
Shrinks the size of a share.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 202
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- share_id: share_id
|
|
- shrink: shrink
|
|
- new_size: share_new_size
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-shrink-request.json
|
|
:language: javascript
|
|
|
|
|
|
Unmanage share (since API v2.7)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
.. versionadded:: 2.7
|
|
|
|
|
|
Use this API to remove a share from the management of the Shared File
|
|
Systems service without deleting the share.
|
|
|
|
Administrator only. Use the ``policy.yaml`` file to grant permissions for this
|
|
action to other roles.
|
|
|
|
|
|
Preconditions:
|
|
|
|
- You should remove any snapshots and share replicas before attempting to
|
|
unmanage a share.
|
|
|
|
.. note::
|
|
|
|
Unmanaging shares that are created on top of share servers (i.e. created
|
|
with share networks) is not supported prior to API version 2.49.
|
|
|
|
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_id: share_id
|
|
- unmanage: share_unmanage
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-unmanage-request.json
|
|
:language: javascript
|
|
|
|
|
|
Response parameters
|
|
-------------------
|
|
There is no body content for the response.
|
|
|
|
|
|
Revert share to snapshot (since API v2.27)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
.. versionadded:: 2.27
|
|
|
|
Reverts a share to the specified snapshot, which must be the most recent one
|
|
known to manila.
|
|
|
|
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_id: share_id
|
|
- snapshot_id: snapshot_id
|
|
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-revert-to-snapshot-request.json
|
|
:language: javascript
|
|
|
|
|
|
Soft delete share (since API v2.69)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
.. versionadded:: 2.69
|
|
|
|
Soft delete a share to recycle bin.
|
|
|
|
Preconditions
|
|
|
|
- Share status must be ``available``, ``error`` or ``inactive``
|
|
|
|
- Share can't have any snapshot.
|
|
|
|
- Share can't have a share group snapshot.
|
|
|
|
- Share can't have dependent replicas.
|
|
|
|
- You cannot soft delete share that already is in the Recycle Bin..
|
|
|
|
- You cannot soft delete a share that doesn't belong to your project.
|
|
|
|
- You cannot soft delete a share is busy with an active task.
|
|
|
|
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_id: share_id
|
|
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-soft-delete-request.json
|
|
:language: javascript
|
|
|
|
|
|
Restore share (since API v2.69)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/shares/{share_id}/action
|
|
|
|
.. versionadded:: 2.69
|
|
|
|
Restore a share from recycle bin.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 202
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- share_id: share_id
|
|
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-actions-restore-request.json
|
|
:language: javascript
|