Browse Source
Add initial API reference, which covers all inspector endpoits. The conf.py and the tox environment are stolen from ironic. Co-Authored-By: Kaifeng Wang <kaifeng.w@gmail.com> Change-Id: I5009e8708dcad8ab25380f7bf574125d6e758ef5changes/52/495752/8
23 changed files with 1459 additions and 1 deletions
@ -0,0 +1,238 @@
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may |
||||
# not use this file except in compliance with the License. You may obtain |
||||
# a copy of the License at |
||||
# |
||||
# http://www.apache.org/licenses/LICENSE-2.0 |
||||
# |
||||
# Unless required by applicable law or agreed to in writing, software |
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
||||
# License for the specific language governing permissions and limitations |
||||
# under the License. |
||||
# |
||||
# ironic-inspector documentation build configuration file, created by |
||||
# sphinx-quickstart on Tue Jul 25 15:17:47 2017. |
||||
# |
||||
# This file is execfile()d with the current directory set to |
||||
# its containing dir. |
||||
# |
||||
# Note that not all possible configuration values are present in this |
||||
# autogenerated file. |
||||
# |
||||
# All configuration values have a default; values that are commented out |
||||
# serve to show the default. |
||||
|
||||
import os |
||||
import subprocess |
||||
import sys |
||||
import warnings |
||||
|
||||
import openstackdocstheme |
||||
|
||||
extensions = [ |
||||
'os_api_ref', |
||||
'openstackdocstheme', |
||||
] |
||||
|
||||
|
||||
html_theme = 'openstackdocs' |
||||
html_theme_path = [openstackdocstheme.get_html_theme_path()] |
||||
html_theme_options = { |
||||
"sidebar_dropdown": "api_ref", |
||||
"sidebar_mode": "toc", |
||||
} |
||||
html_context = {'bug_project': 'ironic-inspector', 'bug_tag': 'api-ref'} |
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory, |
||||
# add these directories to sys.path here. If the directory is relative to the |
||||
# documentation root, use os.path.abspath to make it absolute, like shown here. |
||||
sys.path.insert(0, os.path.abspath('../../')) |
||||
sys.path.insert(0, os.path.abspath('../')) |
||||
sys.path.insert(0, os.path.abspath('./')) |
||||
|
||||
# -- General configuration ---------------------------------------------------- |
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be |
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
||||
|
||||
# The suffix of source filenames. |
||||
source_suffix = '.rst' |
||||
|
||||
# The encoding of source files. |
||||
# |
||||
# source_encoding = 'utf-8' |
||||
|
||||
# The master toctree document. |
||||
master_doc = 'index' |
||||
|
||||
# openstackdocstheme options |
||||
repository_name = 'openstack/ironic-inspector' |
||||
use_storyboard = True |
||||
bug_project = 'openstack/ironic-inspector' |
||||
bug_tag = 'api-ref' |
||||
|
||||
# General information about the project. |
||||
project = 'Hardware Introspection API Reference' |
||||
copyright = '2017-present, Ironic Inspector Developers' |
||||
|
||||
# The version info for the project you're documenting, acts as replacement for |
||||
# |version| and |release|, also used in various other places throughout the |
||||
# built documents. |
||||
# |
||||
from ironic_inspector.version import version_info |
||||
# The full version, including alpha/beta/rc tags. |
||||
release = version_info.release_string() |
||||
# The short X.Y version. |
||||
version = version_info.version_string() |
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation |
||||
# for a list of supported languages. |
||||
# |
||||
# language = None |
||||
|
||||
# There are two options for replacing |today|: either, you set today to some |
||||
# non-false value, then it is used: |
||||
# today = '' |
||||
# Else, today_fmt is used as the format for a strftime call. |
||||
# today_fmt = '%B %d, %Y' |
||||
|
||||
# The reST default role (used for this markup: `text`) to use |
||||
# for all documents. |
||||
# default_role = None |
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text. |
||||
# add_function_parentheses = True |
||||
|
||||
# If true, the current module name will be prepended to all description |
||||
# unit titles (such as .. function::). |
||||
add_module_names = False |
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the |
||||
# output. They are ignored by default. |
||||
show_authors = False |
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use. |
||||
pygments_style = 'sphinx' |
||||
|
||||
# -- Options for man page output ---------------------------------------------- |
||||
|
||||
# Grouping the document tree for man pages. |
||||
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' |
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------- |
||||
|
||||
# The theme to use for HTML and HTML Help pages. Major themes that come with |
||||
# Sphinx are currently 'default' and 'sphinxdoc'. |
||||
# html_theme_path = ["."] |
||||
# html_theme = '_theme' |
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme |
||||
# further. For a list of options available for each theme, see the |
||||
# documentation. |
||||
# html_theme_options = {} |
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory. |
||||
# html_theme_path = [] |
||||
|
||||
# The name for this set of Sphinx documents. If None, it defaults to |
||||
# "<project> v<release> documentation". |
||||
# html_title = None |
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title. |
||||
# html_short_title = None |
||||
|
||||
# The name of an image file (relative to this directory) to place at the top |
||||
# of the sidebar. |
||||
# html_logo = None |
||||
|
||||
# The name of an image file (within the static path) to use as favicon of the |
||||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
||||
# pixels large. |
||||
# html_favicon = None |
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here, |
||||
# relative to this directory. They are copied after the builtin static files, |
||||
# so a file named "default.css" will overwrite the builtin "default.css". |
||||
# html_static_path = ['_static'] |
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
||||
# using the given strftime format. |
||||
# html_last_updated_fmt = '%b %d, %Y' |
||||
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", |
||||
"-n1"] |
||||
try: |
||||
html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8') |
||||
except Exception: |
||||
warnings.warn('Cannot get last updated time from git repository. ' |
||||
'Not setting "html_last_updated_fmt".') |
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to |
||||
# typographically correct entities. |
||||
# html_use_smartypants = True |
||||
|
||||
# Custom sidebar templates, maps document names to template names. |
||||
# html_sidebars = {} |
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to |
||||
# template names. |
||||
# html_additional_pages = {} |
||||
|
||||
# If false, no module index is generated. |
||||
# html_use_modindex = True |
||||
|
||||
# If false, no index is generated. |
||||
# html_use_index = True |
||||
|
||||
# If true, the index is split into individual pages for each letter. |
||||
# html_split_index = False |
||||
|
||||
# If true, links to the reST sources are added to the pages. |
||||
# html_show_sourcelink = True |
||||
|
||||
# If true, an OpenSearch description file will be output, and all pages will |
||||
# contain a <link> tag referring to it. The value of this option must be the |
||||
# base URL from which the finished HTML is served. |
||||
# html_use_opensearch = '' |
||||
|
||||
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
||||
# html_file_suffix = '' |
||||
|
||||
# Output file base name for HTML help builder. |
||||
htmlhelp_basename = 'IronicInspectorAPIRefdoc' |
||||
|
||||
|
||||
# -- Options for LaTeX output ------------------------------------------------- |
||||
|
||||
# The paper size ('letter' or 'a4'). |
||||
# latex_paper_size = 'letter' |
||||
|
||||
# The font size ('10pt', '11pt' or '12pt'). |
||||
# latex_font_size = '10pt' |
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples |
||||
# (source start file, target name, title, author, documentclass |
||||
# [howto/manual]). |
||||
latex_documents = [ |
||||
('index', |
||||
'%s.tex' % project, |
||||
u'OpenStack Hardware Introspection API Documentation', |
||||
u'OpenStack Foundation', 'manual'), |
||||
] |
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of |
||||
# the title page. |
||||
# latex_logo = None |
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts, |
||||
# not chapters. |
||||
# latex_use_parts = False |
||||
|
||||
# Additional stuff for the LaTeX preamble. |
||||
# latex_preamble = '' |
||||
|
||||
# Documents to append as an appendix to all manuals. |
||||
# latex_appendices = [] |
||||
|
||||
# If false, no module index is generated. |
||||
# latex_use_modindex = True |
@ -0,0 +1,12 @@
|
||||
:tocdepth: 2 |
||||
|
||||
========================================= |
||||
Hardware Introspection for Bare Metal API |
||||
========================================= |
||||
|
||||
.. rest_expand_all:: |
||||
|
||||
.. include:: introspection-api-versions.inc |
||||
.. include:: introspection-api-v1-introspection.inc |
||||
.. include:: introspection-api-v1-continue.inc |
||||
.. include:: introspection-api-v1-rules.inc |
@ -0,0 +1,68 @@
|
||||
.. -*- rst -*- |
||||
|
||||
========================== |
||||
Process introspection data |
||||
========================== |
||||
|
||||
After the ramdisk collects the required information from the bare metal |
||||
node, it should post it back to Inspector via ``POST /v1/continue`` method. |
||||
|
||||
|
||||
.. warning:: |
||||
Operators are reminded not to expose the Ironic Inspector API to |
||||
unsecured networks. Below method is available to *unauthenticated* |
||||
clients because **ironic-python-agent** ramdisk does not have access to |
||||
keystone credentials. |
||||
|
||||
|
||||
Ramdisk Callback |
||||
================ |
||||
|
||||
.. rest_method:: POST /v1/continue |
||||
|
||||
It is internal method for the ramdisk to post back all discovered data. |
||||
This should not be used for anything other than the ramdisk. |
||||
|
||||
Full list of hardware inventory keys may be found in **ironic-python-agent** |
||||
documentation: `hardware inventory <https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory>`_. |
||||
|
||||
Normal response codes: 201 |
||||
|
||||
Error codes: 400 |
||||
|
||||
Request |
||||
------- |
||||
|
||||
List of mandatory hardware keys: |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- inventory: inventory |
||||
- memory: memory |
||||
- cpu: cpu |
||||
- bmc_address: bmc_address |
||||
- interfaces: interfaces |
||||
- disks: disks |
||||
- root_disk: root_disk |
||||
- boot_interface: boot_interface |
||||
- logs: logs |
||||
|
||||
**Example node introspection continue request:** |
||||
|
||||
.. literalinclude:: samples/api-v1-continue-request.json |
||||
:language: javascript |
||||
|
||||
|
||||
Response |
||||
-------- |
||||
|
||||
The response will contain Ironic node ``uuid`` record. |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- uuid: node_uuid |
||||
|
||||
**Example JSON representation:** |
||||
|
||||
.. literalinclude:: samples/api-v1-common-node-uuid.json |
||||
:language: javascript |
@ -0,0 +1,226 @@
|
||||
.. -*- rst -*- |
||||
|
||||
================== |
||||
Node Introspection |
||||
================== |
||||
|
||||
Start, abort introspection, get introspection status, get introspection data |
||||
are done through the ``/v1/introspection`` resource. There are also several |
||||
sub-resources, which allow further actions to be performed on introspection. |
||||
|
||||
Start Introspection |
||||
=================== |
||||
|
||||
.. rest_method:: POST /v1/introspection/{node_id} |
||||
|
||||
Initiate hardware introspection for node {node_id} . All power management |
||||
configuration for this node needs to be done prior to calling the endpoint. |
||||
|
||||
In case missing or invalid authentication response code will be 401 and 403. |
||||
If Inspector don't find node {node_id}, it will return 404. |
||||
|
||||
Normal response codes: 202 |
||||
|
||||
Error codes: 400, 401, 403, 404 |
||||
|
||||
|
||||
Request |
||||
------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- node_id: node_id |
||||
- manage_boot: manage_boot |
||||
|
||||
|
||||
Response |
||||
-------- |
||||
|
||||
The response will be empty body. |
||||
|
||||
Get Introspection status |
||||
======================== |
||||
|
||||
.. rest_method:: GET /v1/introspection/{node_id} |
||||
|
||||
Get node introspection status. |
||||
|
||||
In case missing or invalid authentication response code will be 401 and 403. |
||||
If Inspector don't find node {node_id}, it will return 404. |
||||
|
||||
Normal response codes: 200 |
||||
|
||||
Error codes: 400, 401, 403, 404 |
||||
|
||||
Request |
||||
------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- node_id: node_id |
||||
|
||||
|
||||
Response |
||||
-------- |
||||
|
||||
The response will contain the complete introspection info, like |
||||
create, finish time, introspection state, errors if any. |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- error: error |
||||
- finished: finished |
||||
- finished_at: finished_at |
||||
- links: links |
||||
- started_at: started_at |
||||
- state: state |
||||
- uuid: node_id |
||||
|
||||
**Example JSON representation of an introspection:** |
||||
|
||||
.. literalinclude:: samples/api-v1-get-introspection-response.json |
||||
:language: javascript |
||||
|
||||
|
||||
List All Introspection statuses |
||||
=============================== |
||||
|
||||
.. rest_method:: GET /v1/introspection/ |
||||
|
||||
Returned status list is sorted by the ``started_at, uuid`` attribute pair, |
||||
newer items first. |
||||
|
||||
In case missing or invalid authentication response code will be 401 and 403. |
||||
|
||||
Normal response codes: 200 |
||||
|
||||
Error codes: 400, 401, 403 |
||||
|
||||
Request |
||||
------- |
||||
|
||||
Status list may be paginated with these query string fields: |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- marker: marker |
||||
- limit: limit |
||||
|
||||
|
||||
Response |
||||
-------- |
||||
|
||||
The response will contain a list of status objects: |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- error: error |
||||
- finished: finished |
||||
- finished_at: finished_at |
||||
- links: links |
||||
- started_at: started_at |
||||
- state: state |
||||
- uuid: node_id |
||||
|
||||
|
||||
**Example JSON representation of an introspection:** |
||||
|
||||
.. literalinclude:: samples/api-v1-get-introspections-response.json |
||||
:language: javascript |
||||
|
||||
|
||||
Abort Introspection |
||||
=================== |
||||
|
||||
.. rest_method:: POST /v1/introspection/{node_id}/abort |
||||
|
||||
Abort running introspection. |
||||
|
||||
Normal response codes: 202 |
||||
|
||||
Error codes: |
||||
|
||||
* 400 - bad request |
||||
* 401, 403 - missing or invalid authentication |
||||
* 404 - node cannot be found |
||||
* 409 - inspector has locked this node for processing |
||||
|
||||
Request |
||||
------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- node_id: node_id |
||||
|
||||
|
||||
Get Introspection data |
||||
====================== |
||||
|
||||
.. rest_method:: GET /v1/introspection/{node_id}/data |
||||
|
||||
Return stored data from successful introspection. |
||||
|
||||
.. note:: |
||||
We do not provide any backward compatibility guarantees regarding the |
||||
format and contents of the stored data. Notably, it depends on the ramdisk |
||||
used and plugins enabled both in the ramdisk and in inspector itself. |
||||
|
||||
Normal response codes: 200 |
||||
|
||||
Error codes: |
||||
|
||||
* 400 - bad request |
||||
* 401, 403 - missing or invalid authentication |
||||
* 404 - data cannot be found or data storage not configured |
||||
|
||||
Request |
||||
------- |
||||
|
||||
Status list may be paginated with these query string fields: |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- node_id: node_id |
||||
- limit: limit |
||||
|
||||
|
||||
Response |
||||
-------- |
||||
|
||||
The response will contain introspection data in the form of json string. |
||||
|
||||
**Example JSON representation of an introspection data:** |
||||
|
||||
.. literalinclude:: samples/api-v1-data-introspection-response.json |
||||
:language: javascript |
||||
|
||||
|
||||
Reapply Introspection on stored data |
||||
==================================== |
||||
|
||||
.. rest_method:: POST /v1/introspection/{node_id}/data/unprocessed |
||||
|
||||
This method riggers introspection on stored unprocessed data. |
||||
No data is allowed to be sent along with the request. |
||||
|
||||
.. note:: |
||||
|
||||
Requires enabling Swift store in processing section of the |
||||
configuration file. |
||||
|
||||
Normal response codes: 202 |
||||
|
||||
Error codes: |
||||
|
||||
* 400 - bad request or store not configured |
||||
* 401, 403 - missing or invalid authentication |
||||
* 404 - node not found for Node ID |
||||
* 409 - inspector locked node for processing |
||||
|
||||
|
||||
Request |
||||
------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- node_id: node_id |
@ -0,0 +1,155 @@
|
||||
.. -*- rst -*- |
||||
|
||||
=================== |
||||
Introspection Rules |
||||
=================== |
||||
|
||||
Simple JSON-based DSL to define rules, which run during introspection. |
||||
|
||||
|
||||
Create Introspection Rule |
||||
========================= |
||||
|
||||
.. rest_method:: POST /v1/rules |
||||
|
||||
Create a new introspection rule. |
||||
|
||||
Normal response codes: |
||||
|
||||
* 200 - OK for API version < 1.6 |
||||
* 201 - OK for API version 1.6 and higher |
||||
|
||||
Error codes: |
||||
|
||||
* 400 - wrong rule format |
||||
|
||||
Request |
||||
------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- uuid: uuid |
||||
- conditions: conditions |
||||
- actions: actions |
||||
- description: description |
||||
|
||||
|
||||
**Example creating rule request:** |
||||
|
||||
.. literalinclude:: samples/api-v1-create-rule-request.json |
||||
:language: javascript |
||||
|
||||
Response |
||||
-------- |
||||
|
||||
The response will contain full rule object, also ``condition`` |
||||
section may contain additional default fields, like ``invert``, |
||||
``multiple`` and ``field``, see ` Conditions https://docs.openstack.org/ironic-inspector/latest/user/usage.html#conditions>`_ |
||||
|
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- uuid: uuid |
||||
- conditions: conditions |
||||
- actions: actions |
||||
- description: description |
||||
|
||||
**Example JSON representation:** |
||||
|
||||
.. literalinclude:: samples/api-v1-create-rule-response.json |
||||
:language: javascript |
||||
|
||||
|
||||
Get Introspection Rules |
||||
======================= |
||||
|
||||
.. rest_method:: GET /v1/rules |
||||
|
||||
List all introspection rules |
||||
|
||||
Normal response codes: 200 |
||||
|
||||
Response |
||||
-------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- uuid: uuid |
||||
- description: description |
||||
- links: links |
||||
|
||||
**Example JSON representation:** |
||||
|
||||
.. literalinclude:: samples/api-v1-get-rules-response.json |
||||
:language: javascript |
||||
|
||||
|
||||
Delete Introspection Rules |
||||
========================== |
||||
|
||||
.. rest_method:: DELETE /v1/rules |
||||
|
||||
Delete all introspection rules |
||||
|
||||
Normal response codes: 204 |
||||
|
||||
|
||||
|
||||
Get Introspection Rule |
||||
====================== |
||||
|
||||
.. rest_method:: GET /v1/rules/{uuid} |
||||
|
||||
Get one introspection rule by its ``uuid`` |
||||
|
||||
Normal response codes: 202 |
||||
|
||||
Error codes: |
||||
|
||||
* 404 - rule not found |
||||
|
||||
Request |
||||
------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- uuid: uuid |
||||
|
||||
|
||||
Response |
||||
-------- |
||||
|
||||
The response will contain full rule object: |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- uuid: uuid |
||||
- conditions: conditions |
||||
- actions: actions |
||||
- description: description |
||||
|
||||
**Example JSON representation:** |
||||
|
||||
.. literalinclude:: samples/api-v1-get-rule-response.json |
||||
:language: javascript |
||||
|
||||
|
||||
Delete Introspection Rule |
||||
========================= |
||||
|
||||
.. rest_method:: DELETE /v1/rules/{uuid} |
||||
|
||||
Delete introspection rule by ``uuid``. |
||||
|
||||
Normal response codes: 204 |
||||
|
||||
Error codes: |
||||
|
||||
* 404 - rule not found |
||||
|
||||
Request |
||||
------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- uuid: uuid |
@ -0,0 +1,81 @@
|
||||
.. -*- rst -*- |
||||
|
||||
============ |
||||
API versions |
||||
============ |
||||
|
||||
Concepts |
||||
======== |
||||
|
||||
In order to bring new features to users over time, the Ironic |
||||
Inspector API supports versioning. There are two kinds of versions: |
||||
|
||||
- ``major versions``, which have dedicated urls. |
||||
- ``microversions``, which can be requested through the use of the |
||||
``X-OpenStack-Ironic-Inspector-API-Version`` header. |
||||
|
||||
The Version APIs work differently from other APIs as they *do not* require authentication. |
||||
|
||||
All API requests support the ``X-OpenStack-Ironic-Inspector-API-Version`` header. |
||||
This header SHOULD be supplied with every request; in the absence of this header, |
||||
server will default to current supported version in all responses. |
||||
|
||||
List API versions |
||||
================= |
||||
|
||||
.. rest_method:: GET / |
||||
|
||||
This fetches all the information about all known major API versions in the |
||||
deployment. Links to more specific information will be provided for each major |
||||
API version, as well as information about supported min and max microversions. |
||||
|
||||
Normal response codes: 200 |
||||
|
||||
Request |
||||
------- |
||||
|
||||
Response Example |
||||
---------------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- versions: versions |
||||
- id: id |
||||
- links: links |
||||
- status: status |
||||
|
||||
- x-openstack-ironic-api-min-version: x-openstack-ironic-inspector-api-minimum-version |
||||
- x-openstack-ironic-api-max-version: x-openstack-ironic-inspector-api-maximum-version |
||||
|
||||
.. literalinclude:: samples/api-root-response.json |
||||
:language: javascript |
||||
|
||||
|
||||
Show v1 API |
||||
=========== |
||||
|
||||
.. rest_method:: GET /v1/ |
||||
|
||||
Show all the resources within the Ironic Inspector v1 API. |
||||
|
||||
Normal response codes: 200 |
||||
|
||||
Request |
||||
------- |
||||
|
||||
Response Example |
||||
---------------- |
||||
|
||||
.. rest_parameters:: parameters.yaml |
||||
|
||||
- resources: resources |
||||
- links: links |
||||
- href: href |
||||
- rel: rel |
||||
- name: name |
||||
|
||||
- x-openstack-ironic-api-min-version: x-openstack-ironic-inspector-api-minimum-version |
||||
- x-openstack-ironic-api-max-version: x-openstack-ironic-inspector-api-maximum-version |
||||
|
||||
.. literalinclude:: samples/api-v1-root-response.json |
||||
:language: javascript |
@ -0,0 +1,257 @@
|
||||
# variables in header |
||||
x-auth-token: |
||||
description: | |
||||
The client token being passed into Ironic Inspector API to make |
||||
authentication. |
||||
in: header |
||||
required: true |
||||
type: string |
||||
x-openstack-ironic-inspector-api-maximum-version: |
||||
description: | |
||||
Maximum API microversion supported by this endpoint, eg. "1.10" |
||||
in: header |
||||
required: true |
||||
type: string |
||||
x-openstack-ironic-inspector-api-minimum-version: |
||||
description: | |
||||
Minimum API microversion supported by this endpoint, eg. "1.1" |
||||
in: header |
||||
required: true |
||||
type: string |
||||
x-openstack-ironic-inspector-api-version: |
||||
description: > |
||||
A request SHOULD include this header to indicate to the Ironic Inspector |
||||
API service what version the client supports. The server may transform |
||||
the response object into compliance with the requested version, if it is |
||||
supported, or return a 406 Not Supported error. |
||||
If this header is not supplied, the server will default to current |
||||
supported version in all responses. |
||||
in: header |
||||
required: true |
||||
type: string |
||||
|
||||
# variables in path |
||||
node_id: |
||||
description: | |
||||
The UUID of the Ironic node. |
||||
in: path |
||||
required: true |
||||
type: string |
||||
|
||||
uuid: |
||||
description: | |
||||
The UUID of the Ironic Inspector rule. |
||||
in: path |
||||
required: true |
||||
type: string |
||||
|
||||
# common variables to query strings |
||||
limit: |
||||
description: | |
||||
Requests a page size of items. Returns a number of items up to a limit |
||||
value. Use the ``limit`` parameter to make an initial limited request and |
||||
use the ID of the last-seen item from the response as the ``marker`` |
||||
parameter value in a subsequent limited request. This value cannot be |
||||
larger than the ``api_max_limit`` option in the configuration. If it is |
||||
higher than ``api_max_limit``, return 400 Bad Request. |
||||
in: query |
||||
required: false |
||||
type: integer |
||||
manage_boot: |
||||
description: | |
||||
Whether the current installation of ironic-inspector can manage PXE |
||||
booting of nodes. |
||||
in: query |
||||
required: false |
||||
type: string |
||||
marker: |
||||
description: | |
||||
The ID of the last-seen item. Use the ``limit`` parameter to make an |
||||
initial limited request and use the ID of the last-seen item from the |
||||
response as the ``marker`` parameter value in a subsequent request. |
||||
in: query |
||||
required: false |
||||
type: string |
||||
|
||||
|
||||
# variables to methods |
||||
actions: |
||||
description: | |
||||
List of operations that will be performed if ``conditions`` of this |
||||
rule are fulfilled. |
||||
in: body |
||||
required: true |
||||
type: array |
||||
bmc_address: |
||||
description: | |
||||
IP address of the node's BMC |
||||
in: body |
||||
required: false |
||||
type: string |
||||
boot_interface: |
||||
description: | |
||||
MAC address of the NIC that the machine PXE booted from |
||||
in: body |
||||
required: false |
||||
type: string |
||||
conditions: |
||||
description: | |
||||
List of a logic statementd or operations in rules, that can be |
||||
evaluated as True or False. |
||||
in: body |
||||
required: false |
||||
type: array |
||||
cpu: |
||||
description: | |
||||
CPU information containing at least keys ``count`` (CPU count) and |
||||
``architecture`` (CPU architecture, e.g. ``x86_64``), |
||||
in: body |
||||
required: true |
||||
type: string |
||||
description: |
||||
description: | |
||||
Rule human-readable description. |
||||
in: body |
||||
required: false |
||||
type: string |
||||
disks: |
||||
description: | |
||||
List of disk block devices containing at least ``name`` and ``size`` |
||||
keys. In case ``disks`` are not provided **ironic-inspector** assumes |
||||
that this is a disk-less node. |
||||
in: body |
||||
required: true |
||||
type: array |
||||
error: |
||||
description: | |
||||
Error description string or ``null``; |
||||
``Canceled by operator`` in case introspection was aborted. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
finished: |
||||
description: | |
||||
Whether introspection has finished for this node. |
||||
in: body |
||||
required: true |
||||
type: boolean |
||||
finished_at: |
||||
description: | |
||||
UTC ISO8601 timestamp of introspection finished or ``null``. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
href: |
||||
description: | |
||||
A bookmark link to resource object. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
id: |
||||
description: | |
||||
API microversion, eg, "1.12". |
||||
in: body |
||||
required: true |
||||
type: string |
||||
interfaces: |
||||
description: | |
||||
List of dictionaries with interfaces info, contains following keys: |
||||
``name``, ``ipv4_address``, ``mac_address``, ``client_id``. |
||||
in: body |
||||
required: true |
||||
type: array |
||||
inventory: |
||||
description: Dictionary with hardware inventory keys. |
||||
in: body |
||||
required: true |
||||
type: object |
||||
links: |
||||
description: | |
||||
A list of relative links. Includes the self and |
||||
bookmark links. |
||||
in: body |
||||
required: true |
||||
type: array |
||||
logs: |
||||
description: Base64-encoded logs from the ramdisk. |
||||
in: body |
||||
required: false |
||||
type: string |
||||
memory: |
||||
description: | |
||||
Memory information containing at least ``physical_mb`` key, |
||||
memory size is reported by dmidecod. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
name: |
||||
description: | |
||||
Resource name, like `introspection`, `rules`. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
node_uuid: |
||||
description: Ironic node uui |
||||
in: body |
||||
required: true |
||||
type: string |
||||
rel: |
||||
description: | |
||||
The relationship between the version and the href. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
resources: |
||||
description: | |
||||
A list of available API resources. |
||||
in: body |
||||
required: true |
||||
type: array |
||||
root_disk: |
||||
description: | |
||||
Default deployment root disk as calculated by the **ironic-python-agent** |
||||
algorithm. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
started_at: |
||||
description: | |
||||
UTC ISO8601 timestamp of introspection start. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
state: |
||||
description: | |
||||
Current state of the introspection, possible values: ``enrolling``, |
||||
``error``, ``finished``, ``processing``, ``reapplying``, ``starting``, |
||||
``waiting``. For detail information about states see |
||||
`Inspector states <https://docs.openstack.org/ironic-inspector/latest/user/workflow.html#state-machine-diagram>`_. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
status: |
||||
description: | |
||||
The status of this API version. This can be one of: |
||||
|
||||
- ``CURRENT`` This version is up to date recent and should be prioritized over all others. |
||||
|
||||
- ``SUPPORTED`` This version is available and may not be updated in future. |
||||
|
||||
- ``DEPRECATED`` This version is still available but may be removed in future. |
||||
|
||||
- ``EXPERIMENTAL`` This version is under development and may be changed in future. |
||||
in: body |
||||
required: true |
||||
type: string |
||||
version: |
||||
description: | |
||||
Versioning of this API response, eg. "1.12". |
||||
in: body |
||||
required: true |
||||
type: string |
||||
versions: |
||||
description: | |
||||
Array of information about currently supported versions. |
||||
in: body |
||||
required: true |
||||
type: array |
@ -0,0 +1,14 @@
|
||||
{ |
||||
"versions": [ |
||||
{ |
||||
"id": "1.12", |
||||
"links": [ |
||||
{ |
||||
"href": "http://127.0.0.1:5050/v1", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"status": "CURRENT" |
||||
} |
||||
] |
||||
} |
@ -0,0 +1,3 @@
|
||||
{ |
||||
"uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b" |
||||
} |
@ -0,0 +1,3 @@
|
||||
{ |
||||
"uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a" |
||||
} |
@ -0,0 +1,75 @@
|
||||
{ |
||||
"root_disk": { |
||||
"rotational": true, |
||||
"vendor": "0x1af4", |
||||
"name": "/dev/vda", |
||||
"hctl": null, |
||||
"wwn_vendor_extension": null, |
||||
"wwn_with_extension": null, |
||||
"model": "", |
||||
"wwn": null, |
||||
"serial": null, |
||||
"size": 13958643712 |
||||
}, |
||||
"boot_interface": "52:54:00:4e:3d:30", |
||||
"inventory": { |
||||
"bmc_address": "192.167.2.134", |
||||
"interfaces": [ |
||||
{ |
||||
"lldp": null, |
||||
"product": "0x0001", |
||||
"vendor": "0x1af4", |
||||
"name": "eth1", |
||||
"has_carrier": true, |
||||
"switch_port_descr": null, |
||||
"switch_chassis_descr": null, |
||||
"ipv4_address": "172.24.42.101", |
||||
"client_id": null, |
||||
"mac_address": "52:54:00:47:20:4d" |
||||
}, |
||||
{ |
||||
"lldp": null, |
||||
"product": "0x0001", |
||||
"vendor": "0x1af4", |
||||
"name": "eth0", |
||||
"has_carrier": true, |
||||
"switch_port_descr": null, |
||||
"switch_chassis_descr": null, |
||||
"ipv4_address": "172.24.42.100", |
||||
"client_id": null, |
||||
"mac_address": "52:54:00:4e:3d:30" |
||||
} |
||||
], |
||||
"disks": [ |
||||
{ |
||||
"rotational": true, |
||||
"vendor": "0x1af4", |
||||
"name": "/dev/vda", |
||||
"hctl": null, |
||||
"wwn_vendor_extension": null, |
||||
"wwn_with_extension": null, |
||||
"model": "", |
||||
"wwn": null, |
||||
"serial": null, |
||||
"size": 13958643712 |
||||
} |
||||
], |
||||
"memory": { |
||||
"physical_mb": 2048, |
||||
"total": 2105864192 |
||||
}, |
||||
"cpu": { |
||||
"count": 2, |
||||
"frequency": "2100.084", |
||||
"flags": [ |
||||
"fpu", |
||||
"mmx", |
||||
"fxsr", |
||||
"sse", |
||||
"sse2", |
||||
], |
||||
"architecture": "x86_64" |
||||
} |
||||
}, |
||||
"logs": "<hidden>" |
||||
} |
@ -0,0 +1,26 @@
|
||||
{ |
||||
"uuid":"7459bf7c-9ff9-43a8-ba9f-48542ecda66c", |
||||
"description":"Set deploy info if not already set on node", |
||||
"actions":[ |
||||
{ |
||||
"action":"set-attribute", |
||||
"path":"driver_info/deploy_kernel", |
||||
"value":"8fd65-c97b-4d00-aa8b-7ed166a60971" |
||||
}, |
||||
{ |
||||
"action":"set-attribute", |
||||
"path":"driver_info/deploy_ramdisk", |
||||
"value":"09e5420c-6932-4199-996e-9485c56b3394" |
||||
} |
||||
], |
||||
"conditions":[ |
||||
{ |
||||
"op":"is-empty", |
||||
"field":"node://driver_info.deploy_ramdisk" |
||||
}, |
||||
{ |
||||
"op":"is-empty", |
||||
"field":"node://driver_info.deploy_kernel" |
||||
} |
||||
] |
||||
} |
@ -0,0 +1,36 @@
|
||||
{ |
||||
"actions": [ |
||||
{ |
||||
"action": "set-attribute", |
||||
"path": "driver_info/deploy_kernel", |
||||
"value": "8fd65-c97b-4d00-aa8b-7ed166a60971" |
||||
}, |
||||
{ |
||||
"action": "set-attribute", |
||||
"path": "driver_info/deploy_ramdisk", |
||||
"value": "09e5420c-6932-4199-996e-9485c56b3394" |
||||
} |
||||
], |
||||
"conditions": [ |
||||
{ |
||||
"field": "node://driver_info.deploy_ramdisk", |
||||
"invert": false, |
||||
"multiple": "any", |
||||
"op": "is-empty" |
||||
}, |
||||
{ |
||||
"field": "node://driver_info.deploy_kernel", |
||||
"invert": false, |
||||
"multiple": "any", |
||||
"op": "is-empty" |
||||
} |
||||
], |
||||
"description": "Set deploy info if not already set on node", |
||||
"links": [ |
||||
{ |
||||
"href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c" |
||||
} |
@ -0,0 +1,114 @@
|
||||
{ |
||||
"cpu_arch":"x86_64", |
||||
"macs":[ |
||||
"52:54:00:4e:3d:30" |
||||
], |
||||
"root_disk":{ |
||||
"rotational":true, |
||||
"vendor":"0x1af4", |
||||
"name":"/dev/vda", |
||||
"hctl":null, |
||||
"wwn_vendor_extension":null, |
||||
"wwn_with_extension":null, |
||||
"model":"", |
||||
"wwn":null, |
||||
"serial":null, |
||||
"size":13958643712 |
||||
}, |
||||
"interfaces":{ |
||||
"eth0":{ |
||||
"ip":"172.24.42.100", |
||||
"mac":"52:54:00:4e:3d:30", |
||||
"pxe":true, |
||||
"client_id":null |
||||
} |
||||
}, |
||||
"cpus":2, |
||||
"boot_interface":"52:54:00:4e:3d:30", |
||||
"memory_mb":2048, |
||||
"ipmi_address":"192.167.2.134", |
||||
"inventory":{ |
||||
"bmc_address":"192.167.2.134", |
||||
"interfaces":[ |
||||
{ |
||||
"lldp":null, |
||||
"product":"0x0001", |
||||
"vendor":"0x1af4", |
||||
"name":"eth1", |
||||
"has_carrier":true, |
||||
"switch_port_descr":null, |
||||
"switch_chassis_descr":null, |
||||
"ipv4_address":"172.24.42.101", |
||||
"client_id":null, |
||||
"mac_address":"52:54:00:47:20:4d" |
||||
}, |
||||
{ |
||||
"lldp":null, |
||||
"product":"0x0001", |
||||
"vendor":"0x1af4", |
||||
"name":"eth0", |
||||
"has_carrier":true, |
||||
"switch_port_descr":null, |
||||
"switch_chassis_descr":null, |
||||
"ipv4_address":"172.24.42.100", |
||||
"client_id":null, |
||||
"mac_address":"52:54:00:4e:3d:30" |
||||
} |
||||
], |
||||
"disks":[ |
||||
{ |
||||
"rotational":true, |
||||
"vendor":"0x1af4", |
||||
"name":"/dev/vda", |
||||
"hctl":null, |
||||
"wwn_vendor_extension":null, |
||||
"wwn_with_extension":null, |
||||
"model":"", |
||||
"wwn":null, |
||||
"serial":null, |
||||
"size":13958643712 |
||||
} |
||||
], |
||||
"boot":{ |
||||
"current_boot_mode":"bios", |
||||
"pxe_interface":"52:54:00:4e:3d:30" |
||||
}, |
||||
"system_vendor":{ |
||||
"serial_number":"Not Specified", |
||||
"product_name":"Bochs", |
||||
"manufacturer":"Bochs" |
||||
}, |
||||
"memory":{ |
||||
"physical_mb":2048, |
||||
"total":2105864192 |
||||
}, |
||||
"cpu":{ |
||||
"count":2, |
||||
"frequency":"2100.084", |
||||
"flags": [ |
||||
"fpu", |
||||
"mmx", |
||||
"fxsr", |
||||
"sse", |
||||
"sse2" |
||||
], |
||||
"architecture":"x86_64" |
||||
} |
||||
}, |
||||
"error":null, |
||||
"local_gb":12, |
||||
"all_interfaces":{ |
||||
"eth1":{ |
||||
"ip":"172.24.42.101", |
||||
"mac":"52:54:00:47:20:4d", |
||||
"pxe":false, |
||||
"client_id":null |
||||
}, |
||||
"eth0":{ |
||||
"ip":"172.24.42.100", |
||||
"mac":"52:54:00:4e:3d:30", |
||||
"pxe":true, |
||||
"client_id":null |
||||
} |
||||
} |
||||
} |
@ -0,0 +1,14 @@
|
||||
{ |
||||
"error": null, |
||||
"finished": true, |
||||
"finished_at": "2017-08-16T12:24:30", |
||||
"links": [ |
||||
{ |
||||
"href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"started_at": "2017-08-16T12:22:01", |
||||
"state": "finished", |
||||
"uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b" |
||||
} |
@ -0,0 +1,32 @@
|
||||
{ |
||||
"introspection": [ |
||||
{ |
||||
"error": null, |
||||
"finished": true, |
||||
"finished_at": "2017-08-17T11:36:16", |
||||
"links": [ |
||||
{ |
||||
"href": "http://127.0.0.1:5050/v1/introspection/05ccda19-581b-49bf-8f5a-6ded99701d87", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"started_at": "2017-08-17T11:33:43", |
||||
"state": "finished", |
||||
"uuid": "05ccda19-581b-49bf-8f5a-6ded99701d87" |
||||
}, |
||||
{ |
||||
"error": null, |
||||
"finished": true, |
||||
"finished_at": "2017-08-16T12:24:30", |
||||
"links": [ |
||||
{ |
||||
"href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"started_at": "2017-08-16T12:22:01", |
||||
"state": "finished", |
||||
"uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b" |
||||
} |
||||
] |
||||
} |
@ -0,0 +1,41 @@
|
||||
{ |
||||
"actions": [ |
||||
{ |
||||
"action": "set-attribute", |
||||
"path": "driver", |
||||
"value": "agent_ipmitool" |
||||
}, |
||||
{ |
||||
"action": "set-attribute", |
||||
"path": "driver_info/ipmi_username", |
||||
"value": "username" |
||||
}, |
||||
{ |
||||
"action": "set-attribute", |
||||
"path": "driver_info/ipmi_password", |
||||
"value": "password" |
||||
} |
||||
], |
||||
"conditions": [ |
||||
{ |
||||
"field": "node://driver_info.ipmi_password", |
||||
"invert": false, |
||||
"multiple": "any", |
||||
"op": "is-empty" |
||||
}, |
||||
{ |
||||
"field": "node://driver_info.ipmi_username", |
||||
"invert": false, |
||||
"multiple": "any", |
||||
"op": "is-empty" |
||||
} |
||||
], |
||||
"description": "Set IPMI driver_info if no credentials", |
||||
"links": [ |
||||
{ |
||||
"href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a" |
||||
} |
@ -0,0 +1,24 @@
|
||||
{ |
||||
"rules": [ |
||||
{ |
||||
"description": "Set deploy info if not already set on node", |
||||
"links": [ |
||||
{ |
||||
"href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c" |
||||
}, |
||||
{ |
||||
"description": "Set IPMI driver_info if no credentials", |
||||
"links": [ |
||||
{ |
||||
"href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a" |
||||
} |
||||
] |
||||
} |
@ -0,0 +1,31 @@
|
||||
{ |
||||
"resources": [ |
||||
{ |
||||
"links": [ |
||||
{ |
||||
"href": "http://127.0.0.1:5050/v1/introspection", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"name": "introspection" |
||||
}, |
||||
{ |
||||
"links": [ |
||||
{ |
||||
"href": "http://127.0.0.1:5050/v1/continue", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"name": "continue" |
||||
}, |
||||
{ |
||||
"links": [ |
||||
{ |
||||
"href": "http://127.0.0.1:5050/v1/rules", |
||||
"rel": "self" |
||||
} |
||||
], |
||||
"name": "rules" |
||||
} |
||||
] |
||||
} |
Loading…
Reference in new issue