From 05a86b3d574f3262f8ada3d145a352afb8557cdb Mon Sep 17 00:00:00 2001 From: Anton Arefiev Date: Mon, 14 Aug 2017 15:51:38 +0300 Subject: [PATCH] Add API reference 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 Change-Id: I5009e8708dcad8ab25380f7bf574125d6e758ef5 --- api-ref/source/conf.py | 238 ++++++++++++++++ api-ref/source/index.rst | 12 + .../source/introspection-api-v1-continue.inc | 68 +++++ .../introspection-api-v1-introspection.inc | 226 +++++++++++++++ api-ref/source/introspection-api-v1-rules.inc | 155 +++++++++++ api-ref/source/introspection-api-versions.inc | 81 ++++++ api-ref/source/parameters.yaml | 257 ++++++++++++++++++ api-ref/source/samples/api-root-response.json | 14 + .../samples/api-v1-common-node-uuid.json | 3 + .../samples/api-v1-common-rule-uuid.json | 3 + .../samples/api-v1-continue-request.json | 75 +++++ .../samples/api-v1-create-rule-request.json | 26 ++ .../samples/api-v1-create-rule-response.json | 36 +++ .../api-v1-data-introspection-response.json | 114 ++++++++ .../api-v1-get-introspection-response.json | 14 + .../api-v1-get-introspections-response.json | 32 +++ .../samples/api-v1-get-rule-response.json | 41 +++ .../samples/api-v1-get-rules-response.json | 24 ++ .../source/samples/api-v1-root-response.json | 31 +++ lower-constraints.txt | 1 + test-requirements.txt | 2 +- tox.ini | 6 + zuul.d/legacy-ironic-inspector-jobs.yaml | 1 + 23 files changed, 1459 insertions(+), 1 deletion(-) create mode 100644 api-ref/source/conf.py create mode 100644 api-ref/source/index.rst create mode 100644 api-ref/source/introspection-api-v1-continue.inc create mode 100644 api-ref/source/introspection-api-v1-introspection.inc create mode 100644 api-ref/source/introspection-api-v1-rules.inc create mode 100644 api-ref/source/introspection-api-versions.inc create mode 100644 api-ref/source/parameters.yaml create mode 100644 api-ref/source/samples/api-root-response.json create mode 100644 api-ref/source/samples/api-v1-common-node-uuid.json create mode 100644 api-ref/source/samples/api-v1-common-rule-uuid.json create mode 100644 api-ref/source/samples/api-v1-continue-request.json create mode 100644 api-ref/source/samples/api-v1-create-rule-request.json create mode 100644 api-ref/source/samples/api-v1-create-rule-response.json create mode 100644 api-ref/source/samples/api-v1-data-introspection-response.json create mode 100644 api-ref/source/samples/api-v1-get-introspection-response.json create mode 100644 api-ref/source/samples/api-v1-get-introspections-response.json create mode 100644 api-ref/source/samples/api-v1-get-rule-response.json create mode 100644 api-ref/source/samples/api-v1-get-rules-response.json create mode 100644 api-ref/source/samples/api-v1-root-response.json diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 000000000..ebaa0d340 --- /dev/null +++ b/api-ref/source/conf.py @@ -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 +# " v 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 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 diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 000000000..a022bde2c --- /dev/null +++ b/api-ref/source/index.rst @@ -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 diff --git a/api-ref/source/introspection-api-v1-continue.inc b/api-ref/source/introspection-api-v1-continue.inc new file mode 100644 index 000000000..2b7517619 --- /dev/null +++ b/api-ref/source/introspection-api-v1-continue.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 `_. + +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 diff --git a/api-ref/source/introspection-api-v1-introspection.inc b/api-ref/source/introspection-api-v1-introspection.inc new file mode 100644 index 000000000..4c296557e --- /dev/null +++ b/api-ref/source/introspection-api-v1-introspection.inc @@ -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 diff --git a/api-ref/source/introspection-api-v1-rules.inc b/api-ref/source/introspection-api-v1-rules.inc new file mode 100644 index 000000000..1bbb44077 --- /dev/null +++ b/api-ref/source/introspection-api-v1-rules.inc @@ -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 diff --git a/api-ref/source/introspection-api-versions.inc b/api-ref/source/introspection-api-versions.inc new file mode 100644 index 000000000..f8086acdc --- /dev/null +++ b/api-ref/source/introspection-api-versions.inc @@ -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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 000000000..8a02f135f --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -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 `_. + 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 diff --git a/api-ref/source/samples/api-root-response.json b/api-ref/source/samples/api-root-response.json new file mode 100644 index 000000000..c0f8a69e3 --- /dev/null +++ b/api-ref/source/samples/api-root-response.json @@ -0,0 +1,14 @@ +{ + "versions": [ + { + "id": "1.12", + "links": [ + { + "href": "http://127.0.0.1:5050/v1", + "rel": "self" + } + ], + "status": "CURRENT" + } + ] +} diff --git a/api-ref/source/samples/api-v1-common-node-uuid.json b/api-ref/source/samples/api-v1-common-node-uuid.json new file mode 100644 index 000000000..3d23de7d8 --- /dev/null +++ b/api-ref/source/samples/api-v1-common-node-uuid.json @@ -0,0 +1,3 @@ +{ + "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b" +} \ No newline at end of file diff --git a/api-ref/source/samples/api-v1-common-rule-uuid.json b/api-ref/source/samples/api-v1-common-rule-uuid.json new file mode 100644 index 000000000..bf24670c9 --- /dev/null +++ b/api-ref/source/samples/api-v1-common-rule-uuid.json @@ -0,0 +1,3 @@ +{ + "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a" +} \ No newline at end of file diff --git a/api-ref/source/samples/api-v1-continue-request.json b/api-ref/source/samples/api-v1-continue-request.json new file mode 100644 index 000000000..4969f1f9d --- /dev/null +++ b/api-ref/source/samples/api-v1-continue-request.json @@ -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": "" +} \ No newline at end of file diff --git a/api-ref/source/samples/api-v1-create-rule-request.json b/api-ref/source/samples/api-v1-create-rule-request.json new file mode 100644 index 000000000..20db667ce --- /dev/null +++ b/api-ref/source/samples/api-v1-create-rule-request.json @@ -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" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/api-v1-create-rule-response.json b/api-ref/source/samples/api-v1-create-rule-response.json new file mode 100644 index 000000000..cfe90c773 --- /dev/null +++ b/api-ref/source/samples/api-v1-create-rule-response.json @@ -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" +} diff --git a/api-ref/source/samples/api-v1-data-introspection-response.json b/api-ref/source/samples/api-v1-data-introspection-response.json new file mode 100644 index 000000000..4af709f4a --- /dev/null +++ b/api-ref/source/samples/api-v1-data-introspection-response.json @@ -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 + } + } +} \ No newline at end of file diff --git a/api-ref/source/samples/api-v1-get-introspection-response.json b/api-ref/source/samples/api-v1-get-introspection-response.json new file mode 100644 index 000000000..d76892275 --- /dev/null +++ b/api-ref/source/samples/api-v1-get-introspection-response.json @@ -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" +} \ No newline at end of file diff --git a/api-ref/source/samples/api-v1-get-introspections-response.json b/api-ref/source/samples/api-v1-get-introspections-response.json new file mode 100644 index 000000000..ab9176388 --- /dev/null +++ b/api-ref/source/samples/api-v1-get-introspections-response.json @@ -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" + } + ] +} diff --git a/api-ref/source/samples/api-v1-get-rule-response.json b/api-ref/source/samples/api-v1-get-rule-response.json new file mode 100644 index 000000000..e6656fe6b --- /dev/null +++ b/api-ref/source/samples/api-v1-get-rule-response.json @@ -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" +} diff --git a/api-ref/source/samples/api-v1-get-rules-response.json b/api-ref/source/samples/api-v1-get-rules-response.json new file mode 100644 index 000000000..66498de8f --- /dev/null +++ b/api-ref/source/samples/api-v1-get-rules-response.json @@ -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" + } + ] +} diff --git a/api-ref/source/samples/api-v1-root-response.json b/api-ref/source/samples/api-v1-root-response.json new file mode 100644 index 000000000..294588547 --- /dev/null +++ b/api-ref/source/samples/api-v1-root-response.json @@ -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" + } + ] +} diff --git a/lower-constraints.txt b/lower-constraints.txt index f4b923c72..dc3c40fff 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -56,6 +56,7 @@ netaddr==0.7.18 netifaces==0.10.6 openstackdocstheme==1.18.1 openstacksdk==0.12.0 +os-api-ref==1.4.0 os-client-config==1.29.0 os-service-types==1.2.0 os-testr==1.0.0 diff --git a/test-requirements.txt b/test-requirements.txt index 5e3176080..204e4ce4d 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -8,10 +8,10 @@ hacking>=1.0.0,<1.2.0 # Apache-2.0 mock>=2.0.0 # BSD sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD openstackdocstheme>=1.18.1 # Apache-2.0 +os-api-ref>=1.4.0 # Apache-2.0 stestr>=1.0.0 # Apache-2.0 reno>=2.5.0 # Apache-2.0 fixtures>=3.0.0 # Apache-2.0/BSD testresources>=2.0.0 # Apache-2.0/BSD testscenarios>=0.4 # Apache-2.0/BSD oslotest>=3.2.0 # Apache-2.0 - diff --git a/tox.ini b/tox.ini index 6e648831f..b00699d9f 100644 --- a/tox.ini +++ b/tox.ini @@ -19,6 +19,12 @@ passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY basepython = python3 commands = {posargs} +[testenv:api-ref] +basepython = python3 +whitelist_externals = bash +commands = + sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html + [testenv:releasenotes] basepython = python3 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html diff --git a/zuul.d/legacy-ironic-inspector-jobs.yaml b/zuul.d/legacy-ironic-inspector-jobs.yaml index 7c2da11b0..53eb4fe1b 100644 --- a/zuul.d/legacy-ironic-inspector-jobs.yaml +++ b/zuul.d/legacy-ironic-inspector-jobs.yaml @@ -15,6 +15,7 @@ irrelevant-files: - ^test-requirements.txt$ - ^.*\.rst$ + - ^api-ref/.*$ - ^doc/.*$ - ^ironic_inspector/test/(?!.*tempest).*$ - ^ironic_inspector/locale/.*$