api: Drop statistics-style fields from os-hypervisors

Introduce API microversion 2.88, which makes the following changes to
a number of 'os-hypervisors'. Specifically, the following fields are
dropped from both the '/os-hypervisors/detail' (detailed list) and
'/os-hypervisors/{hypervisor_id}' (show) APIs:

- current_workload
- cpu_info
- vcpus
- vcpus_used
- free_disk_gb
- local_gb
- local_gb_used
- disk_available_least
- free_ram_mb
- memory_mb
- memory_mb_used
- running_vms

In addition, the '/os-hypervisors/statistics' API, which provided a
summary of the above stats but for all hypervisors in the deployment, is
dropped entirely.

Finally, the '/os-hypervisors/{hypervisor}/uptime' API, which provided a
similar response to the '/os-hypervisors/{hypervisor}' API but with an
additional 'uptime' field, has been removed in favour of including this
field in the primary '/os-hypervisors/{hypervisor}' API.

A small tweak to 'tox.ini' that allows us to share some venvs is
included.

Part of blueprint modernize-os-hypervisors-api

Change-Id: I515e484ade6c6455f82a3067940a418a0d7d965a
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

2 files changed, 90 insertions, 28 deletions

diff --git a/api-ref/source/os-hypervisors.inc b/api-ref/source/os-hypervisors.inc
index 84e67e60cd..6363b409b4 100644
--- a/api-ref/source/os-hypervisors.inc
+++ b/api-ref/source/os-hypervisors.inc
@@ -12,6 +12,7 @@ for a hypervisor, lists all servers on hypervisors that match the given
 ``hypervisor_hostname_pattern`` or searches for hypervisors by the given
 ``hypervisor_hostname_pattern``.
 
+
 List Hypervisors
 ================
 
@@ -64,6 +65,7 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-with-servers-resp.json
    :language: javascript
 
+
 List Hypervisors Details
 ========================
 
@@ -122,6 +124,7 @@ Response
   - service.id: service_id_body_2_52
   - service.id: service_id_body_2_53
   - service.disabled_reason: service_disable_reason
+  - uptime: hypervisor_uptime
   - vcpus: hypervisor_vcpus
   - vcpus_used: hypervisor_vcpus_used
   - hypervisor_links: hypervisor_links
@@ -136,13 +139,25 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-detail-resp.json
    :language: javascript
 
-Show Hypervisor Statistics
-==========================
+**Example List Hypervisors Details (v2.88): JSON response**
+
+.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.88/hypervisors-detail-resp.json
+   :language: javascript
+
+
+Show Hypervisor Statistics (DEPRECATED)
+=======================================
 
 .. rest_method:: GET /os-hypervisors/statistics
+   max_version: 2.87
 
 Shows summary statistics for all enabled hypervisors over all compute nodes.
 
+.. warning::
+
+   This API is deprecated and will fail with HTTP 404 starting with microversion
+   2.88. Use placement to get information on resource usage across hypervisors.
+
 Policy defaults enable only users with the administrative role to perform
 this operation. Cloud providers can change these permissions through
 the ``policy.json`` file.
@@ -158,7 +173,7 @@ the ``policy.json`` file.
 
 Normal response codes: 200
 
-Error response codes: unauthorized(401), forbidden(403)
+Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
 
 Response
 --------
@@ -167,7 +182,7 @@ Response
 
   - hypervisor_statistics: hypervisor_statistics
   - count: hypervisor_count
-  - current_workload: current_workload
+  - current_workload: current_workload_total
   - disk_available_least: disk_available_least_total
   - free_disk_gb: hypervisor_free_disk_gb_total
   - free_ram_mb: free_ram_mb_total
@@ -184,6 +199,7 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-hypervisors/hypervisors-statistics-resp.json
    :language: javascript
 
+
 Show Hypervisor Details
 =======================
 
@@ -249,6 +265,7 @@ Response
   - service.id: service_id_body_2_52
   - service.id: service_id_body_2_53
   - service.disabled_reason: service_disable_reason
+  - uptime: hypervisor_uptime
   - vcpus: hypervisor_vcpus
   - vcpus_used: hypervisor_vcpus_used
 
@@ -262,13 +279,26 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-show-with-servers-resp.json
    :language: javascript
 
-Show Hypervisor Uptime
-======================
+**Example Show Hypervisors Details (v2.88): JSON response**
+
+.. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.88/hypervisors-show-with-servers-resp.json
+   :language: javascript
+
+
+Show Hypervisor Uptime (DEPRECATED)
+===================================
 
 .. rest_method:: GET /os-hypervisors/{hypervisor_id}/uptime
+   max_version: 2.87
 
 Shows the uptime for a given hypervisor.
 
+.. warning::
+
+    This API is deprecated and will fail with HTTP 404 starting with
+    microversion 2.88. Use `Show Hypervisor Details`_ with microversion 2.88
+    and later to get this information.
+
 Policy defaults enable only users with the administrative role to perform
 this operation. Cloud providers can change these permissions through
 the ``policy.json`` file.
@@ -308,8 +338,9 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-hypervisors/v2.53/hypervisors-uptime-resp.json
    :language: javascript
 
-Search Hypervisor
-=================
+
+Search Hypervisor (DEPRECATED)
+==============================
 
 .. rest_method:: GET /os-hypervisors/{hypervisor_hostname_pattern}/search
    max_version: 2.52
@@ -351,8 +382,9 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-hypervisors/hypervisors-search-resp.json
    :language: javascript
 
-List Hypervisor Servers
-=======================
+
+List Hypervisor Servers (DEPRECATED)
+====================================
 
 .. rest_method:: GET /os-hypervisors/{hypervisor_hostname_pattern}/servers
    max_version: 2.52
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index cc36fcbe8a..13fbc541aa 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -2226,6 +2226,7 @@ cpu_info:
   in: body
   required: true
   type: object
+  max_version: 2.87
 create_info:
   description: |
     Information for snapshot creation.
@@ -2280,9 +2281,20 @@ createImage:
   type: object
 current_workload:
   description: |
-    The current_workload is the number of tasks the hypervisor is responsible for. This will be
-    equal or greater than the number of active VMs on the system (it can be greater when VMs
-    are being deleted and the hypervisor is still cleaning up).
+    The current_workload is the number of tasks the hypervisor is responsible
+    for. This will be equal or greater than the number of active VMs on the
+    system (it can be greater when VMs are being deleted and the hypervisor is
+    still cleaning up).
+  in: body
+  required: true
+  type: integer
+  max_version: 2.87
+current_workload_total:
+  description: |
+    The current_workload is the number of tasks the hypervisors are responsible
+    for. This will be equal or greater than the number of active VMs on the
+    systems (it can be greater when VMs are being deleted and a hypervisor is
+    still cleaning up).
   in: body
   required: true
   type: integer
@@ -2504,6 +2516,7 @@ disk_available_least:
   in: body
   required: true
   type: integer
+  max_version: 2.87
 disk_available_least_total:
   description: |
     The actual free disk on all hypervisors(in GiB). If allocation ratios used
@@ -3438,6 +3451,7 @@ free_ram_mb:
   in: body
   required: true
   type: integer
+  max_version: 2.87
 free_ram_mb_total:
   description: |
     The free RAM on all hypervisors(in MiB). This does not take allocation
@@ -3742,6 +3756,7 @@ hypervisor_free_disk_gb:
   in: body
   required: true
   type: integer
+  max_version: 2.87
 hypervisor_free_disk_gb_total:
   description: |
     The free disk remaining on all hypervisors(in GiB). This does not take
@@ -3752,8 +3767,8 @@ hypervisor_free_disk_gb_total:
   type: integer
 hypervisor_hostname:
   description: |
-    The hypervisor host name provided by the Nova virt driver. For the Ironic driver,
-    it is the Ironic node uuid.
+    The hypervisor host name provided by the Nova virt driver. For the Ironic
+    driver, it is the Ironic node uuid.
   in: body
   required: true
   type: string
@@ -3853,17 +3868,26 @@ hypervisor_type_body:
   in: body
   required: true
   type: string
+hypervisor_uptime:
+  description: |
+    The total uptime of the hypervisor and information about average load. Only
+    reported for active hosts where the virt driver supports this feature.
+  in: body
+  required: true
+  type: string
+  min_version: 2.88
 hypervisor_vcpus:
   description: |
-    The number of vcpu in this hypervisor. This does not take allocation
+    The number of vCPU in this hypervisor. This does not take allocation
     ratios used for overcommit into account so there may be disparity between
     this and the used count.
   in: body
   required: true
   type: integer
+  max_version: 2.87
 hypervisor_vcpus_total:
   description: |
-    The number of vcpu on all hypervisors. This does not take allocation
+    The number of vCPU on all hypervisors. This does not take allocation
     ratios used for overcommit into account so there may be disparity between
     this and the used count.
   in: body
@@ -3871,13 +3895,14 @@ hypervisor_vcpus_total:
   type: integer
 hypervisor_vcpus_used:
   description: |
-    The number of vcpu used in this hypervisor.
+    The number of vCPU used in this hypervisor.
   in: body
   required: true
   type: integer
+  max_version: 2.87
 hypervisor_vcpus_used_total:
   description: |
-    The number of vcpu used on all hypervisors.
+    The number of vCPU used on all hypervisors.
   in: body
   required: true
   type: integer
@@ -4480,12 +4505,13 @@ links:
   type: array
 local_gb:
   description: |
-    The disk in this hypervisor(in GiB). This does not take allocation
+    The disk in this hypervisor (in GiB). This does not take allocation
     ratios used for overcommit into account so there may be disparity between
     this and the used count.
   in: body
   required: true
   type: integer
+  max_version: 2.87
 local_gb_simple_tenant_usage:
   description: |
     The sum of the root disk size of the server and
@@ -4502,7 +4528,7 @@ local_gb_simple_tenant_usage_optional:
   type: integer
 local_gb_total:
   description: |
-    The disk on all hypervisors(in GiB). This does not take allocation
+    The disk on all hypervisors (in GiB). This does not take allocation
     ratios used for overcommit into account so there may be disparity between
     this and the used count.
   in: body
@@ -4510,13 +4536,14 @@ local_gb_total:
   type: integer
 local_gb_used:
   description: |
-    The disk used in this hypervisor(in GiB).
+    The disk used in this hypervisor (in GiB).
   in: body
   required: true
   type: integer
+  max_version: 2.87
 local_gb_used_total:
   description: |
-    The disk used on all hypervisors(in GiB).
+    The disk used on all hypervisors (in GiB).
   in: body
   required: true
   type: integer
@@ -4600,12 +4627,13 @@ memory_details_diagnostics:
   min_version: 2.48
 memory_mb:
   description: |
-    The memory of this hypervisor(in MiB). This does not take allocation
+    The memory of this hypervisor (in MiB). This does not take allocation
     ratios used for overcommit into account so there may be disparity between
     this and the used count.
   in: body
   required: true
   type: integer
+  max_version: 2.87
 memory_mb_simple_tenant_usage:
   description: |
     The memory size of the server (in MiB).
@@ -4620,7 +4648,7 @@ memory_mb_simple_tenant_usage_optional:
   type: integer
 memory_mb_total:
   description: |
-    The memory of all hypervisors(in MiB). This does not take allocation
+    The memory of all hypervisors (in MiB). This does not take allocation
     ratios used for overcommit into account so there may be disparity between
     this and the used count.
   in: body
@@ -4628,10 +4656,11 @@ memory_mb_total:
   type: integer
 memory_mb_used:
   description: |
-    The memory used in this hypervisor(in MiB).
+    The memory used in this hypervisor (in MiB).
   in: body
   required: true
   type: integer
+  max_version: 2.87
 memory_mb_used_total:
   description: |
     The memory used on all hypervisors(in MiB).
@@ -6020,13 +6049,14 @@ rules:
   type: array
 running_vms:
   description: |
-    The number of running vms on this hypervisor.
+    The number of running VMs on this hypervisor.
   in: body
   required: true
   type: integer
+  max_version: 2.87
 running_vms_total:
   description: |
-    The total number of running vms on all hypervisors.
+    The total number of running VMs on all hypervisors.
   in: body
   required: true
   type: integer