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