9.6 KiB
List introspection statuses
List introspection statuses RFE
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.
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.
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.
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.
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 unfinishedstate: <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-likestarted_at=<op>:<time>[&started_at=...]
filtering, time intervalfinished_at=(<op>:<time>)|null[&finished_at=...]
filtering, time interval
Response codes:
- Normal http response code:
200
400
for an invalid query string404
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 50GET@/v1/introspection?finished_at=ge:15:30&state=error&sort=error:asc
only error introspections since 15:30 Today, alphabetically sorted by the error messageGET@/v1/introspection?finished_at=null
pending introspectionsGET@/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.
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