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:
parent
d959e4b1ba
commit
818c8d3a92
299
specs/list-introspection-statuses.rst
Normal file
299
specs/list-introspection-statuses.rst
Normal 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
|
Loading…
Reference in New Issue
Block a user