nova/api-ref/source
Rafael Weingärtner 01f0424930 Enhance simple usage API documentation
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
2020-12-07 17:38:37 -03:00
..
conf.py Fix pygments_style 2020-05-20 21:56:41 +02:00
diagnostics.inc Fixed some nits for microversion 2.48 2017-06-06 13:34:17 +00:00
extensions.inc api-ref: Fix a broken link 2019-07-05 13:24:18 +09:00
flavors.inc Multiple API cleanup changes 2019-08-12 08:52:38 -05:00
images.inc Keep pre-commit inline with hacking and fix whitespace 2019-12-12 14:56:39 +00:00
index.rst api-ref: Move 'os-agents' API to obsolete section 2020-11-17 11:25:07 +00:00
ips.inc API Ref: update server_id params 2016-11-11 14:01:51 -05:00
limits.inc api-ref: sort parameters for limits, quotas and quota classes 2017-12-18 13:40:13 -05:00
metadata.inc Make metadata doc more readable 2017-03-31 06:19:01 +00:00
os-agents.inc api: Remove 'os-agents' API 2020-09-11 14:10:32 +01:00
os-aggregates.inc Add image caching API for aggregates 2019-10-15 21:22:31 -04:00
os-assisted-volume-snapshots.inc libvirt: remove glusterfs volume driver 2017-05-19 14:51:42 -04:00
os-availability-zone.inc Stop using "nova" in API samples when creating a server 2019-03-01 10:43:08 -05:00
os-baremetal-nodes.inc Update api-ref location 2019-07-22 19:17:28 +02:00
os-cells.inc Remove '/os-cells' REST APIs 2019-04-16 18:26:13 +01:00
os-certificates.inc Remove "DEPRECATED" tag from Obsolete APIs 2018-07-18 22:23:45 -04:00
os-cloudpipe.inc Correct project/user id descriptions for os-instance-actions 2019-07-22 15:23:16 -04:00
os-consoles.inc Remove 'os-consoles' API 2019-11-22 16:09:36 +00:00
os-fixed-ips.inc Remove "DEPRECATED" tag from Obsolete APIs 2018-07-18 22:23:45 -04:00
os-flavor-access.inc Verify project id for flavor access calls 2017-05-04 18:23:17 -04:00
os-flavor-extra-specs.inc api-ref: fix link to flavor extra specs docs 2019-02-06 14:49:18 -05:00
os-floating-ip-dns.inc Remove needs:* todo from deprecated APIs api-ref 2019-06-28 19:09:31 +00:00
os-floating-ip-pools.inc nova-net: Update API reference guide 2020-01-22 13:50:30 +00:00
os-floating-ips-bulk.inc Remove "DEPRECATED" tag from Obsolete APIs 2018-07-18 22:23:45 -04:00
os-floating-ips.inc nova-net: Update API reference guide 2020-01-22 13:50:30 +00:00
os-fping.inc Remove "DEPRECATED" tag from Obsolete APIs 2018-07-18 22:23:45 -04:00
os-hosts.inc Update the documentation links 2017-11-28 11:07:36 +08:00
os-hypervisors.inc Update api-ref location 2019-07-22 19:17:28 +02:00
os-instance-actions.inc Add instance actions v284 samples test 2020-03-30 03:02:31 +00:00
os-instance-usage-audit-log.inc api-ref: Fix description of os-instance-usage-audit-log 2016-12-14 11:22:50 -05:00
os-interface.inc Add microversion to expose virtual device tags 2019-02-21 13:38:51 +00:00
os-keypairs.inc trivial: Rename directory for os-keypairs samples 2020-03-06 16:57:46 +00:00
os-migrations.inc Filter migrations by user_id/project_id 2019-10-14 11:35:11 -07:00
os-networks.inc Remove (most) '/os-networks' REST APIs 2019-11-18 16:25:47 +00:00
os-quota-class-sets.inc api-ref: sort parameters for limits, quotas and quota classes 2017-12-18 13:40:13 -05:00
os-quota-sets.inc api-ref: sort parameters for limits, quotas and quota classes 2017-12-18 13:40:13 -05:00
os-security-group-default-rules.inc Remove 'os-security-group-default-rules' REST API 2019-11-18 16:25:47 +00:00
os-security-group-rules.inc Update api-ref location 2019-07-22 19:17:28 +02:00
os-security-groups.inc Update api-ref location 2019-07-22 19:17:28 +02:00
os-server-external-events.inc Nix os-server-external-events 404 condition 2019-12-09 11:52:49 -06:00
os-server-groups.inc Add microversion info in the os-server-groups API samples 2018-08-07 22:47:44 +00:00
os-server-password.inc API Ref: update server_id params 2016-11-11 14:01:51 -05:00
os-server-tags.inc api-ref: Remove unnecessary minimum microversion 2018-10-25 16:37:21 +09:00
os-services.inc Block deleting compute services with in-progress migrations 2019-11-14 14:29:58 -05:00
os-simple-tenant-usage.inc Enhance simple usage API documentation 2020-12-07 17:38:37 -03:00
os-tenant-network.inc Remove '/os-tenant-networks' REST API 2019-11-22 16:03:11 +00:00
os-virtual-interfaces.inc Remove "DEPRECATED" tag from Obsolete APIs 2018-07-18 22:23:45 -04:00
os-volume-attachments.inc Allow PUT volume attachments API to modify delete_on_termination 2020-04-02 09:26:55 -07:00
os-volumes.inc Keep pre-commit inline with hacking and fix whitespace 2019-12-12 14:56:39 +00:00
parameters.yaml compute: Validate a BDMs disk_bus when provided 2020-07-29 16:05:48 +00:00
request-ids.inc Update api-ref location 2019-07-22 19:17:28 +02:00
server-migrations.inc Merge "Add support matrix for Delete (Abort) on-going live migration" 2019-11-13 23:43:52 +00:00
server-security-groups.inc api-ref: Fix parameters in server-security-groups 2017-07-10 14:02:13 +00:00
server-topology.inc api-ref: fix server topology "host_numa_node" field param name 2019-09-06 17:31:42 -04:00
servers-action-console-output.inc Fix 'server' and 'instance' occurrence in api-ref 2017-03-28 02:54:11 +00:00
servers-action-crash-dump.inc remove /v2.1/{tenant_id} from all urls 2016-06-03 08:47:33 -04:00
servers-action-deferred-delete.inc remove /v2.1/{tenant_id} from all urls 2016-06-03 08:47:33 -04:00
servers-action-evacuate.inc docs: Add evacuation pre-conditions around the src host 2020-05-06 10:57:59 +01:00
servers-action-fixed-ip.inc Deprecate Multinic, floatingip action and os-virtual-interface API 2017-04-25 12:04:05 -04:00
servers-action-remote-consoles.inc Remove 'nova-xvpvncproxy' 2019-12-23 14:20:28 +00:00
servers-action-shelve.inc Specify availability_zone to unshelve 2019-08-27 12:57:10 -04:00
servers-actions.inc api-ref: re-work resize action post-conditions 2019-10-29 12:56:59 -04:00
servers-admin-action.inc virt: Remove 'reset_network' API 2020-11-23 15:55:50 +00:00
servers-remote-consoles.inc Remove 'nova-xvpvncproxy' 2019-12-23 14:20:28 +00:00
servers.inc Non-Admin user can filter their instances by more filters 2020-03-15 17:35:49 +01:00
urls.inc [api-ref] Minor text clean-up, formatting 2016-11-29 12:31:46 -05:00
versions.inc Update api-ref location 2019-07-22 19:17:28 +02:00