Spec: Add a v2 API endpoint to retrieve the state of different scopes

See "specs/train/add_get_scope_state_api_endpoint.rst" for details.

Change-Id: I748ee949a6890b52e2844a51e371a22e40ff18c1
Story: 2005395
Task: 30792
This commit is contained in:
Luka Peschke 2019-05-09 15:06:05 +02:00
parent df4d9cbd10
commit ea093e834d
1 changed files with 185 additions and 0 deletions

View File

@ -0,0 +1,185 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===============================================================
Add a v2 API endpoint to retrieve the state of different scopes
===============================================================
https://storyboard.openstack.org/#!/story/2005395
.. note:: This spec is the detailled implementation of one part of a
larger spec. If you haven't read it yet, please see
https://review.opendev.org/#/c/657393/
Problem Description
===================
For now, there is no way for admins to know until which date a scope's data has
been processed, except by looking at the ``cloudkitty_storage_states`` SQL
table. This is, however, critical information to have before an invoice/report
is generated, as you have to make sure that the whole period you're billing
for has been processed.
Proposed Change
===============
This information should be made available through the API. This describes a
V2 API endpoint. It will only be available to admins.
Alternatives
------------
None.
Data model impact
-----------------
None.
REST API impact
---------------
This will add an endpoint on ``/v2/scope`` with support for the ``GET``
HTTP method.
A ``GET`` request on this endpoint returns a paginated list of all scopes,
with support for optional filters on the scope, the fetcher, the collector
and/or the scope_key.
The method will support the following parameters:
* ``offset``: (optional, defaults to 0) The offset of the first scope that
should be returned.
* ``limit``: (optional, defaults to 100) The maximal number or results to
return.
* ``scope_id``: (optional) Can be specified several times. One or several
scope_ids to filter on.
* ``collector``: (optional) Can be specified several times. One or several
collectors to filter on.
* ``fetcher``: (optional) Can be specified several times. One or several
fetchers to filter on.
* ``scope_key``: (optional) Can be specified several times. One or several
scope_keys to filter on.
The response will have the following format:
.. code-block:: javascript
{
"results": [
{
"collector": "gnocchi",
"fetcher": "keystone",
"scope_id": "7a7e5183264644a7a79530eb56e59941",
"scope_key": "project_id",
"state": "2019-05-09 10:00:00"
},
{
"collector": "gnocchi",
"fetcher": "keystone",
"scope_id": "9084fadcbd46481788e0ad7405dcbf12",
"scope_key": "project_id",
"state": "2019-05-08 03:00:00"
},
{
"collector": "gnocchi",
"fetcher": "keystone",
"scope_id": "1f41d183fca5490ebda5c63fbaca026a",
"scope_key": "project_id",
"state": "2019-05-06 22:00:00"
}
]
}
The expected HTTP success response code for a ``GET`` request on this endpoint
is ``200 OK``.
Expected HTTP error response codes for a ``GET`` request on this endpoint are:
* ``400 Bad Request``: Malformed request.
* ``403 Forbidden``: The user hasn't the necessary rights to retrieve the state of
the scopes.
* ``404 Not Found``: No scope was found for the provided filters.
This endpoint will only be authorized for admins.
Security impact
---------------
Any user with access to this endpoint will be able to retrieve information about
the state of all scopes rated by cloudkitty. Thus, access to this endpoint should
be granted to non-admin users with parsimony.
Notifications Impact
--------------------
None.
Other end user impact
---------------------
The client will also be updated in order to include a function and a CLI command
allowing to retrieve information about the state of the different scopes.
Performance Impact
------------------
None.
Other deployer impact
---------------------
Scope state information will be easier to retrieve for admins and deployers.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
<peschk_l>
Work Items
----------
* Implement the API endpoint with unit tests
* Add tempest tests
* Support this endpoint in the client.
Dependencies
============
None.
Testing
=======
Tempest tests for this endpoint will be added.
Documentation Impact
====================
The endpoint will be added to the API reference.
References
==========
Spec to get/reset the state of a scope: https://review.opendev.org/#/c/657393/