Endpoint to list introspection statuses

This patch suggests a spec file describing such an endpoint.

APIImpact

Change-Id: I4efab67cbb798399d18ec82708bbed52dc9d3b70
Partial-Bug: #1525238
This commit is contained in:
dparalen 2016-09-22 20:15:34 +02:00
parent d959e4b1ba
commit 818c8d3a92

View File

@ -0,0 +1,299 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================
List introspection statuses
===========================
`List introspection statuses RFE`_
.. _List introspection statuses RFE: https://bugs.launchpad.net/ironic-\
inspector/+bug/1525238
There is no way a user can get the list of all introspection statuses from the
ironic inspector service besides first fetching a list of nodes from the ironic
service. The ironic inspector misses an API endpoint to serve this information.
The purpose of this spec is to describe such an endpoint.
Problem description
===================
A user should be able to obtain a list of introspection statuses managed by
ironic inspector through a dedicated API endpoint. The introspection status
list item should provide *basic* status information about particular node
introspection status and a link to the full introspection status endpoint. The
list of the status items should be `paginated`_. It should be possible to
filter the status list based on the ``started_at``, ``finished_at`` and
``state`` node introspection status attributes.
.. _paginated: http://developer.openstack.org/api-ref/baremetal/index.html\
?expanded=list-nodes-detail#list-nodes
Proposed change
===============
The endpoint should reside at ``GET@/v1/introspection`` path yielding the list
of introspection statuses, encoded in *JSON*. The endpoint should consider
these queries affecting the pagination and filtering of the list:
Pagination
----------
``?marker=<uuid>&limit=<number>`` The default and maximum value of the limit
query is configurable as ``CONF.api_max_limit = 1000``. The default ordering of
the resources for the pagination is based on the ``started_at, uuid`` tuple,
newer items first. The pagination is always in effect to avoid exhausting
server resources. With no marker specified, the user always receives first
``CONF.api_max_limit`` statuses. Sorting keys can be changed through the query
``?sort=<key[:asc|desc]>[,<key[:asc|desc]>...]``. The key can be any of the
``started_at, finished_at, state, error, uuid`` attributes. It is possible to
change the `sorting direction`_ through the ``[:asc|desc]`` sort key query
direction suffix.
.. _sorting direction: https://specs.openstack.org/openstack/openstack-specs/\
specs/cli-sorting-args.html
State query
-----------
``?state=<op>:<state_name>[,<state_name>...]`` Only return items matching the
states specified; acts as a *set*. Allowed operators: ``=in: =nin:`` the latter
meaning not in. Recognized state name values are as per the `HA Inspector
spec`_ and as further amended with the `introspection state patch`_:
``starting, waiting, processing, finished, reapplying, enrolling, error``.
Just the first occurrence of the ``state`` query string field is considered,
any repetitions are ignored.
.. _HA inspector spec: https://specs.openstack.org/openstack/ironic-inspector
-specs/specs/HA_inspector.html
.. _introspection state patch: https://review.openstack.org/#/c/348943/
Time query
----------
* ``?started_at=<op>:<time>[&started_at=...]``
* ``?finished_at=(<op>:<time>)|null[&finished_at=...]``
Return only items in specified time intervals. Values are `ISO8601 time stamp`_
The default value ``finished_at=null`` meaning unfinished introspections.
Allowed operators are: ``=gt: =ge: =lt: =le:`` See also the `API working group
filtering specification`_.
.. _ISO8601 time stamp: https://en.wikipedia.org/wiki/ISO_8601
.. _API working group filtering specification: http://specs.openstack.org/\
openstack/api-wg/guidelines/\
pagination_filter_sort.html\
#time-based-filtering-queries
Status item
-----------
The basic information about a node introspection status the endpoint serves,
encoded in a JSON dictionary with these items:
* ``uuid: <node_uuid>``
* ``finished: true|false``
* ``started_at: <time>``
* ``finished_at: <time>|null`` the latter in case unfinished
* ``state: <state_name>``
* ``links``: a dictionary with the items:
* ``href: <introspection_url>``
* ``rel: self``
Alternatives
------------
Maintain the status quo of fetching all nodes from the ironic service before
visiting each node in the inspector service to obtain the node introspection
status.
Data model impact
-----------------
None
HTTP API impact
---------------
Get list of introspection statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With pagination and filtering:
* Method: ``GET``
* Path: ``/v1/introspection``
Optional query string fields:
* ``?marker=<uuid>&limit=<number>`` pagination
* ``?sort=<key[:asc|desc]>[&sort=...]`` pagination, sorting keys
* ``?state=<op>:<state_name>[,<state_name>...]`` filtering, set-like
* ``started_at=<op>:<time>[&started_at=...]`` filtering, time interval
* ``finished_at=(<op>:<time>)|null[&finished_at=...]`` filtering, time
interval
Response codes:
* Normal http response code: ``200``
* ``400`` for an invalid query string
* ``404`` marker not found or invalid state
JSON schema definition for the response data::
[
{
'uuid': '<node_uuid>',
'state': '<state_name>,
'finished': true/false,
'started_at': '<time>',
'finished_at': '<time>'|null,
'links': [{
'href': '<url_to_node_uuid_introspection_detail>',
'rel: 'self'
}]
},
...
]
Example use cases:
* ``GET@/v1/introspection?finished_at=2016-09-21/&limit=50`` all introspections
finished after 29th of September, 00:00 UTC, no matter the state, limited to
50
* ``GET@/v1/introspection?finished_at=ge:15:30&state=error&sort=error:asc``
only error introspections since 15:30 Today, alphabetically
sorted by the error message
* ``GET@/v1/introspection?finished_at=null``
pending introspections
* ``GET@/v1/introspection?started_at=ge:15:30&state=waiting``
introspections that have been waiting since 15:30 Today
Client (CLI) impact
-------------------
This change should be adopted by the python ironic inspector client project as
well. The CLI should include a new subcommand with optional switches reflecting
the API optional queries::
openstack baremetal introspection statuses \
[--states=<op>:<state_name>[,<state_name>...]]
[--started-at=(<op>:<time>)[,<op>:<time>...]]
[--finished-at=(<op>:<time>)|null[,(<op>:<time>)|null...]]
[--marker=<node_uuid>]
[--limit=<number>]
[--sort=<key[:asc|desc]>[,<key[:asc|desc]>...]]
Without the pagination parameters, the command should return a complete list.
The output should be formatted in a table as is usual for the ``openstack``
commands.
Ironic python agent impact
--------------------------
None
Performance and scalability impact
----------------------------------
Filtering together with the pagination may have positive effect on the
server-side resources utilization.
Security impact
---------------
None
Deployer impact
---------------
Due to the `Pagination`_, a new config option ``CONF.api_max_limit = 1000`` is
introduced to limit the amount of items an API endpoint can return in a single
request. This is to prevent server resource exhaustion.
This new endpoint has an immediate impact and cannot be switched off in the
ironic inspector service.
Existing API clients, such as the python ironic inspector client, should
continue working without any impact as the endpoint is new. Those would of
course miss the feature altogether.
The deployer is advised to update both the server and client sides, preferably
in that order.
Developer impact
----------------
Developers are suggested to adopt this endpoint instead of having to retrieve
list of nodes from the ironic service before obtaining introspection statuses
from the inspector service.
Implementation
==============
Assignees
---------
* Milan Kovacik, #milan, <vetrisko>
* Dmitry Tantsur, #dtantsur, <divius>
Primary assignee: <vetrisko>
Work Items
----------
This feature can be implemented in more patches, for instance, landing
pagination before state-based and time-based filtering might make the most
sense for both the ironic inspector and python ironic inspector client
projects.
A `partial implementation`_ of the status list API endpoint for the ironic
inspector project is currently blocked by this specification landing. It
supports time-based filtering and pagination already.
.. _partial implementation: https://review.openstack.org/#/c/344921
Dependencies
============
This feature can be implemented without any dependencies although it would be
reasonable to depend on the `introspection state patch`_ to limit code
rewrites.
Testing
=======
Functional and unit-testing with both the ironic inspector server and python
ironic inspector client projects.
References
==========
* `List introspection statuses RFE`_
* `State query for list introspection statuses RFE`_
* `HA inspector spec`_
* `Introspection state patch`_
* `Flask query handling`_
* `Partial implementation`_ of the list API endpoint for the inspector
* `API working group filtering specification`_
* Global CLI `sorting direction`_ guidelines
.. _State query for list introspection statuses RFE: https://bugs\
.launchpad.net/\
ironic-inspector/\
+bug/1625183
.. _Flask query handling: http://flask.pocoo.org/docs/0.11/api/#flask.\
Request.args