From 1074e2c0e718735b1df3f107c33c50527862f12a Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 10 Jun 2021 11:50:38 +0100 Subject: [PATCH] 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 Co-authored-by: Lucas de Oliveira Closes-Bug: 1885544 --- api-ref/source/v3/clusters.inc | 317 ++++++++++++++++++ api-ref/source/v3/index.rst | 1 + api-ref/source/v3/os-services.inc | 2 +- api-ref/source/v3/parameters.yaml | 301 ++++++++++++++++- .../v3.7/cluster-disable-request.json | 5 + .../v3.7/cluster-disable-response.json | 10 + .../clusters/v3.7/cluster-enable-request.json | 4 + .../v3.7/cluster-enable-response.json | 10 + .../clusters/v3.7/cluster-show-response.json | 17 + .../v3.7/clusters-list-detailed-response.json | 19 ++ .../clusters/v3.7/clusters-list-response.json | 11 + api-ref/source/v3/volumes-v3-volumes.inc | 8 +- 12 files changed, 689 insertions(+), 16 deletions(-) create mode 100644 api-ref/source/v3/clusters.inc create mode 100644 api-ref/source/v3/samples/clusters/v3.7/cluster-disable-request.json create mode 100644 api-ref/source/v3/samples/clusters/v3.7/cluster-disable-response.json create mode 100644 api-ref/source/v3/samples/clusters/v3.7/cluster-enable-request.json create mode 100644 api-ref/source/v3/samples/clusters/v3.7/cluster-enable-response.json create mode 100644 api-ref/source/v3/samples/clusters/v3.7/cluster-show-response.json create mode 100644 api-ref/source/v3/samples/clusters/v3.7/clusters-list-detailed-response.json create mode 100644 api-ref/source/v3/samples/clusters/v3.7/clusters-list-response.json diff --git a/api-ref/source/v3/clusters.inc b/api-ref/source/v3/clusters.inc new file mode 100644 index 00000000000..4338b571b4e --- /dev/null +++ b/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 diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index ecd024ef635..50d10552343 100644 --- a/api-ref/source/v3/index.rst +++ b/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 diff --git a/api-ref/source/v3/os-services.inc b/api-ref/source/v3/os-services.inc index f5434a92629..3e993c17c7d 100644 --- a/api-ref/source/v3/os-services.inc +++ b/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 ------------------- diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 859c90d0a7a..b3bffdf39b4 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/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 + `_: + + :: + + 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 + `_: + + :: + + 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. diff --git a/api-ref/source/v3/samples/clusters/v3.7/cluster-disable-request.json b/api-ref/source/v3/samples/clusters/v3.7/cluster-disable-request.json new file mode 100644 index 00000000000..bb9d855602a --- /dev/null +++ b/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" +} diff --git a/api-ref/source/v3/samples/clusters/v3.7/cluster-disable-response.json b/api-ref/source/v3/samples/clusters/v3.7/cluster-disable-response.json new file mode 100644 index 00000000000..69016440512 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/v3/samples/clusters/v3.7/cluster-enable-request.json b/api-ref/source/v3/samples/clusters/v3.7/cluster-enable-request.json new file mode 100644 index 00000000000..4bc813e65c1 --- /dev/null +++ b/api-ref/source/v3/samples/clusters/v3.7/cluster-enable-request.json @@ -0,0 +1,4 @@ +{ + "name": "cluster_name", + "binary": "cinder-volume" +} diff --git a/api-ref/source/v3/samples/clusters/v3.7/cluster-enable-response.json b/api-ref/source/v3/samples/clusters/v3.7/cluster-enable-response.json new file mode 100644 index 00000000000..b5692480062 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/v3/samples/clusters/v3.7/cluster-show-response.json b/api-ref/source/v3/samples/clusters/v3.7/cluster-show-response.json new file mode 100644 index 00000000000..84d7fdb58bb --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/v3/samples/clusters/v3.7/clusters-list-detailed-response.json b/api-ref/source/v3/samples/clusters/v3.7/clusters-list-detailed-response.json new file mode 100644 index 00000000000..2e2681bd6b1 --- /dev/null +++ b/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" + } + ] +} diff --git a/api-ref/source/v3/samples/clusters/v3.7/clusters-list-response.json b/api-ref/source/v3/samples/clusters/v3.7/clusters-list-response.json new file mode 100644 index 00000000000..9c310ebcd33 --- /dev/null +++ b/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" + } + ] +} diff --git a/api-ref/source/v3/volumes-v3-volumes.inc b/api-ref/source/v3/volumes-v3-volumes.inc index ecf1a13b18b..41a99d1454e 100644 --- a/api-ref/source/v3/volumes-v3-volumes.inc +++ b/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