From 7a3d34471729d618989c1407a8b3820029841876 Mon Sep 17 00:00:00 2001 From: luqitao Date: Tue, 14 Mar 2017 05:27:47 -0400 Subject: [PATCH] Adds API documentation for list and show hosts. Adds v2 and v3 API documentation for list all hosts and show host details. Change-Id: I43791fded823cd931c2d77a11fa502b2cb5f0105 Closes-Bug: #1558257 --- api-ref/source/v2/hosts.inc | 81 +++++++++++++++++++ api-ref/source/v2/index.rst | 1 + api-ref/source/v2/parameters.yaml | 24 ++++++ .../source/v2/samples/hosts-get-response.json | 22 +++++ .../v2/samples/hosts-list-response.json | 26 ++++++ api-ref/source/v3/hosts.inc | 81 +++++++++++++++++++ api-ref/source/v3/index.rst | 1 + api-ref/source/v3/parameters.yaml | 18 +++++ .../source/v3/samples/hosts-get-response.json | 22 +++++ .../v3/samples/hosts-list-response.json | 26 ++++++ 10 files changed, 302 insertions(+) create mode 100644 api-ref/source/v2/hosts.inc create mode 100644 api-ref/source/v2/samples/hosts-get-response.json create mode 100644 api-ref/source/v2/samples/hosts-list-response.json create mode 100644 api-ref/source/v3/hosts.inc create mode 100644 api-ref/source/v3/samples/hosts-get-response.json create mode 100644 api-ref/source/v3/samples/hosts-list-response.json diff --git a/api-ref/source/v2/hosts.inc b/api-ref/source/v2/hosts.inc new file mode 100644 index 00000000000..500a6911e37 --- /dev/null +++ b/api-ref/source/v2/hosts.inc @@ -0,0 +1,81 @@ +.. -*- rst -*- + +Hosts extension (os-hosts) +==================================== + +Administrators only, depending on policy settings. + +Lists, shows hosts. + + +List all hosts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/{admin_tenant_id}/os-hosts + +Lists all hosts summary info that is not disabled. + +Normal response codes: 200 +Error response codes: + +Request +------- + +.. rest_parameters:: parameters.yaml + + - admin_tenant_id: admin_tenant_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - service-status: service_status + - service: host_service + - zone: availability_zone_3 + - service-state: service_state + - host_name: hostname + - last-update: updated_at + +Response Example +---------------- + +.. literalinclude:: ./samples/hosts-list-response.json + :language: javascript + +Show Host Details +~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/{admin_tenant_id}/os-hosts/{host_name} + +Shows details for a host. + +Normal response codes: 200 + +Error response codes: unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - admin_tenant_id: admin_tenant_id + - host_name: hostname + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - volume_count: total_count + - total_volume_gb: totalGigabytesUsed + - total_snapshot_gb: totalSnapshotsUsed + - project: admin_tenant_id + - host: host + - snapshot_count: totalSnapshotsUsed + +**Example Show Host Details** + +.. literalinclude:: ./samples/hosts-get-response.json + :language: javascript diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 058c3c6ef08..435f53add84 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -12,6 +12,7 @@ Block Storage API V2 (DEPRECATED) .. include:: capabilities-v2.inc .. include:: os-cgsnapshots-v2.inc .. include:: consistencygroups-v2.inc +.. include:: hosts.inc .. include:: limits.inc .. include:: os-vol-image-meta-v2.inc .. include:: os-vol-pool-v2.inc diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 2a7f5c7efbe..41144a95718 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -590,6 +590,12 @@ host_name: in: body required: false type: string +host_service: + description: | + The name of the service which is running on the host. + in: body + required: true + type: string id: description: | The UUID of the volume transfer. @@ -1277,6 +1283,18 @@ security_groups: in: body required: true type: integer +service_state: + description: | + The state of the service. One of ``available`` or ``unavailable``. + 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 size: description: | The size of the volume, in gibibytes (GiB). @@ -1434,6 +1452,12 @@ total_capacity: in: body required: true type: string +total_count: + description: | + Total number of volumes. + in: body + required: true + type: integer totalBackupGigabytesUsed: description: | The total number of backups gibibytes (GiB) used. diff --git a/api-ref/source/v2/samples/hosts-get-response.json b/api-ref/source/v2/samples/hosts-get-response.json new file mode 100644 index 00000000000..b3e23702882 --- /dev/null +++ b/api-ref/source/v2/samples/hosts-get-response.json @@ -0,0 +1,22 @@ +{ + "host": [{ + "resource": { + "volume_count": "8", + "total_volume_gb": "11", + "total_snapshot_gb": "1", + "project": "(total)", + "host": "node1@rbd-sas", + "snapshot_count": "1" + } + }, + { + "resource": { + "volume_count": "8", + "total_volume_gb": "11", + "total_snapshot_gb": "1", + "project": "f21a9c86d7114bf99c711f4874d80474", + "host": "node1@rbd-sas", + "snapshot_count": "1" + } + }] +} diff --git a/api-ref/source/v2/samples/hosts-list-response.json b/api-ref/source/v2/samples/hosts-list-response.json new file mode 100644 index 00000000000..1ae7808982e --- /dev/null +++ b/api-ref/source/v2/samples/hosts-list-response.json @@ -0,0 +1,26 @@ +{ + "hosts": [{ + "service-status": "available", + "service": "cinder-backup", + "zone": "nova", + "service-state": "enabled", + "host_name": "node1", + "last-update": "2017-03-09T21:38:41.000000" + }, + { + "service-status": "available", + "service": "cinder-scheduler", + "zone": "nova", + "service-state": "enabled", + "host_name": "node1", + "last-update": "2017-03-09T21:38:38.000000" + }, + { + "service-status": "available", + "service": "cinder-volume", + "zone": "nova", + "service-state": "enabled", + "host_name": "node1@lvm", + "last-update": "2017-03-09T21:38:35.000000" + }] +} diff --git a/api-ref/source/v3/hosts.inc b/api-ref/source/v3/hosts.inc new file mode 100644 index 00000000000..0193a134e1d --- /dev/null +++ b/api-ref/source/v3/hosts.inc @@ -0,0 +1,81 @@ +.. -*- rst -*- + +Hosts extension (os-hosts) +==================================== + +Administrators only, depending on policy settings. + +Lists, shows hosts. + + +List all hosts for a project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v3/{admin_project_id}/os-hosts + +Lists all hosts summary info that is not disabled. + +Normal response codes: 200 +Error response codes: + +Request +------- + +.. rest_parameters:: parameters.yaml + + - admin_project_id: admin_project_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - service-status: service_status + - service: host_service + - zone: availability_zone_3 + - service-state: service_state + - host_name: hostname + - last-update: updated_at + +Response Example +---------------- + +.. literalinclude:: ./samples/hosts-list-response.json + :language: javascript + +Show Host Details for a project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v3/{admin_project_id}/os-hosts/{host_name} + +Shows details for a host. + +Normal response codes: 200 + +Error response codes: unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - admin_project_id: admin_project_id + - host_name: hostname + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - volume_count: total_count + - total_volume_gb: totalGigabytesUsed + - total_snapshot_gb: totalSnapshotsUsed + - project: admin_project_id + - host: host + - snapshot_count: totalSnapshotsUsed + +**Example Show Host Details** + +.. literalinclude:: ./samples/hosts-get-response.json + :language: javascript diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index 43bce33b175..20576e7ccd3 100644 --- a/api-ref/source/v3/index.rst +++ b/api-ref/source/v3/index.rst @@ -15,6 +15,7 @@ Block Storage API V3 (CURRENT) .. include:: groups.inc .. include:: group-snapshots.inc .. include:: group-types.inc +.. include:: hosts.inc .. include:: limits.inc .. include:: os-vol-image-meta-v3.inc .. include:: os-vol-pool-v3.inc diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 37c6222ccdf..e5e0f0fb117 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -737,6 +737,12 @@ host_name: in: body required: false type: string +host_service: + description: | + The name of the service which is running on the host. + in: body + required: true + type: string id: description: | The UUID of the volume transfer. @@ -1461,6 +1467,18 @@ security_groups: in: body required: true type: integer +service_state: + description: | + The state of the service. One of ``available`` or ``unavailable``. + 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 size: description: | The size of the volume, in gibibytes (GiB). diff --git a/api-ref/source/v3/samples/hosts-get-response.json b/api-ref/source/v3/samples/hosts-get-response.json new file mode 100644 index 00000000000..b3e23702882 --- /dev/null +++ b/api-ref/source/v3/samples/hosts-get-response.json @@ -0,0 +1,22 @@ +{ + "host": [{ + "resource": { + "volume_count": "8", + "total_volume_gb": "11", + "total_snapshot_gb": "1", + "project": "(total)", + "host": "node1@rbd-sas", + "snapshot_count": "1" + } + }, + { + "resource": { + "volume_count": "8", + "total_volume_gb": "11", + "total_snapshot_gb": "1", + "project": "f21a9c86d7114bf99c711f4874d80474", + "host": "node1@rbd-sas", + "snapshot_count": "1" + } + }] +} diff --git a/api-ref/source/v3/samples/hosts-list-response.json b/api-ref/source/v3/samples/hosts-list-response.json new file mode 100644 index 00000000000..1ae7808982e --- /dev/null +++ b/api-ref/source/v3/samples/hosts-list-response.json @@ -0,0 +1,26 @@ +{ + "hosts": [{ + "service-status": "available", + "service": "cinder-backup", + "zone": "nova", + "service-state": "enabled", + "host_name": "node1", + "last-update": "2017-03-09T21:38:41.000000" + }, + { + "service-status": "available", + "service": "cinder-scheduler", + "zone": "nova", + "service-state": "enabled", + "host_name": "node1", + "last-update": "2017-03-09T21:38:38.000000" + }, + { + "service-status": "available", + "service": "cinder-volume", + "zone": "nova", + "service-state": "enabled", + "host_name": "node1@lvm", + "last-update": "2017-03-09T21:38:35.000000" + }] +}