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:

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 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.

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.