An empty value for the 'all_tenants' query parameter of '/servers' and
'/servers/detail' means the value defaults to 'True', i.e. requesting
'/servers?all_tenants' is the same as '/servers?all_tenants=1'. Clarify
this, since the current wording is confusing.

Change-Id: Ib5fdd3b73aa5179e0379ee8f465e4118107786be
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
Closes-Bug: #1909745

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>

The 'availability_zone' description in unshelve api-ref is confusing,
adding NOTE for unshelve request body:

Since microversion 2.77, allowed request body schema are {"unshelve":
null} or {"unshelve": {"availability_zone": <string>}}. A request body
of {"unshelve":{}} is not allowed.

Closes-Bug: #1908336
Change-Id: I66c209baf11c37ffebca52764263daae9e1dd50b

This change adds some basic notes in the api-ref for a wrinkle in the
current os-volume_attachments API in that both attach and detach actions
are async, returning to the caller *before* the underlying action is
complete. As such callers need to make seperate calls to ensure these
actions complete successfully.

There are also currently two different ways of polling for completion
when attaching and detaching.

- When attaching callers should use the volume status and list of
  attachments as reported by the volume API.

- When detaching callers should instead use the list of volume attachments
  reported by the os-volume_attachments API.

This is due to the way in which Nova currently completes the attachment
via c-api last during attachment and deletes the bdm record last during
detachment.

It would be useful to one day centralise on just using the
os-volume_attachments API to poll both actions but to do that we would
need to start tracking our own state within the BDMs.

Change-Id: Id367ee53ef1458b6a90fc107ab14f5b3cbba7a86

Nova's `os-simple-tenant-usage` has the following statement.

```
Reports usage statistics of compute and storage resources periodically
for an individual tenant or all tenants. The usage statistics will
include all instances’ CPU, memory and local disk during a specific
period.

```

To some people, when reading that, they might get the understanding that
the `os-simple-tenant-usage` will report the actual use of resources.
Therefore, if a VM is stopped and then started back again, it (the
`os-simple-tenant-usage`) would only report the time the VM has been up
and running. However, that is not what happens. The
`os-simple-tenant-usage` reports the time that a virtual machine (VM)
exists in the cloud environment. Therefore, actions such as pause,
suspend, and stop do not affect the usage accounting.

This might be a problem for people using this API for billing, or for
people that use other systems (e.g. CloudKitty) for billing.
End-users might try to cross-check the data from the billing from
CloudKitty for instance, with the usage report found in Horizon that
uses this API, and the numbers will not add up, as people might only
consider the time a VM has been up and running to charge users in
CloudKitty.

An extension was proposed in [1], to allow operators to customize
the usage accounting. However, during a meeting with the community [2],
the extension was rejected for two reasons:

* Nova tries to avoid using config driven APIs. Meaning, APIs that change
  the response according to server-side configurations;
* The community has decided to get rid of usage and billing accounting
  in Nova.

Having said that, we would like to propose a documentation amendment.
The idea is to explicitly say for users/operators that the simple usage
API only considers the time that the VM existed in the cloud for the
accounting, and not the actual time it has been up and running.
This will save some misunderstanding and misuse of the API data.

References
===========
[1] https://review.opendev.org/c/openstack/nova/+/711113
[2] http://eavesdrop.openstack.org/meetings/nova/2020/nova.2020-12-03-16.00.log.txt

Closes-Bug: #1907133
Change-Id: Ic55669f5210b57f151f693393f205655765a8dc9

This one is tied into an admin action in the server actions API, which
means we must remove that API action also. Otherwise, this isn't too
crazy.

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

Follow up for change I9512f605dd2b3b0e88c951ed086250d57056303d.

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

This was only useful with XenAPI and can therefore be removed.

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

Remove references to the feature from various comments scattered
throughout the code.

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