Api-ref: add 'os-services' v3 api doc

There is no document about v3 'os-services' api.
So add the missing content.

Change-Id: I104915cdb0486ab8f4482f0034f58a03c3f72b77
This commit is contained in:
lihaijing 2017-06-29 09:32:47 +08:00
parent 873e7a2f17
commit b6f495b61d
16 changed files with 623 additions and 1 deletions

View File

@ -35,6 +35,7 @@ Block Storage API V3 (CURRENT)
.. include:: capabilities-v3.inc
.. include:: consistencygroups-v3.inc
.. include:: os-cgsnapshots-v3.inc
.. include:: os-services.inc
.. include:: groups.inc
.. include:: group-snapshots.inc
.. include:: group-types.inc

View File

@ -0,0 +1,353 @@
.. -*- rst -*-
Services (os-services)
======================
Administrator only. Lists all Cinder services, enables or disables
a Cinder service, freeze or thaw the specified cinder-volume host,
failover a replicating cinder-volume host.
List All Cinder Services
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/os-services
Lists all Cinder services. Provides details why any services
were disabled.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- host: host_query
- binary: binary_query
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- services: services
- binary: binary
- disabled_reason: disabled_reason_body
- host: host_name_body
- state: service_state_1
- status: service_status
- frozen: frozen
- updated_at: updated
- zone: availability_zone_3
- cluster: cluster
- replication_status: replication_status_1
- active_backend_id: active_backend_id
Response Example
----------------
.. literalinclude:: ./samples/services-list-response.json
:language: javascript
Disable a Cinder Service
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/disable
Disables a Cinder service. Specify the service by its host name
and binary name.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- binary: binary
- host: host_name_body
Request Example
---------------
.. literalinclude:: ./samples/services-disable-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- disabled: disabled_1
- status: service_status
- host: host_name_body
- service: service_key
- binary: binary
Response Example
----------------
.. literalinclude:: ./samples/services-disable-response.json
:language: javascript
Log Disabled Cinder Service Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/disable-log-reason
Logs information to the Cinder service table about why a Cinder service was disabled.
Specify the service by its host name and binary name.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- binary: binary
- host: host_name_body
- disabled_reason: disabled_reason_body
Request Example
---------------
.. literalinclude:: ./samples/services-disable-log-request.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- disabled: disabled_1
- status: service_status
- host: host_name_body
- service: service_key
- binary: binary
- disabled_reason: disabled_reason_body
Response Example
----------------
.. literalinclude:: ./samples/services-disable-log-response.json
:language: javascript
Enable a Cinder Service
~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/enable
Enables a Cinder service. Specify the service by its host name
and binary name.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- binary: binary
- host: host_name_body
Request Example
---------------
.. literalinclude:: ./samples/services-enable-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- disabled: disabled_1
- status: service_status
- host: host_name_body
- service: service_key
- binary: binary
- disabled_reason: disabled_reason_body
Response Example
----------------
.. literalinclude:: ./samples/services-enable-response.json
:language: javascript
Get Current Log Levels for Cinder Services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/get-log
Get current log levels for services, supported since v3.32. Filter the
services by binary, server name and prefix for the log path.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- binary: binary_1
- server: host_name_body_1
- prefix: prefix
Request Example
---------------
.. literalinclude:: ./samples/services-get-log-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- log_levels: log_levels
- binary: binary
- host: host_name_body
- levels: levels
Response Example
----------------
.. literalinclude:: ./samples/services-get-log-response.json
:language: javascript
Set Log Levels of Cinder Services Dynamically
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/set-log
Set log levels of services dynamically, supported since v3.32. Filter the
services by binary, server name and prefix for the log path.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- binary: binary_1
- server: host_name_body_1
- prefix: prefix
- levels: levels_1
Request Example
---------------
.. literalinclude:: ./samples/services-set-log-request.json
:language: javascript
Freeze a Cinder Backend Host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/freeze
Freeze and disable the specified cinder-volume host, and set
``Disabled Reason`` of Cinder service table to ``frozen``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- host: host_name_body
Request Example
---------------
.. literalinclude:: ./samples/services-freeze-request.json
:language: javascript
Thaw a Cinder Backend Host
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/thaw
Thaw and enable the specified cinder-volume host, and clean
``Disabled Reason`` of Cinder service table.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- host: host_name_body
Request Example
---------------
.. literalinclude:: ./samples/services-thaw-request.json
:language: javascript
Failover a Cinder Backend Host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/os-services/failover_host
Failover a replicating cinder-volume host. Since Cinder Volume API Version
3.26, you can use ``failover`` in request URL instead of ``failover_host``,
and the cluster name in request body is supported.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- host: host_name_body
- backend_id: backend_id
- cluster: cluster
Request Example
---------------
.. literalinclude:: ./samples/services-failover-host-request.json
:language: javascript

View File

@ -201,6 +201,12 @@ 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.
@ -215,6 +221,12 @@ detail:
in: query
required: false
type: boolean
host_query:
description: |
Filter the service list result by host name of the service.
in: query
required: false
type: string
image-id:
description: |
Creates volume from image ID. Default=None.
@ -396,6 +408,12 @@ absolute:
in: body
required: true
type: object
active_backend_id:
description: |
The ID of active storage backend. Only in ``cinder-volume`` service.
in: body
required: false
type: string
add_volumes:
description: |
One or more volume UUIDs, separated by commas, to
@ -482,6 +500,12 @@ availability_zone_3:
in: body
required: true
type: string
backend_id:
description: |
ID of backend to failover to. Default is ``None``.
in: body
required: false
type: string
backup:
description: |
A ``backup`` object.
@ -524,7 +548,13 @@ backups_number_usage:
type: object
binary:
description: |
The service binary.
The binary name of the service.
in: body
required: true
type: string
binary_1:
description: |
The binary name of the service.
in: body
required: false
type: string
@ -569,6 +599,19 @@ cipher:
in: body
required: false
type: string
cluster:
description: |
The cluster name. Only in ``cinder-volume`` service.
in: body
required: false
type: string
min_version: 3.7
cluster_1:
description: |
The cluster name.
in: body
required: false
type: string
cluster_mutex:
description: |
The OpenStack Block Storage cluster where the resource resides. Optional
@ -815,6 +858,24 @@ disabled:
in: body
required: false
type: boolean
disabled_1:
description: |
The service is disabled or not.
in: body
required: true
type: boolean
disabled_reason_body:
description: |
The reason for disabling a service.
in: body
required: true
type: string
disabled_reason_body_1:
description: |
The reason for disabling a service.
in: body
required: false
type: string
disk_format:
description: |
Disk format for the new image. Default is raw.
@ -931,6 +992,12 @@ free_capacity:
in: body
required: true
type: string
frozen:
description: |
The host is frozen or not. Only in ``cinder-volume`` service.
in: body
required: false
type: boolean
gigabytes:
description: |
The size (GB) of volumes and snapshots that are allowed for each project.
@ -1047,6 +1114,18 @@ host_name:
in: body
required: false
type: string
host_name_body:
description: |
The name of the host.
in: body
required: true
type: string
host_name_body_1:
description: |
The name of the host.
in: body
required: false
type: string
host_service:
description: |
The name of the service which is running on the host.
@ -1193,6 +1272,26 @@ keys:
in: body
required: true
type: array
levels:
description: |
The current log level that queried.
in: body
required: true
type: object
levels_1:
description: |
The log level to set, case insensitive, accepted values are ``INFO``,
``WARNING``, ``ERROR`` and ``DEBUG``.
in: body
required: true
type: string
limit_usage:
description: |
The limit data size. Visible only if you set the
``usage=true`` query parameter.
in: body
required: false
type: integer
limits:
description: |
A list of ``limit`` objects.
@ -1242,6 +1341,12 @@ location:
in: body
required: true
type: string
log_levels:
description: |
The list of log levels.
in: body
required: true
type: array
manageable-snapshots:
description: |
A list of manageable snapshots.
@ -1779,6 +1884,15 @@ pool_name:
in: body
required: true
type: string
prefix:
description: |
The prefix for the log path we are querying,
for example ``cinder.`` or ``sqlalchemy.engine``.
When not present or the empty string is passed all
log levels will be retrieved.
in: body
required: false
type: string
project:
description: |
The ID of the project. Volume Type access to be
@ -1898,6 +2012,12 @@ replication_status:
in: body
required: true
type: string
replication_status_1:
description: |
The volume service replication status. Only in ``cinder-volume`` service.
in: body
required: false
type: string
replication_targets:
description: |
A list of volume backends used to replicate volumes
@ -1973,24 +2093,57 @@ safe_to_manage:
in: body
required: true
type: boolean
security_group_rules:
description: |
The number of rules that are allowed for each
security group.
in: body
required: false
type: integer
security_groups:
description: |
The number of security groups that are allowed
for each project.
in: body
required: true
type: integer
service_id:
description: |
UUID for the cleanup service.
in: body
required: false
type: string
service_key:
description: |
The service name. Deprecated. Keeping service key
for API compatibility.
in: body
required: true
type: string
service_state:
description: |
The state of the service. One of ``available`` or ``unavailable``.
in: body
required: true
type: string
service_state_1:
description: |
The state of the service. One of ``up`` or ``down``.
in: body
required: true
type: string
service_status:
description: |
The status of the service. One of ``enabled`` or ``disabled``.
in: body
required: true
type: string
services:
description: |
A list of service objects.
in: body
required: true
type: array
size:
description: |
The size of the volume, in gibibytes (GiB).

View File

@ -0,0 +1,5 @@
{
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1",
"disabled_reason": "test"
}

View File

@ -0,0 +1,8 @@
{
"disabled": true,
"status": "disabled",
"host": "devstack@lvmdriver-1",
"service": "",
"binary": "cinder-volume",
"disabled_reason": "test"
}

View File

@ -0,0 +1,4 @@
{
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1"
}

View File

@ -0,0 +1,7 @@
{
"disabled": true,
"status": "disabled",
"host": "devstack@lvmdriver-1",
"service": "",
"binary": "cinder-volume"
}

View File

@ -0,0 +1,4 @@
{
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1"
}

View File

@ -0,0 +1,8 @@
{
"disabled": false,
"status": "enabled",
"host": "devstack@lvmdriver-1",
"service": "",
"binary": "cinder-volume",
"disabled_reason": null
}

View File

@ -0,0 +1,4 @@
{
"host": "devstack@lvmdriver-1",
"backend_id": null
}

View File

@ -0,0 +1,3 @@
{
"host": "devstack@rbd-sas"
}

View File

@ -0,0 +1,5 @@
{
"binary": "cinder-volume",
"server": "devstack@lvmdriver-1",
"prefix": "cinder.volume"
}

View File

@ -0,0 +1,25 @@
{
"log_levels": [{
"binary": "cinder-api",
"host": "devstack",
"levels": {
"cinder.volume.api": "DEBUG"
}
}, {
"binary": "cinder-scheduler",
"host": "devstack",
"levels": {
"cinder.volume.api": "DEBUG"
}
}, {
"binary": "cinder-backup",
"host": "devstack",
"levels": {}
}, {
"binary": "cinder-volume",
"host": "devstack@lvmdriver-1",
"levels": {
"cinder.volume.api": "DEBUG"
}
}]
}

View File

@ -0,0 +1,33 @@
{
"services": [{
"status": "enabled",
"binary": "cinder-scheduler",
"zone": "nova",
"state": "up",
"updated_at": "2017-06-29T05:50:35.000000",
"host": "devstack",
"disabled_reason": null
},
{
"status": "enabled",
"binary": "cinder-backup",
"zone": "nova",
"state": "up",
"updated_at": "2017-06-29T05:50:42.000000",
"host": "devstack",
"disabled_reason": null
},
{
"status": "enabled",
"binary": "cinder-volume",
"zone": "nova",
"frozen": false,
"state": "up",
"updated_at": "2017-06-29T05:50:39.000000",
"cluster": null,
"host": "devstack@lvmdriver-1",
"replication_status": "disabled",
"active_backend_id": null,
"disabled_reason": null
}]
}

View File

@ -0,0 +1,6 @@
{
"binary": "cinder-volume",
"server": "devstack@lvmdriver-1",
"prefix": "cinder.volume",
"level": "ERROR"
}

View File

@ -0,0 +1,3 @@
{
"host": "devstack@rbd-sas"
}