openstack/manila
Code Issues Proposed changes

Add documentation for share replica quotas

Browse Source 
Update documentation to fit into the new manila quota keys:
- `share_replicas`
- `replica_gigabytes`

Closes-Bug: #1881921
Change-Id: I91fa2222743da06557ceb52fcbae0f8928d0752c
This commit is contained in:
silvacarloss 2020-04-15 19:59:41 +00:00
parent 9634bfa733
commit 7bc4886a03
16 changed files with 187 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
api-ref/source/limits.inc
View File

@ -11,7 +11,7 @@ tenant (project). An administrator can configure limits in the
Users can query their rate and absolute limits. The absolute limits
contain information about:
- Total maximum share memory, in GBs.
- Total maximum share memory, in GiBs.
- Number of share-networks.
@ -19,9 +19,13 @@ contain information about:
- Number of shares.
- Shares and total used memory, in GBs.
- Shares and total used memory, in GiBs.
- Snapshots and total used memory, in GBs.
- Snapshots and total used memory, in GiBs.
- Number of share replicas (since API version 2.53).
- Share replicas and total used memory, in GiBs (since API version 2.53).
Rate limits control the frequency at which users can issue specific
API requests. Administrators use rate limiting to configure limits
@ -67,11 +71,15 @@ Response parameters
- maxTotalShares: maxTotalShares
- maxTotalShareSnapshots: maxTotalShareSnapshots
- maxTotalShareNetworks: maxTotalShareNetworks
- maxTotalShareReplicas: maxTotalShareReplicas
- maxTotalReplicaGigabytes: maxTotalReplicaGigabytes
- totalSharesUsed: totalSharesUsed
- totalShareSnapshotsUsed: totalShareSnapshotsUsed
- totalShareNetworksUsed: totalShareNetworksUsed
- totalShareGigabytesUsed: totalShareGigabytesUsed
- totalSnapshotGigabytesUsed: totalSnapshotGigabytesUsed
- totalShareReplicasUsed: totalShareReplicasUsed
- totalReplicaGigabytesUsed: totalReplicaGigabytesUsed
- uri: uri
- regex: regex
- value: value

87
api-ref/source/parameters.yaml
View File

@ -1249,6 +1249,24 @@ manage_share_server_id:
required: true
type: string
min_version: 2.49
maxTotalReplicaGigabytes:
description: |
The maximum number of replica gigabytes that are allowed in a project.
You cannot create a share, share replica, manage a share or extend a
share if it is going to exceed the allowed replica gigabytes quota.
in: body
required: true
type: integer
min_version: 2.53
maxTotalReplicaGigabytesOptional:
description: |
The maximum number of replica gigabytes that are allowed in a project.
You cannot create a share, share replica, manage a share or extend a
share if it is going to exceed the allowed replica gigabytes quota.
in: body
required: false
type: integer
min_version: 2.53
maxTotalShareGigabytes:
description: |
The total maximum number of share gigabytes that
@ -1293,6 +1311,20 @@ maxTotalShareNetworksOptional:
in: body
required: false
type: integer
maxTotalShareReplicas:
description: |
The maximum number of share replicas that is allowed.
in: body
required: true
type: integer
min_version: 2.53
maxTotalShareReplicasOptional:
description: |
The maximum number of share replicas that is allowed.
in: body
required: false
type: integer
min_version: 2.53
maxTotalShares:
description: |
The total maximum number of shares that are
@ -1630,6 +1662,27 @@ quota_project_id:
in: body
required: true
type: string
quota_replica_gigabytes:
description: |
The number of gigabytes for the share replicas allowed for each project.
in: body
required: true
min_version: 2.53
type: integer
quota_replica_gigabytes_detail:
description: |
The limit, in_use, reserved number of replica gigabytes for each project.
in: body
min_version: 2.53
required: true
type: object
quota_replica_gigabytes_request:
description: |
The number of gigabytes for share replicas for the project.
in: body
min_version: 2.53
required: false
type: integer
quota_set:
description: |
The ``quota_set`` object.
@ -1707,6 +1760,27 @@ quota_share_networks_request:
in: body
required: false
type: integer
quota_share_replicas:
description: |
The number of share replicas allowed for each project.
in: body
required: true
min_version: 2.53
type: integer
quota_share_replicas_detail:
description: |
The limit, in_use, reserved number of share replicas for each project.
in: body
min_version: 2.53
required: true
type: object
quota_share_replicas_request:
description: |
The number of share replicas allowed for each project or user.
in: body
min_version: 2.53
required: false
type: integer
quota_shares:
description: |
The number of shares allowed for each project.
@ -2801,6 +2875,13 @@ timestamp:
in: body
required: true
type: string
totalReplicaGigabytesUsed:
description: |
The total number of replica gigabytes used in a
project by share replicas.
in: body
required: true
type: integer
totalShareGigabytesUsed:
description: |
The total number of gigabytes used in a project
@ -2815,6 +2896,12 @@ totalShareNetworksUsed:
in: body
required: true
type: integer
totalShareReplicasUsed:
description: |
The total number of created share replicas in a project.
in: body
required: true
type: integer
totalShareSnapshotsUsed:
description: |
The total number of created share snapshots in a

11
api-ref/source/quota-classes.inc
View File

@ -6,6 +6,11 @@ Quota class set
Quota classes can be shown and updated for a project.
.. important::
Share replicas and replica gigabytes were added to quota management
APIs in API version 2.53.
Show quota classes for a project
================================
@ -49,6 +54,8 @@ Response Parameters
- shares: maxTotalShares
- id: quota_class_id
- share_networks: maxTotalShareNetworks
- share_replicas: maxTotalShareReplicas
- replica_gigabytes: maxTotalReplicaGigabytes
Response Example
----------------
@ -90,6 +97,8 @@ Request
- gigabytes: maxTotalShareGigabytesOptional
- snapshot-gigabytes: maxTotalSnapshotGigabytesOptional
- share-networks: maxTotalShareNetworksOptional
- share-replicas: maxTotalShareReplicasOptional
- replica-gigabytes: maxTotalReplicaGigabytesOptional
Request Example
---------------
@ -111,6 +120,8 @@ Response Parameters
- snapshot_gigabytes: maxTotalSnapshotGigabytes
- shares: maxTotalShares
- share_networks: maxTotalShareNetworks
- share_replicas: maxTotalShareReplicas
- replica_gigabytes: maxTotalReplicaGigabytes
Response Example
----------------

17
api-ref/source/quota-sets.inc
View File

@ -18,10 +18,17 @@ Provides quotas management support.
- ``snapshots``
- ``shares``
- ``snapshot_gigabytes``
- ``share_groups`` (since API version 2.40)
- ``share_group_snapshots`` (since API version 2.40)
- ``share_replicas`` (since API version 2.53)
- ``replica_gigabytes`` (since API version 2.53)
Share groups and share group snapshots were added to quota management
APIs in API version 2.40.
Share replicas and replica gigabytes were added to quota management
APIs in API version 2.53.
Show default quota set
======================
@ -66,6 +73,8 @@ Response parameters
- share_groups: quota_share_groups
- share_group_snapshots: quota_share_group_snapshots
- share_networks: quota_share_networks_default
- share_replicas: quota_share_replicas
- replica_gigabytes: quota_replica_gigabytes
Response example
----------------
@ -122,6 +131,8 @@ Response parameters
- share_networks: quota_share_networks
- share_groups: quota_share_groups
- share_group_snapshots: quota_share_group_snapshots
- share_replicas: quota_share_replicas
- replica_gigabytes: quota_replica_gigabytes
Response example
----------------
@ -180,6 +191,8 @@ Response parameters
- share_networks: quota_share_networks_detail
- share_groups: quota_share_groups_detail
- share_group_snapshots: quota_share_group_snapshots_detail
- share_replicas: quota_share_replicas_detail
- replica_gigabytes: quota_replica_gigabytes_detail
Response example
----------------
@ -230,6 +243,8 @@ Request
- share_groups: quota_share_groups_request
- share_group_snapshots: quota_share_group_snapshots_request
- share_type: share_type_for_quota
- share_replicas: quota_share_replicas_request
- replica_gigabytes: quota_replica_gigabytes_request
Request example
---------------
@ -251,6 +266,8 @@ Response parameters
- share_networks: quota_share_networks
- share_groups: quota_share_groups
- share_group_snapshots: quota_share_group_snapshots
- share_replicas: quota_share_replicas
- replica_gigabytes: quota_replica_gigabytes
Response example
----------------

6
api-ref/source/samples/limits-response.json
View File

@ -11,7 +11,11 @@
"maxTotalShares": 50,
"totalSnapshotGigabytesUsed": 0,
"maxTotalSnapshotGigabytes": 1000,
"maxTotalShareSnapshots": 50
"maxTotalShareSnapshots": 50,
"maxTotalShareReplicas": 100,
"maxTotalReplicaGigabytes": 1000,
"totalShareReplicasUsed": 0,
"totalReplicaGigabytesUsed": 0
}
}
}

4
api-ref/source/samples/quota-classes-show-response.json
View File

@ -7,6 +7,8 @@
"snapshot_gigabytes": 1000,
"shares": 50,
"id": "default",
"share_networks": 10
"share_networks": 10,
"share_replicas": 100,
"replica_gigabytes": 1000
}
}

4
api-ref/source/samples/quota-classes-update-response.json
View File

@ -6,6 +6,8 @@
"snapshots": 50,
"snapshot_gigabytes": 1000,
"shares": 50,
"share_networks": 10
"share_networks": 10,
"share_replicas": 100,
"replica_gigabytes": 1000
}
}

8
api-ref/source/samples/quota-show-detail-response.json
View File

@ -21,6 +21,12 @@
"reserved": 0},
"share_group_snapshots": {"in_use": 0,
"limit": 10,
"reserved": 0}
"reserved": 0},
"share_replicas": {"in_use": 0,
"limit": 100,
"reserved": 0},
"replica_gigabytes": {"in_use": 0,
"limit": 1000,
"reserved": 0}
}
}

4
api-ref/source/samples/quota-show-response.json
View File

@ -7,6 +7,8 @@
"id": "16e1ab15c35a457e9c2b2aa189f544e1",
"share_networks": 10,
"share_groups": 10,
"share_group_snapshots": 10
"share_group_snapshots": 10,
"share_replicas": 100,
"replica_gigabytes": 1000
}
}

3
api-ref/source/samples/quota-update-request.json
View File

@ -2,6 +2,7 @@
"quota_set": {
"snapshot_gigabytes": 999,
"snapshots": 49,
"share_networks": 9
"share_networks": 9,
"share_replicas": 89
}
}

4
api-ref/source/samples/quota-update-response.json
View File

@ -6,6 +6,8 @@
"snapshots": 49,
"share_networks": 9,
"share_groups": 12,
"share_group_snapshots": 12
"share_group_snapshots": 12,
"share_replicas": 89,
"replica_gigabytes": 1000
}
}

6
doc/source/admin/shared-file-systems-manage-and-unmanage-share.rst
View File

@ -55,6 +55,12 @@ Manage a share
share servers via share networks until Shared File Systems API version
``2.49`` (Stein/Manila 8.0.0 release).
.. note::
From API version 2.53, if the requester specifies a share type containing
a ``replication_type`` extra spec while managing a share, manila quota
system will reserve and consume resources for two additional quotas:
``share_replicas`` and ``replica_gigabytes``.
To register the non-managed share in the File System service, run the
:command:`manila manage` command:

13
doc/source/admin/shared-file-systems-quotas.rst
View File

@ -25,11 +25,15 @@ To see the absolute limits, run:
| maxTotalShareSnapshots | 50 |
| maxTotalShares | 50 |
| maxTotalSnapshotGigabytes | 1000 |
| maxTotalShareReplicas | 100 |
| maxTotalReplicaGigabytes | 1000 |
| totalShareGigabytesUsed | 1 |
| totalShareNetworksUsed | 2 |
| totalShareSnapshotsUsed | 1 |
| totalSharesUsed | 1 |
| totalSnapshotGigabytesUsed | 1 |
| totalShareReplicasUsed | 1 |
| totalReplicaGigabytesUsed | 1 |
+----------------------------+-------+
Rate limits control the frequency at which users can issue specific API
@ -112,6 +116,8 @@ you get the quotas for the specified project.
| share_networks | 10 |
| share_groups | 50 |
| share_group_snapshots | 50 |
| share_replicas | 100 |
| replica_gigabytes | 1000 |
+-----------------------+-----------------------------------+
There are default quotas for a project that are set from the
@ -132,6 +138,8 @@ the :command:`manila quota-defaults` command:
| 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
@ -140,6 +148,11 @@ 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``.
.. code-block:: console
$ manila quota-update %project_id% --user %user_id% --shares 49 --snapshots 49

4
doc/source/admin/shared-file-systems-share-replication.rst
View File

@ -265,6 +265,10 @@ Specify the share ID or name as a parameter.
created for you. You can verify this with the
:command:`manila share-replica-list` command.
From API version 2.53, when creating a replicated share, the manila quota
system will reserve and consume resources for two additional quotas:
``share_replicas`` and ``replica_gigabytes``.
Creating and promoting share replicas
-------------------------------------

8
doc/source/admin/shared-file-systems-share-resize.rst
View File

@ -15,6 +15,14 @@ with the new size that does not exceed the quota. For details, see
:ref:`Quotas and Limits <shared_file_systems_quotas>`. You also cannot shrink
share size to 0 or to a greater value than the current share size.
.. note::
From API version 2.53, extending a replicated share, manila quota system
will reserve and consume resources for two additional quotas:
``share_replicas`` and ``replica_gigabytes``. This request will fail if
there is no available quotas to extend the share and all of its share
replicas.
While extending, the share has an ``extending`` status. This means that
the increase share size request was issued successfully.

4
doc/source/configuration/shared-file-systems/overview.rst
View File

@ -70,6 +70,10 @@ The Shared File Systems service contains the following components:
- The number of share group snapshots that can be created.
- The number of share replicas that can be created.
- The number of gigabytes that can be provisioned for share replicas.
You can revise the default quota values with the Shared File Systems
CLI, so the limits placed by quotas are editable by admin users.