api-ref: Add docs for clusters

This API is currently undocumented, as I noticed while working on OSC
changes. There isn't anything too unusual going on here. The API was
first introduced in microversion 3.7 and was then extended with
replication-related information in 3.36. Both are accounted for here.

Change-Id: I86dc774c8d203839f4dadb13e93a416d112fc7b5
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
Co-authored-by: Lucas de Oliveira <lucasmoliveira059@gmail.com>
Closes-Bug: 1885544

api-ref/source/v3/clusters.inc

@@ -0,0 +1,317 @@
+.. -*- rst -*-
+
+Clusters (clusters)
+===================
+
+Administrator only.  Lists all Cinder clusters, show cluster detail,
+enable or disable a cluster.
+
+Each cinder service runs on a *host* computer (possibly multiple services
+on the same host; it depends how you decide to deploy cinder).  In order
+to support High Availibility scenarios, services can be grouped into
+*clusters* where the same type of service (for example, cinder-volume)
+can run on different hosts so that if one host goes down the service is
+still available on a different host. Since there's no point having these
+services sitting around doing nothing while waiting for some other host
+to go down (which is also known as Active/Passive mode), grouping services
+into clusters also allows cinder to support Active/Active mode in which
+all services in a cluster are doing work all the time.
+
+.. note::
+
+   Currently the only service that can be grouped into clusters is
+   ``cinder-volume``.
+
+Clusters are determined by the deployment configuration; that's why there
+is no 'create-cluster' API call listed below.  Once your services are up
+and running, however, you can use the following API requests to get
+information about your clusters and to update their status.
+
+
+Disable cluster
+~~~~~~~~~~~~~~~
+
+.. rest_method::  PUT /v3/{project_id}/clusters/disable
+
+Disables a cluster. Specify the cluster by its name and optionally the
+binary name in the request body.
+
+Available starting in the 3.7 microversion.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - name: cluster_name_required
+   - binary: cluster_binary
+   - disabled_reason: disabled_reason_body
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/clusters/v3.7/cluster-disable-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - cluster: cluster
+   - name: cluster_name_resp
+   - binary: cluster_binary_resp
+   - state: cluster_state
+   - status: cluster_status
+   - replication_status: cluster_replication_status
+   - disabled_reason: disabled_reason_body
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/clusters/v3.7/cluster-disable-response.json
+   :language: javascript
+
+
+Enable cluster
+~~~~~~~~~~~~~~
+
+.. rest_method::  PUT /v3/{project_id}/clusters/enable
+
+Enables a cluster. Specify the cluster by its name and optionally the
+binary name in the request body.
+
+Available starting in the 3.7 microversion.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - name: cluster_name_required
+   - binary: cluster_binary
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/clusters/v3.7/cluster-enable-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - cluster: cluster
+   - name: cluster_name_resp
+   - binary: cluster_binary_resp
+   - state: cluster_state
+   - status: cluster_status
+   - replication_status: cluster_replication_status
+   - disabled_reason: disabled_reason_body
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/clusters/v3.7/cluster-enable-response.json
+   :language: javascript
+
+
+Show cluster details
+~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/clusters/{cluster_name}
+
+Shows details for a cluster by its name and optionally the
+binary name.
+
+Available starting in the 3.7 microversion.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - cluster_name: cluster_name_path
+   - binary: cluster_binary_query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - cluster: cluster
+   - name: cluster_name_resp
+   - binary: cluster_binary_resp
+   - state: cluster_state
+   - status: cluster_status
+   - num_hosts: cluster_num_hosts
+   - num_down_hosts: cluster_num_down_hosts
+   - last_heartbeat: cluster_last_heartbeat
+   - created_at: created_at
+   - updated_at: updated_at
+   - disabled_reason: disabled_reason_body
+   - replication_status: cluster_replication_status
+   - frozen: cluster_frozen
+   - active_backend_id: cluster_active_backend_id
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/clusters/v3.7/cluster-show-response.json
+   :language: javascript
+
+
+List clusters
+~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/clusters
+
+Lists all clusters.
+
+Available starting in the 3.7 microversion.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - name: cluster_name_query
+   - binary: cluster_binary_query
+   - is_up: cluster_is_up_query
+   - disabled: cluster_disabled_query
+   - num_hosts: cluster_num_hosts_query
+   - num_down_hosts: cluster_num_down_hosts_query
+   - replication_status: cluster_replication_status_query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - clusters: clusters
+   - name: cluster_name_resp
+   - binary: cluster_binary_resp
+   - state: cluster_state
+   - status: cluster_status
+   - replication_status: cluster_replication_status
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/clusters/v3.7/clusters-list-response.json
+   :language: javascript
+
+
+List clusters with details
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/clusters/detail
+
+Lists all clusters with details.
+
+Available starting in the 3.7 microversion.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - name: cluster_name_query
+   - binary: cluster_binary_query
+   - is_up: cluster_is_up_query
+   - disabled: cluster_disabled_query
+   - num_hosts: cluster_num_hosts_query
+   - num_down_hosts: cluster_num_down_hosts_query
+   - replication_status: cluster_replication_status_query
+   - frozen: cluster_frozen
+   - active_backend_id: cluster_active_backend_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - clusters: clusters
+   - name: cluster_name_resp
+   - binary: cluster_binary_resp
+   - state: cluster_state
+   - status: cluster_status
+   - num_hosts: cluster_num_hosts
+   - num_down_hosts: cluster_num_down_hosts
+   - last_heartbeat: cluster_last_heartbeat
+   - created_at: created_at
+   - updated_at: updated_at
+   - disabled_reason: disabled_reason_body
+   - replication_status: cluster_replication_status
+   - frozen: cluster_frozen
+   - active_backend_id: cluster_active_backend_id
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/clusters/v3.7/clusters-list-detailed-response.json
+   :language: javascript

api-ref/source/v3/index.rst

@@ -55,6 +55,7 @@ Block Storage API V3 (CURRENT)
 .. include:: ext-backups.inc
 .. include:: ext-backups-actions-v3.inc
 .. include:: capabilities-v3.inc
+.. include:: clusters.inc
 .. include:: consistencygroups-v3.inc
 .. include:: os-cgsnapshots-v3.inc
 .. include:: os-services.inc

api-ref/source/v3/os-services.inc

@@ -36,7 +36,7 @@ Request
 
    - project_id: project_id_path
    - host: host_query
-   - binary: binary_query
+   - binary: service_binary_query
 
 Response Parameters
 -------------------

api-ref/source/v3/parameters.yaml

@@ -31,6 +31,12 @@ cgsnapshot_id_path:
   in: path
   required: true
   type: string
+cluster_name_path:
+  description: |
+    The name of the cluster.
+  in: path
+  required: true
+  type: string
 consistencygroup_id_path:
   description: |
     The ID of the consistency group.
@@ -68,6 +74,19 @@ hostname:
   in: path
   required: true
   type: string
+init_at:
+  description: |
+    The date and time when the resource was initiated.
+
+        The date and time stamp format is `ISO 8601
+        <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+        ::
+
+           CCYY-MM-DDThh:mm:ss±hh:mm
+  in: path
+  required: true
+  type: string
 key_encrypt_spec:
   description: |
     The key name of the encryption spec for a volume type.
@@ -188,12 +207,6 @@ all-tenants:
   in: query
   required: false
   type: string
-binary_query:
-  description: |
-    Filter the service list result by binary name of the service.
-  in: query
-  required: false
-  type: string
 bootable_query:
   description: |
     Filters results by bootable status. Default=None.
@@ -206,6 +219,63 @@ cascade:
   in: query
   required: false
   type: boolean
+cluster_active_backend_id_query:
+  description: |
+    Filter the cluster list result by the ID of the active backend.
+  in: query
+  required: false
+  type: string
+cluster_binary_query:
+  description: |
+    Filter the cluster list result by binary name of the clustered services.
+    One of ``cinder-api``, ``cinder-scheduler``, ``cinder-volume``
+    or ``cinder-backup``.
+  in: query
+  required: false
+  type: string
+cluster_disabled_query:
+  description: |
+    Filter the cluster list result by status.
+  in: query
+  required: false
+  type: boolean
+cluster_frozen_query:
+  description: |
+    Filter the cluster list result by whether it's frozen.
+  in: query
+  required: false
+  type: boolean
+cluster_is_up_query:
+  description: |
+    Filter the cluster list result by state.
+  in: query
+  required: false
+  type: boolean
+cluster_name_query:
+  description: |
+    Filter the cluster list result by cluster name.
+  in: query
+  required: false
+  type: string
+cluster_num_down_hosts_query:
+  description: |
+    Filter the cluster list result by number of down hosts.
+  in: query
+  required: false
+  type: integer
+cluster_num_hosts_query:
+  description: |
+    Filter the cluster list result by number of hosts.
+  in: query
+  required: false
+  type: integer
+cluster_replication_status_query:
+  description: |
+    Filter the cluster list result by replication status. One of: ``enabled``,
+    ``disabled``.
+  in: query
+  required: false
+  type: string
 detail:
   description: |
     Indicates whether to show pool details or only
@@ -389,6 +459,12 @@ resource:
   in: query
   required: false
   type: string
+service_binary_query:
+  description: |
+    Filter the service list result by binary name of the service.
+  in: query
+  required: false
+  type: string
 sort:
   description: |
     Comma-separated list of sort keys and optional
@@ -786,6 +862,31 @@ cipher:
   in: body
   required: false
   type: string
+cluster:
+  description: |
+    A cluster object.
+  in: body
+  required: true
+  type: object
+cluster_active_backend_id:
+  description: |
+    The ID of active storage backend. Only in ``cinder-volume`` service.
+  in: body
+  required: false
+  type: string
+  min_version: 3.26
+cluster_binary:
+  description: |
+    The binary name of the services in the cluster.
+  in: body
+  required: false
+  type: string
+cluster_binary_resp:
+  description: |
+    The binary name of the services in the cluster.
+  in: body
+  required: true
+  type: string
 cluster_cvol:
   description: |
     The cluster name. Only in ``cinder-volume`` service.
@@ -793,6 +894,31 @@ cluster_cvol:
   required: false
   type: string
   min_version: 3.7
+cluster_frozen:
+  description: |
+    Whether the cluster is frozen or not.
+  in: body
+  required: false
+  type: boolean
+  min_version: 3.26
+cluster_last_heartbeat:
+  description: |
+    The last periodic heartbeat received.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
 cluster_mutex:
   description: |
     The OpenStack Block Storage cluster where the resource resides.  Optional
@@ -800,13 +926,55 @@ cluster_mutex:
   in: body
   required: false
   type: string
-cluster_name:
+cluster_name_required:
   description: |
-    The cluster name of volume backend.
+    The name to identify the service cluster.
+  in: body
+  required: true
+  type: string
+cluster_name_resp:
+  description: |
+    The name of the service cluster.
+  in: body
+  required: true
+  type: string
+cluster_num_down_hosts:
+  description: |
+    The number of down hosts in the cluster.
+  in: body
+  required: true
+  type: integer
+cluster_num_hosts:
+  description: |
+    The number of hosts in the cluster.
+  in: body
+  required: true
+  type: integer
+cluster_replication_status:
+  description: |
+    The cluster replication status. Only included in responses if configured.
+    One of: ``enabled`` or ``disabled``.
   in: body
   required: false
   type: string
-  min_version: 3.61
+cluster_state:
+  description: |
+    The state of the cluster. One of ``up`` or ``down``.
+  in: body
+  required: true
+  type: string
+cluster_status:
+  description: |
+    The status of the cluster. One of ``enabled`` or ``disabled``.
+  in: body
+  required: true
+  type: string
+clusters:
+  description: |
+    A list of cluster objects.
+  in: body
+  required: true
+  type: array
 connection_info:
   description: |
     The connection info used for server to connect the volume.
@@ -979,6 +1147,12 @@ deleted_at:
   in: body
   required: true
   type: string
+dependents:
+  description: |
+    Show the dependencies cluster.
+  in: body
+  requered: false
+  type: string
 description:
   description: |
     The backup description or null.
@@ -1094,6 +1268,13 @@ description_volume_type_required:
   in: body
   required: true
   type: string
+desired_capacity:
+  description: |
+    Show and set the desired capacity of cluster.
+  in: body
+  requered: true
+  type: string
+  min_version: 3.7
 destination_project_id:
   description: |
     Records the destination project_id after volume transfer.
@@ -1116,13 +1297,13 @@ disabled:
   type: boolean
 disabled_reason_body:
   description: |
-    The reason for disabling a service.
+    The reason for disabling a resource.
   in: body
   required: false
   type: string
 disabled_reason_body_req:
   description: |
-    The reason for disabling a service.
+    The reason for disabling a resource.
   in: body
   required: true
   type: string
@@ -1151,6 +1332,12 @@ display_name:
   in: body
   required: true
   type: string
+domain:
+  description: |
+    show de domain in use for the cluster.
+  in: body
+  required: true
+  type: string
 driver_version:
   description: |
     The driver version.
@@ -1605,6 +1792,12 @@ keys:
   in: body
   required: true
   type: array
+last_heartbeat:
+  description: |
+    Find the operational latency between this server/cluster and the other members of the replica set.
+  in: body
+  required: false
+  type: string
 levels:
   description: |
     The current log level that queried.
@@ -1704,6 +1897,12 @@ manageable-volumes:
   in: body
   required: true
   type: list
+max_size:
+  description: |
+    The maximum total size for the cluster.
+  in: body
+  required: true
+  type: integer
 maxTotalBackupGigabytes:
   description: |
     The maximum total amount of backups, in gibibytes
@@ -1909,12 +2108,24 @@ migration_status:
   in: body
   required: false
   type: string
+min_size:
+  description: |
+    The maximum total size for the cluster.
+  in: body
+  required: true
+  type: integer
 mountpoint:
   description: |
     The attaching mount point.
   in: body
   required: true
   type: string
+multiattach:
+  description: |
+    Enable creating multiattach volumes
+  in: body
+  required: false
+  type: string
 multiattach_req:
   description: |
     To enable this volume to attach to more than one
@@ -2065,6 +2276,24 @@ no_snapshots:
   required: false
   min_version: 3.55
   type: boolean
+nodes:
+  description: |
+    A list of the UUIDs of node objects which are members of the current cluster.
+  in: body
+  required: false
+  type: string
+num_down_hosts:
+  description: |
+    A list of the hosts innoperates
+  in: body
+  required: false
+  type: integer
+num_hosts:
+  description: |
+    List of all hosts.
+  in: body
+  required: false
+  type: integer
 object_count:
   description: |
     The number of objects in the backup.
@@ -2285,6 +2514,12 @@ per_volume_gigabytes_usage:
   in: body
   required: true
   type: object
+policies:
+  description: |
+    A list of UUIDs of the policies attached to current cluster.
+  in: body
+  required: false
+  type: string
 pool_name:
   description: |
     The name of the storage pool.
@@ -2306,6 +2541,22 @@ prefix:
   in: body
   required: false
   type: string
+profile_id:
+  description: |
+    The UUID of the profile.
+  in: body
+  required: false
+  type: string
+  min_version: 3.7
+profile_name:
+  description: |
+    The name of a profile object. The name must start
+    with an ASCII letter and can contain ASCII letters,
+    digits, underscores, periods, and hyphens and its
+    length must be less than 255
+  in: body
+  required: true
+  type: string
 project:
   description: |
     The ID of the project. Volume Type access to be
@@ -2836,6 +3087,12 @@ specs:
   in: body
   required: true
   type: object
+state:
+  description: |
+    The ''state'' of the cluster. One for "up" or "down".
+  in: body
+  required: true
+  type: string
 status:
   description: |
     The ``status`` of the consistency group snapshot.
@@ -2879,6 +3136,13 @@ status_group_snap:
   in: body
   required: true
   type: string
+status_reason:
+  description: |
+    The string representation of the reason why the object
+    has transited to its current status.
+  in: body
+  required: false
+  type: string
 status_snap:
   description: |
     The status for the snapshot.
@@ -2906,6 +3170,14 @@ summary_metadata:
   required: true
   type: object
   min_version: 3.36
+timeout:
+  descripition: |
+    The default timeout value (in seconds)
+    of cluster operations.
+  in: body
+  required: false
+  type: integer
+  min_version: 3.7
 total_capacity:
   description: |
     The total capacity for the back-end volume, in
@@ -3139,6 +3411,13 @@ volume_backend_name:
   in: body
   required: true
   type: string
+volume_cluster_name:
+  description: |
+    The cluster name of volume backend.
+  in: body
+  required: false
+  type: string
+  min_version: 3.61
 volume_id:
   description: |
     The UUID of the volume.

api-ref/source/v3/samples/clusters/v3.7/cluster-disable-request.json

@@ -0,0 +1,5 @@
+{
+    "name": "cluster_name",
+    "binary": "cinder-volume",
+    "disabled_reason": "for testing"
+}

api-ref/source/v3/samples/clusters/v3.7/cluster-disable-response.json

@@ -0,0 +1,10 @@
+{
+    "cluster": {
+        "name": "cluster_name",
+        "state": "up",
+        "binary": "cinder-volume",
+        "status": "disabled",
+        "disabled_reason": "for testing",
+        "replication_status": "disable"
+    }
+}

api-ref/source/v3/samples/clusters/v3.7/cluster-enable-request.json

@@ -0,0 +1,4 @@
+{
+    "name": "cluster_name",
+    "binary": "cinder-volume"
+}

api-ref/source/v3/samples/clusters/v3.7/cluster-enable-response.json

@@ -0,0 +1,10 @@
+{
+    "cluster": {
+        "name": "cluster_name",
+        "state": "up",
+        "binary": "cinder-volume",
+        "status": "enabled",
+        "disabled_reason": null,
+        "replication_status": "enable"
+    }
+}

api-ref/source/v3/samples/clusters/v3.7/cluster-show-response.json

@@ -0,0 +1,17 @@
+{
+    "cluster": {
+        "name": "cluster_name",
+        "binary": "cinder-volume",
+        "state": "up",
+        "status": "enabled",
+        "disabled_reason": null,
+        "created_at": "2016-06-01T02:46:28",
+        "updated_at": "2016-06-01T02:46:28",
+        "num_down_hosts": 0,
+        "num_hosts": 0,
+        "last_heartbeat": "2016-06-01T02:46:28",
+        "replication_status": "enable",
+        "frozen": false,
+        "active_backend_id": "replication1"
+    }
+}

api-ref/source/v3/samples/clusters/v3.7/clusters-list-detailed-response.json

@@ -0,0 +1,19 @@
+{
+    "clusters": [
+        {
+            "name": "cluster_name",
+            "binary": "cinder-volume",
+            "state": "up",
+            "status": "enabled",
+            "disabled_reason": null,
+            "created_at": "2016-06-01T02:46:28",
+            "updated_at": "2016-06-01T02:46:28",
+            "num_down_hosts": 0,
+            "num_hosts": 0,
+            "last_heartbeat": "2016-06-01T02:46:28",
+            "replication_status": "enable",
+            "frozen": false,
+            "active_backend_id": "replication1"
+        }
+    ]
+}

api-ref/source/v3/samples/clusters/v3.7/clusters-list-response.json

@@ -0,0 +1,11 @@
+{
+    "clusters": [
+        {
+            "name": "cluster_name",
+            "binary": "cinder-volume",
+            "state": "up",
+            "status": "enabled",
+            "replication_status": "enable"
+        }
+    ]
+}

api-ref/source/v3/volumes-v3-volumes.inc

@@ -141,7 +141,7 @@ Response Parameters
    - service_uuid: service_uuid
    - shared_targets: shared_targets
    - shared_targets: shared_targets_tristate
-   - cluster_name: cluster_name
+   - cluster_name: volume_cluster_name
    - consumes_quota: consumes_quota
    - count: count
 
@@ -269,7 +269,7 @@ Response Parameters
    - service_uuid: service_uuid
    - shared_targets: shared_targets
    - shared_targets: shared_targets_tristate
-   - cluster_name: cluster_name
+   - cluster_name: volume_cluster_name
    - consumes_quota: consumes_quota
 
 Response Example (v3.65)
@@ -406,7 +406,7 @@ Response Parameters
    - service_uuid: service_uuid
    - shared_targets: shared_targets
    - shared_targets: shared_targets_tristate
-   - cluster_name: cluster_name
+   - cluster_name: volume_cluster_name
    - provider_id:  provider_id
    - group_id: group_id_optional
    - consumes_quota: consumes_quota
@@ -489,7 +489,7 @@ Response Parameters
    - service_uuid: service_uuid
    - shared_targets: shared_targets
    - shared_targets: shared_targets_tristate
-   - cluster_name: cluster_name
+   - cluster_name: volume_cluster_name
    - consumes_quota: consumes_quota