Add documentation for share replica quotas

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

Closes-Bug: #1881921
Change-Id: I91fa2222743da06557ceb52fcbae0f8928d0752c
(cherry picked from commit 7bc4886a03)

api-ref/source/limits.inc

@@ -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

api-ref/source/parameters.yaml

@@ -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

api-ref/source/quota-classes.inc

@@ -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
 ----------------

api-ref/source/quota-sets.inc

@@ -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
 ----------------

api-ref/source/samples/limits-response.json

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

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

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

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

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

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

@@ -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}
     }
 }

api-ref/source/samples/quota-show-response.json

@@ -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
     }
 }

api-ref/source/samples/quota-update-request.json

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

api-ref/source/samples/quota-update-response.json

@@ -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
     }
 }

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

@@ -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:
 

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

@@ -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

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

@@ -273,6 +273,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
 -------------------------------------

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

@@ -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.
 

doc/source/configuration/shared-file-systems/overview.rst

@@ -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.