api-ref: Add group replication APIs

Add APIs introduced for group replication.

Also corrected a few incorrectly referenced group ID
body parameters while I was at it.

Closes-bug: 1700882
Change-Id: I253099072dba9fb6b03f562466aad0ff36b4052f

api-ref/source/v3/group-replication.inc

@@ -0,0 +1,124 @@
+.. -*- rst -*-
+
+Group replication
+=================
+
+Lists targets, enables, disables, and fails over group replication.
+
+Available since API microversion 3.38.
+
+
+List replication targets
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/groups/{group_id}/action
+
+Lists replication targets for a group.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - group_id: group_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/group-replication-list-targets.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - backend_id: backend_id_target
+   - unique_key: replication_targets_unique_key
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/group-replication-target.json
+   :language: javascript
+
+
+Enable group replication
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/groups/{group_id}/action
+
+Enable replication for a group.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - group_id: group_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/group-replication-enable.json
+   :language: javascript
+
+Disable group replication
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/groups/{group_id}/action
+
+Disable replication for a group.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - group_id: group_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/group-replication-disable.json
+   :language: javascript
+
+Failover replication
+~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/groups/{group_id}/action
+
+Failover a replicated group.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - group_id: group_id
+   - allow_attached_volume: allow_attached_volume
+   - secondary_backend_id: backend_id_target
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/group-replication-failover.json
+   :language: javascript

api-ref/source/v3/group-snapshots.inc

@@ -56,7 +56,7 @@ Response Parameters
    - status: status_7
    - description: description
    - created_at: created_at
-   - group_id: group_id
+   - group_id: group_id_1
    - id: id
    - name: name
 
@@ -100,7 +100,7 @@ Response Parameters
    - status: status_7
    - description: description
    - created_at: created_at
-   - group_id: group_id
+   - group_id: group_id_1
    - id: id
    - name: name
 
@@ -170,7 +170,7 @@ Request
 
    - name: name
    - description: description
-   - group_id: group_id
+   - group_id: group_id_1
    - project_id: project_id_path
 
 Request Example
@@ -187,7 +187,7 @@ Response Parameters
    - status: status_7
    - description: description
    - created_at: created_at
-   - group_id: group_id
+   - group_id: group_id_1
    - id: id
    - name: name
 

api-ref/source/v3/groups.inc

@@ -119,6 +119,7 @@ Response Parameters
    - volume_types: volume_types
    - id: id
    - name: name
+   - replication_status: group_replication_status
 
 Response Example
 ----------------

api-ref/source/v3/index.rst

@@ -37,6 +37,7 @@ Block Storage API V3 (CURRENT)
 .. include:: os-cgsnapshots-v3.inc
 .. include:: os-services.inc
 .. include:: groups.inc
+.. include:: group-replication.inc
 .. include:: group-snapshots.inc
 .. include:: group-types.inc
 .. include:: group-type-specs.inc

api-ref/source/v3/parameters.yaml

@@ -66,7 +66,7 @@ group_id:
   description: |
     The ID of the group.
   in: path
-  required: false
+  required: true
   type: string
 group_snapshot_id:
   description: |
@@ -429,6 +429,12 @@ alias:
   in: body
   required: true
   type: string
+allow_attached_volume:
+  description: |
+    Whether to allow failover if any volumes are 'in-use'.
+  in: body
+  required: true
+  type: boolean
 attach_mode:
   description: |
     The attach mode of attachment, read-only ('ro') or
@@ -506,6 +512,12 @@ backend_id:
   in: body
   required: false
   type: string
+backend_id_target:
+  description: |
+    ID of failover target backend.
+  in: body
+  required: true
+  type: string
 backup:
   description: |
     A ``backup`` object.
@@ -1034,6 +1046,12 @@ group_id_1:
   in: body
   required: false
   type: string
+group_replication_status:
+  description: |
+    The group replication status. Introduced with API microversion 3.38.
+  in: body
+  required: false
+  type: string
 group_snapshot_id_1:
   description: |
     The ID of the group snapshot.
@@ -2025,6 +2043,11 @@ replication_targets:
   in: body
   required: true
   type: list
+replication_targets_unique_key:
+  description: |
+    Vendor specific key-values. Only returned if administrator.
+  in: body
+  type: string
 request_id:
   description: |
     The id of the request during which the message was created.

api-ref/source/v3/samples/group-replication-disable.json

@@ -0,0 +1,4 @@
+{
+    "disable_replication": {
+    }
+}

api-ref/source/v3/samples/group-replication-enable.json

@@ -0,0 +1,4 @@
+{
+    "enable_replication": {
+    }
+}

api-ref/source/v3/samples/group-replication-failover.json

@@ -0,0 +1,6 @@
+{
+    "failover_replication": {
+        "allow_attached_volume": true,
+        "secondary_backend_id": "vendor-id-1"
+    }
+}

api-ref/source/v3/samples/group-replication-list-targets.json

@@ -0,0 +1,4 @@
+{
+    "list_replication_targets": {
+    }
+}

api-ref/source/v3/samples/group-replication-target.json

@@ -0,0 +1,6 @@
+{
+    "replication_targets": {
+        "backend_id": "vendor-id-1",
+        "unique_key": "value1"
+    }
+}