From b6f495b61dad23299b31ca90d266cb614c96774d Mon Sep 17 00:00:00 2001 From: lihaijing Date: Thu, 29 Jun 2017 09:32:47 +0800 Subject: [PATCH] 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 --- api-ref/source/v3/index.rst | 1 + api-ref/source/v3/os-services.inc | 353 ++++++++++++++++++ api-ref/source/v3/parameters.yaml | 155 +++++++- .../samples/services-disable-log-request.json | 5 + .../services-disable-log-response.json | 8 + .../v3/samples/services-disable-request.json | 4 + .../v3/samples/services-disable-response.json | 7 + .../v3/samples/services-enable-request.json | 4 + .../v3/samples/services-enable-response.json | 8 + .../services-failover-host-request.json | 4 + .../v3/samples/services-freeze-request.json | 3 + .../v3/samples/services-get-log-request.json | 5 + .../v3/samples/services-get-log-response.json | 25 ++ .../v3/samples/services-list-response.json | 33 ++ .../v3/samples/services-set-log-request.json | 6 + .../v3/samples/services-thaw-request.json | 3 + 16 files changed, 623 insertions(+), 1 deletion(-) create mode 100644 api-ref/source/v3/os-services.inc create mode 100644 api-ref/source/v3/samples/services-disable-log-request.json create mode 100644 api-ref/source/v3/samples/services-disable-log-response.json create mode 100644 api-ref/source/v3/samples/services-disable-request.json create mode 100644 api-ref/source/v3/samples/services-disable-response.json create mode 100644 api-ref/source/v3/samples/services-enable-request.json create mode 100644 api-ref/source/v3/samples/services-enable-response.json create mode 100644 api-ref/source/v3/samples/services-failover-host-request.json create mode 100644 api-ref/source/v3/samples/services-freeze-request.json create mode 100644 api-ref/source/v3/samples/services-get-log-request.json create mode 100644 api-ref/source/v3/samples/services-get-log-response.json create mode 100644 api-ref/source/v3/samples/services-list-response.json create mode 100644 api-ref/source/v3/samples/services-set-log-request.json create mode 100644 api-ref/source/v3/samples/services-thaw-request.json diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index cfd13813029..fbc04add257 100644 --- a/api-ref/source/v3/index.rst +++ b/api-ref/source/v3/index.rst @@ -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 diff --git a/api-ref/source/v3/os-services.inc b/api-ref/source/v3/os-services.inc new file mode 100644 index 00000000000..95e74f4a76e --- /dev/null +++ b/api-ref/source/v3/os-services.inc @@ -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 diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 6567957a561..da4e6c3230a 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -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). diff --git a/api-ref/source/v3/samples/services-disable-log-request.json b/api-ref/source/v3/samples/services-disable-log-request.json new file mode 100644 index 00000000000..fb30eb1dba4 --- /dev/null +++ b/api-ref/source/v3/samples/services-disable-log-request.json @@ -0,0 +1,5 @@ +{ + "binary": "cinder-volume", + "host": "devstack@lvmdriver-1", + "disabled_reason": "test" +} diff --git a/api-ref/source/v3/samples/services-disable-log-response.json b/api-ref/source/v3/samples/services-disable-log-response.json new file mode 100644 index 00000000000..e64d4d8d873 --- /dev/null +++ b/api-ref/source/v3/samples/services-disable-log-response.json @@ -0,0 +1,8 @@ +{ + "disabled": true, + "status": "disabled", + "host": "devstack@lvmdriver-1", + "service": "", + "binary": "cinder-volume", + "disabled_reason": "test" +} diff --git a/api-ref/source/v3/samples/services-disable-request.json b/api-ref/source/v3/samples/services-disable-request.json new file mode 100644 index 00000000000..f7aff7bbf70 --- /dev/null +++ b/api-ref/source/v3/samples/services-disable-request.json @@ -0,0 +1,4 @@ +{ + "binary": "cinder-volume", + "host": "devstack@lvmdriver-1" +} diff --git a/api-ref/source/v3/samples/services-disable-response.json b/api-ref/source/v3/samples/services-disable-response.json new file mode 100644 index 00000000000..a46fbfe532c --- /dev/null +++ b/api-ref/source/v3/samples/services-disable-response.json @@ -0,0 +1,7 @@ +{ + "disabled": true, + "status": "disabled", + "host": "devstack@lvmdriver-1", + "service": "", + "binary": "cinder-volume" +} diff --git a/api-ref/source/v3/samples/services-enable-request.json b/api-ref/source/v3/samples/services-enable-request.json new file mode 100644 index 00000000000..f7aff7bbf70 --- /dev/null +++ b/api-ref/source/v3/samples/services-enable-request.json @@ -0,0 +1,4 @@ +{ + "binary": "cinder-volume", + "host": "devstack@lvmdriver-1" +} diff --git a/api-ref/source/v3/samples/services-enable-response.json b/api-ref/source/v3/samples/services-enable-response.json new file mode 100644 index 00000000000..f2500ff87e8 --- /dev/null +++ b/api-ref/source/v3/samples/services-enable-response.json @@ -0,0 +1,8 @@ +{ + "disabled": false, + "status": "enabled", + "host": "devstack@lvmdriver-1", + "service": "", + "binary": "cinder-volume", + "disabled_reason": null +} diff --git a/api-ref/source/v3/samples/services-failover-host-request.json b/api-ref/source/v3/samples/services-failover-host-request.json new file mode 100644 index 00000000000..ddcfd84d6bb --- /dev/null +++ b/api-ref/source/v3/samples/services-failover-host-request.json @@ -0,0 +1,4 @@ +{ + "host": "devstack@lvmdriver-1", + "backend_id": null +} diff --git a/api-ref/source/v3/samples/services-freeze-request.json b/api-ref/source/v3/samples/services-freeze-request.json new file mode 100644 index 00000000000..b67fccc05bc --- /dev/null +++ b/api-ref/source/v3/samples/services-freeze-request.json @@ -0,0 +1,3 @@ +{ + "host": "devstack@rbd-sas" +} diff --git a/api-ref/source/v3/samples/services-get-log-request.json b/api-ref/source/v3/samples/services-get-log-request.json new file mode 100644 index 00000000000..ffac2cb22a9 --- /dev/null +++ b/api-ref/source/v3/samples/services-get-log-request.json @@ -0,0 +1,5 @@ +{ + "binary": "cinder-volume", + "server": "devstack@lvmdriver-1", + "prefix": "cinder.volume" +} diff --git a/api-ref/source/v3/samples/services-get-log-response.json b/api-ref/source/v3/samples/services-get-log-response.json new file mode 100644 index 00000000000..03af716d95d --- /dev/null +++ b/api-ref/source/v3/samples/services-get-log-response.json @@ -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" + } + }] +} diff --git a/api-ref/source/v3/samples/services-list-response.json b/api-ref/source/v3/samples/services-list-response.json new file mode 100644 index 00000000000..c720da903e9 --- /dev/null +++ b/api-ref/source/v3/samples/services-list-response.json @@ -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 + }] +} diff --git a/api-ref/source/v3/samples/services-set-log-request.json b/api-ref/source/v3/samples/services-set-log-request.json new file mode 100644 index 00000000000..aeb073aa9b9 --- /dev/null +++ b/api-ref/source/v3/samples/services-set-log-request.json @@ -0,0 +1,6 @@ +{ + "binary": "cinder-volume", + "server": "devstack@lvmdriver-1", + "prefix": "cinder.volume", + "level": "ERROR" +} diff --git a/api-ref/source/v3/samples/services-thaw-request.json b/api-ref/source/v3/samples/services-thaw-request.json new file mode 100644 index 00000000000..b67fccc05bc --- /dev/null +++ b/api-ref/source/v3/samples/services-thaw-request.json @@ -0,0 +1,3 @@ +{ + "host": "devstack@rbd-sas" +}