Enhance quota documentation

These doc enhancements still use the "manila"
CLI/shell utility. It makes it easier to
backport to older branches. A future commit
will update all documentation to use OSC.

Change-Id: I18c4ac2d4134314da9df0d3e0b7d45acafce2b22
Closes-Bug: #1941057
Signed-off-by: Goutham Pacha Ravi <gouthampravi@gmail.com>

doc/source/admin/index.rst

@@ -46,6 +46,7 @@ deployment.
    shared-file-systems-key-concepts.rst
    shared-file-systems-share-management.rst
    shared-file-systems-share-types.rst
+   shared-file-systems-quotas.rst
    shared-file-systems-share-group-types.rst
    shared-file-systems-share-groups.rst
    shared-file-systems-snapshots.rst

doc/source/admin/shared-file-systems-quotas.rst

@@ -4,15 +4,20 @@
 Quotas and limits
 =================
 
-Limits
+Limits are usage restrictions imposed on consumers of the Shared File
-~~~~~~
+Systems service (manila). These limits can be of two types:
 
-Limits are the resource limitations that are allowed for each project.
+* Limits on resource consumption (also referred to as ``quotas``)
-An administrator can configure limits in the ``manila.conf`` file.
+* Limits on usage of APIs (also referred to as ``rate-limits``)
 
-Users can query their rate and absolute limits.
+Administrators can setup and manipulate these limits at any point of time.
+Users can query their rate limits and quotas. If an administrator does
+not set up limits explicitly, the service does not impose any rate limits
+but it enforces default resource limits (also referred to as ``default
+quotas``).
 
-To see the absolute limits, run:
+Users can query their absolute limits using the :command:`manila
+absolute-limits` command.
 
 .. code-block:: console
 
@@ -36,16 +41,18 @@ To see the absolute limits, run:
    | totalReplicaGigabytesUsed  | 1     |
    +----------------------------+-------+
 
-Rate limits control the frequency at which users can issue specific API
+API Rate Limits
-requests. Administrators use rate limiting to configure limits on the type and
+~~~~~~~~~~~~~~~
+
+API Rate limits control the frequency at which users can make specific API
+requests. Administrators can use rate limiting on the type and
 number of API calls that can be made in a specific time interval. For example,
 a rate limit can control the number of ``GET`` requests processed
 during a one-minute period.
 
-To set the API rate limits, modify the
+To set API rate limits, copy and modify the ``etc/manila/api-paste.ini`` file.
-``etc/manila/api-paste.ini`` file, which is a part of the WSGI pipeline and
+You need to restart ``manila-api`` service after you edit the ``api-paste.ini``
-defines the actual limits. You need to restart ``manila-api`` service after
+file.
-you edit the ``etc/manila/api-paste.ini`` file.
 
 .. code-block:: ini
 
@@ -71,7 +78,8 @@ the ``[composite:openstack_share_api]`` and
    keystone = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext apiv2
    keystone_nolimit = cors faultwrap ssl sizelimit authtoken keystonecontext apiv2
 
-Finally, set the ``[DEFAULT] api_rate_limit`` parameter to ``True``.
+Finally, set the ``[DEFAULT]/api_rate_limit`` parameter in ``manila.conf`` to
+``True``.
 
 .. code-block:: ini
 
@@ -91,15 +99,83 @@ To see the rate limits, run:
    | PUT    | "*/shares" | 120   | 120    | MINUTE | 2015-10-20T15:17:20Z |
    +--------+------------+-------+--------+--------+----------------------+
 
-Quotas
+Default Resource Quotas
-~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Quota sets provide quota management support.
+It is possible to set limits on the number of ``shares``, ``snapshots``,
+``share-networks``, ``share_groups`` (requires API version 2.40),
+``share_group_snapshots`` (requires API version 2.40) and
+``share_replicas`` (requires API version 2.53). Alongside limits can also be
+set on capacity with ``gigabytes`` (total size of shares allowed),
+``snapshot-gigabytes`` (total size of snapshots allowed),
+``replica_gigabytes`` (requires API version 2.53) or ``per_share_gigabytes``
+(requires API version 2.62).
+
+If these resource quotas are not set by an administrator, default quotas
+that are hardcoded in the service will apply. To view these
+default quotas, the administrator can use the :command:`manila
+quota-defaults` command:
+
+.. code-block:: console
+
+   $ manila quota-defaults
+   +-----------------------+------------------------------------+
+   | Property              | Value                              |
+   +-----------------------+------------------------------------+
+   | id                    | 1cc2154937bd40f4815d5f168d372263   |
+   | gigabytes             | 1000                               |
+   | per_share_gigabytes   | -1                                 |
+   | snapshot_gigabytes    | 1000                               |
+   | snapshots             | 50                                 |
+   | shares                | 50                                 |
+   | share_networks        | 10                                 |
+   | share_groups          | 50                                 |
+   | share_group_snapshots | 50                                 |
+   | share_replicas        | 100                                |
+   | replica_gigabytes     | 1000                               |
+   +-----------------------+------------------------------------+
+
+Administrators can modify default quotas with the :command:`manila
+quota-class-update` command:
+
+.. code-block:: console
+
+    manila quota-class-update default \
+        --shares 30                   \
+        --snapshots 50                \
+        --share-groups 15
+
+
+Alternatively, you can also specify these defaults via the ``manila.conf``.
+The following is an example:
+
+.. code-block:: ini
+
+    [quota]
+    shares = 30
+    share_gigabytes = 10000
+    share_networks = 50
+    share_snapshots = 100
+
+.. important::
+
+    Default quotas specified via the API will always take precedence over
+    any defaults applied via ``manila.conf``. Therefore it is recommended to
+    always use the API when creating or manipulating default quotas.
+
+
+Custom quotas
+~~~~~~~~~~~~~
+
+The administrator can customize quotas for a specific project, or for a
+specific user within a project context, or for a share type used by users of
+a project.
 
 To list the quotas for a project or user, use the :command:`manila quota-show`
 command. If you specify the optional ``--user`` parameter, you get the
 quotas for this user in the specified project. If you omit this parameter,
-you get the quotas for the specified project.
+you get the quotas for the specified project. If there are no overrides, the
+quotas shown will match the defaults.
 
 .. note::
 
@@ -128,49 +204,15 @@ you get the quotas for the specified project.
    | replica_gigabytes     | 1000                              |
    +-----------------------+-----------------------------------+
 
-There are default quotas for a project that are set from the
+These quotas can be updated with the :command:`manila quota-update` command.
-``manila.conf`` file. To list the default quotas for a project, use
-the :command:`manila quota-defaults` command:
-
-.. code-block:: console
-
-   $ manila quota-defaults --tenant %project_id%
-   +-----------------------+------------------------------------+
-   | Property              | Value                              |
-   +-----------------------+------------------------------------+
-   | id                    | 1cc2154937bd40f4815d5f168d372263   |
-   | gigabytes             | 1000                               |
-   | per_share_gigabytes   | -1                                 |
-   | snapshot_gigabytes    | 1000                               |
-   | snapshots             | 50                                 |
-   | shares                | 50                                 |
-   | share_networks        | 10                                 |
-   | share_groups          | 50                                 |
-   | share_group_snapshots | 50                                 |
-   | share_replicas        | 100                                |
-   | replica_gigabytes     | 1000                               |
-   +-----------------------+------------------------------------+
-
-The administrator can update the quotas for a specific project, or for a
-specific user by providing both the ``--tenant`` and ``--user`` optional
-arguments. It is possible to update the ``shares``, ``snapshots``,
-``gigabytes``, ``snapshot-gigabytes``, ``share-networks``, ``share_groups``,
-``share_group_snapshots`` and ``share-type`` quotas.
-
-.. note::
-    Since API version 2.53, the administrator is also able to update quotas
-    for share replicas and replica gigabytes by specifying ``share_replicas``
-    and/or ``replica_gigabytes``.
-    Since API version 2.62, the administrator is also able to update quotas
-    for per share gigabytes by specifying ``per_share_gigabytes``
 
 .. code-block:: console
 
    $ manila quota-update %project_id% --user %user_id% --shares 49 --snapshots 49
 
-As administrator, you can also permit or deny the force-update of a quota that
+The service will prevent the quota being set lower than the current
-is already used, or if the requested value exceeds the configured quota limit.
+consumption. However, a quota update can still be made if necessary with
-To force-update a quota, use ``force`` optional key.
+the``force`` key.
 
 .. code-block:: console
 
@@ -184,15 +226,16 @@ be applied across all users of a particular project.
 
    $ manila quota-update %project_id% --share-type %share_type_id%
 
-To revert quotas to default for a project or for a user, delete quotas:
+To revert quotas to default for a project or for a user, simply delete
+the quota that has been set:
 
 .. code-block:: console
 
    $ manila quota-delete --tenant %project_id% --user-id %user_id%
 
-To revert quotas to default, use the specific project or share type. Share
+Share type quotas can be reverted in the same way. Except, Share Type quotas
-Type quotas can not be reverted for individual users within a project. They
+can not be set for individual users within a project, so they cannot be
-can only be reverted across all users of a particular project.
+unset either.
 
 .. code-block:: console