diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 724fabadec..8bda328984 100644 --- a/doc/source/admin/index.rst +++ b/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 diff --git a/doc/source/admin/shared-file-systems-quotas.rst b/doc/source/admin/shared-file-systems-quotas.rst index 4a0d1f392c..9fc611a45f 100644 --- a/doc/source/admin/shared-file-systems-quotas.rst +++ b/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. -An administrator can configure limits in the ``manila.conf`` file. +* Limits on resource consumption (also referred to as ``quotas``) +* 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 -requests. Administrators use rate limiting to configure limits on the type and +API Rate Limits +~~~~~~~~~~~~~~~ + +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 -``etc/manila/api-paste.ini`` file, which is a part of the WSGI pipeline and -defines the actual limits. You need to restart ``manila-api`` service after -you edit the ``etc/manila/api-paste.ini`` file. +To set API rate limits, copy and modify the ``etc/manila/api-paste.ini`` file. +You need to restart ``manila-api`` service after you edit the ``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 -``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`` +These quotas can be updated with the :command:`manila quota-update` command. .. 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 -is already used, or if the requested value exceeds the configured quota limit. -To force-update a quota, use ``force`` optional key. +The service will prevent the quota being set lower than the current +consumption. However, a quota update can still be made if necessary with +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 -Type quotas can not be reverted for individual users within a project. They -can only be reverted across all users of a particular project. +Share type quotas can be reverted in the same way. Except, Share Type quotas +can not be set for individual users within a project, so they cannot be +unset either. .. code-block:: console