openstack/cinder
Code Issues Proposed changes

api-ref: Add docs for clusters

Browse Source 
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
This commit is contained in:
Stephen Finucane 2021-06-10 11:50:38 +01:00
parent 743385ac19
commit 1074e2c0e7
12 changed files with 689 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

317
api-ref/source/v3/clusters.inc Normal file
View File

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

1
api-ref/source/v3/index.rst
View File

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

2
api-ref/source/v3/os-services.inc
View File

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

301
api-ref/source/v3/parameters.yaml
View File

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

5
api-ref/source/v3/samples/clusters/v3.7/cluster-disable-request.json Normal file
View File

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

10
api-ref/source/v3/samples/clusters/v3.7/cluster-disable-response.json Normal file
View File

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

4
api-ref/source/v3/samples/clusters/v3.7/cluster-enable-request.json Normal file
View File

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

10
api-ref/source/v3/samples/clusters/v3.7/cluster-enable-response.json Normal file
View File

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

17
api-ref/source/v3/samples/clusters/v3.7/cluster-show-response.json Normal file
View File

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

19
api-ref/source/v3/samples/clusters/v3.7/clusters-list-detailed-response.json Normal file
View File

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

11
api-ref/source/v3/samples/clusters/v3.7/clusters-list-response.json Normal file
View File

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

8
api-ref/source/v3/volumes-v3-volumes.inc
View File

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