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
Microversion 2.40 added paging to simple tenant usage, complete with
"next" links, but the api-ref response documentation wasn't updated to
include them.
Change-Id: Iaf2d71cc45b896ccb00271fd455befd24f1efadd
Closes-Bug: #1651254
Add optional parameters 'limit' and 'marker' to the
os-simple-tenant-usage endpoints for pagaination.
/os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
/os-simple-tenant-usage/{tenant}?limit={limit}&marker={instance_uuid}
The aggregate usage totals may no longer reflect all instances for a
tenant, but rather just the instances for a given page. API consumers
will need to stitch the aggregate data back together (add the totals)
if a tenant's instances span several pages.
Implements blueprint paginate-simple-tenant-usage
Change-Id: Ic8e9f869f1b855f968967bedbf77542f287f26c0
As discussed at summit, the version part of the URL is not really
relevant, or a thing a user should be filling out themselves, this
should instead be set by the service catalog and extracted from the
token.
This removes it's reference in all documented REST urls, and adds a
new section describing how one gets the base URL for all calls.
Change-Id: I4306b8c3de0225e54f3909dd8a1fb293c4e5944c
verified the API doc for os-simple-tenant-usage,
remove some common error code like 500, 503 etc
Part of bp:api-ref-in-rst
Change-Id: I90d6899cdb9dc9983fdbfd5156b369ab2fb88226
This adds a set of tags in comments to the beginning of files so that
we can process them according to the documentation here:
https://wiki.openstack.org/wiki/NovaAPIRef
Part of bp:api-ref-in-rst
Change-Id: I17cf584dafb5bd969c12f51b7e7185d92365bf93
This fixes more api samples references which were autogenerated
incorrectly, and brings our api-ref warnings down to 175.
It also removes the os-volume-types API references, which turns out to
be a complete work of fiction, and never existed.
Part of bp:api-ref-in-rst
Change-Id: I1395c5e5986d8810ed91e9c9f132ec04f620497c
Heading for json response example is wrong,
it is json request instead of json response.
Part of bp:api-ref-in-rst
Change-Id: I709b2bf19520eb76e0264c358a2146bb0dbcee2b
In the sphinx document h3 is supposed to be '-' not '^':
=, for sections
-, for subsections
^, for subsubsections
We have to enforce consistency here because we're processing included
files which all have to agree, otherwise it's a sphinx error.
Part of bp:api-ref-in-rst
Change-Id: Ic6eef5cacb07870f161b04b031e332f2b87aeedc
This is the results of the RST conversion from WADL. It creates a
single index plus a bunch of included files which represent sections
of the API document. This is the starting point for fixing the
documentation.
Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
