summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAnton Arefiev <aarefiev@mirantis.com>2017-08-14 15:51:38 +0300
committerKaifeng Wang <kaifeng.w@gmail.com>2018-10-16 16:50:01 +0800
commit05a86b3d574f3262f8ada3d145a352afb8557cdb (patch)
tree182b5c06db48598c931d086e1929dc7721b0cd5f
parent672b7eea66d44d70c2902098aaef180388faded7 (diff)
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 <kaifeng.w@gmail.com> Change-Id: I5009e8708dcad8ab25380f7bf574125d6e758ef5
Notes
Notes (review): Code-Review+2: Dmitry Tantsur <divius.inside@gmail.com> Code-Review+2: Ruby Loo <opensrloo@gmail.com> Code-Review+2: Julia Kreger <juliaashleykreger@gmail.com> Workflow+1: Julia Kreger <juliaashleykreger@gmail.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Mon, 22 Oct 2018 20:31:33 +0000 Reviewed-on: https://review.openstack.org/495752 Project: openstack/ironic-inspector Branch: refs/heads/master
-rw-r--r--api-ref/source/conf.py238
-rw-r--r--api-ref/source/index.rst12
-rw-r--r--api-ref/source/introspection-api-v1-continue.inc68
-rw-r--r--api-ref/source/introspection-api-v1-introspection.inc226
-rw-r--r--api-ref/source/introspection-api-v1-rules.inc155
-rw-r--r--api-ref/source/introspection-api-versions.inc81
-rw-r--r--api-ref/source/parameters.yaml257
-rw-r--r--api-ref/source/samples/api-root-response.json14
-rw-r--r--api-ref/source/samples/api-v1-common-node-uuid.json3
-rw-r--r--api-ref/source/samples/api-v1-common-rule-uuid.json3
-rw-r--r--api-ref/source/samples/api-v1-continue-request.json75
-rw-r--r--api-ref/source/samples/api-v1-create-rule-request.json26
-rw-r--r--api-ref/source/samples/api-v1-create-rule-response.json36
-rw-r--r--api-ref/source/samples/api-v1-data-introspection-response.json114
-rw-r--r--api-ref/source/samples/api-v1-get-introspection-response.json14
-rw-r--r--api-ref/source/samples/api-v1-get-introspections-response.json32
-rw-r--r--api-ref/source/samples/api-v1-get-rule-response.json41
-rw-r--r--api-ref/source/samples/api-v1-get-rules-response.json24
-rw-r--r--api-ref/source/samples/api-v1-root-response.json31
-rw-r--r--lower-constraints.txt1
-rw-r--r--test-requirements.txt2
-rw-r--r--tox.ini6
-rw-r--r--zuul.d/legacy-ironic-inspector-jobs.yaml1
23 files changed, 1459 insertions, 1 deletions
diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py
new file mode 100644
index 0000000..ebaa0d3
--- /dev/null
+++ b/api-ref/source/conf.py
@@ -0,0 +1,238 @@
1# Licensed under the Apache License, Version 2.0 (the "License"); you may
2# not use this file except in compliance with the License. You may obtain
3# a copy of the License at
4#
5# http://www.apache.org/licenses/LICENSE-2.0
6#
7# Unless required by applicable law or agreed to in writing, software
8# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
9# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
10# License for the specific language governing permissions and limitations
11# under the License.
12#
13# ironic-inspector documentation build configuration file, created by
14# sphinx-quickstart on Tue Jul 25 15:17:47 2017.
15#
16# This file is execfile()d with the current directory set to
17# its containing dir.
18#
19# Note that not all possible configuration values are present in this
20# autogenerated file.
21#
22# All configuration values have a default; values that are commented out
23# serve to show the default.
24
25import os
26import subprocess
27import sys
28import warnings
29
30import openstackdocstheme
31
32extensions = [
33 'os_api_ref',
34 'openstackdocstheme',
35]
36
37
38html_theme = 'openstackdocs'
39html_theme_path = [openstackdocstheme.get_html_theme_path()]
40html_theme_options = {
41 "sidebar_dropdown": "api_ref",
42 "sidebar_mode": "toc",
43}
44html_context = {'bug_project': 'ironic-inspector', 'bug_tag': 'api-ref'}
45
46# If extensions (or modules to document with autodoc) are in another directory,
47# add these directories to sys.path here. If the directory is relative to the
48# documentation root, use os.path.abspath to make it absolute, like shown here.
49sys.path.insert(0, os.path.abspath('../../'))
50sys.path.insert(0, os.path.abspath('../'))
51sys.path.insert(0, os.path.abspath('./'))
52
53# -- General configuration ----------------------------------------------------
54
55# Add any Sphinx extension module names here, as strings. They can be
56# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
57
58# The suffix of source filenames.
59source_suffix = '.rst'
60
61# The encoding of source files.
62#
63# source_encoding = 'utf-8'
64
65# The master toctree document.
66master_doc = 'index'
67
68# openstackdocstheme options
69repository_name = 'openstack/ironic-inspector'
70use_storyboard = True
71bug_project = 'openstack/ironic-inspector'
72bug_tag = 'api-ref'
73
74# General information about the project.
75project = 'Hardware Introspection API Reference'
76copyright = '2017-present, Ironic Inspector Developers'
77
78# The version info for the project you're documenting, acts as replacement for
79# |version| and |release|, also used in various other places throughout the
80# built documents.
81#
82from ironic_inspector.version import version_info
83# The full version, including alpha/beta/rc tags.
84release = version_info.release_string()
85# The short X.Y version.
86version = version_info.version_string()
87
88# The language for content autogenerated by Sphinx. Refer to documentation
89# for a list of supported languages.
90#
91# language = None
92
93# There are two options for replacing |today|: either, you set today to some
94# non-false value, then it is used:
95# today = ''
96# Else, today_fmt is used as the format for a strftime call.
97# today_fmt = '%B %d, %Y'
98
99# The reST default role (used for this markup: `text`) to use
100# for all documents.
101# default_role = None
102
103# If true, '()' will be appended to :func: etc. cross-reference text.
104# add_function_parentheses = True
105
106# If true, the current module name will be prepended to all description
107# unit titles (such as .. function::).
108add_module_names = False
109
110# If true, sectionauthor and moduleauthor directives will be shown in the
111# output. They are ignored by default.
112show_authors = False
113
114# The name of the Pygments (syntax highlighting) style to use.
115pygments_style = 'sphinx'
116
117# -- Options for man page output ----------------------------------------------
118
119# Grouping the document tree for man pages.
120# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
121
122
123# -- Options for HTML output --------------------------------------------------
124
125# The theme to use for HTML and HTML Help pages. Major themes that come with
126# Sphinx are currently 'default' and 'sphinxdoc'.
127# html_theme_path = ["."]
128# html_theme = '_theme'
129
130# Theme options are theme-specific and customize the look and feel of a theme
131# further. For a list of options available for each theme, see the
132# documentation.
133# html_theme_options = {}
134
135# Add any paths that contain custom themes here, relative to this directory.
136# html_theme_path = []
137
138# The name for this set of Sphinx documents. If None, it defaults to
139# "<project> v<release> documentation".
140# html_title = None
141
142# A shorter title for the navigation bar. Default is the same as html_title.
143# html_short_title = None
144
145# The name of an image file (relative to this directory) to place at the top
146# of the sidebar.
147# html_logo = None
148
149# The name of an image file (within the static path) to use as favicon of the
150# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
151# pixels large.
152# html_favicon = None
153
154# Add any paths that contain custom static files (such as style sheets) here,
155# relative to this directory. They are copied after the builtin static files,
156# so a file named "default.css" will overwrite the builtin "default.css".
157# html_static_path = ['_static']
158
159# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
160# using the given strftime format.
161# html_last_updated_fmt = '%b %d, %Y'
162git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
163 "-n1"]
164try:
165 html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
166except Exception:
167 warnings.warn('Cannot get last updated time from git repository. '
168 'Not setting "html_last_updated_fmt".')
169
170# If true, SmartyPants will be used to convert quotes and dashes to
171# typographically correct entities.
172# html_use_smartypants = True
173
174# Custom sidebar templates, maps document names to template names.
175# html_sidebars = {}
176
177# Additional templates that should be rendered to pages, maps page names to
178# template names.
179# html_additional_pages = {}
180
181# If false, no module index is generated.
182# html_use_modindex = True
183
184# If false, no index is generated.
185# html_use_index = True
186
187# If true, the index is split into individual pages for each letter.
188# html_split_index = False
189
190# If true, links to the reST sources are added to the pages.
191# html_show_sourcelink = True
192
193# If true, an OpenSearch description file will be output, and all pages will
194# contain a <link> tag referring to it. The value of this option must be the
195# base URL from which the finished HTML is served.
196# html_use_opensearch = ''
197
198# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
199# html_file_suffix = ''
200
201# Output file base name for HTML help builder.
202htmlhelp_basename = 'IronicInspectorAPIRefdoc'
203
204
205# -- Options for LaTeX output -------------------------------------------------
206
207# The paper size ('letter' or 'a4').
208# latex_paper_size = 'letter'
209
210# The font size ('10pt', '11pt' or '12pt').
211# latex_font_size = '10pt'
212
213# Grouping the document tree into LaTeX files. List of tuples
214# (source start file, target name, title, author, documentclass
215# [howto/manual]).
216latex_documents = [
217 ('index',
218 '%s.tex' % project,
219 u'OpenStack Hardware Introspection API Documentation',
220 u'OpenStack Foundation', 'manual'),
221]
222
223# The name of an image file (relative to this directory) to place at the top of
224# the title page.
225# latex_logo = None
226
227# For "manual" documents, if this is true, then toplevel headings are parts,
228# not chapters.
229# latex_use_parts = False
230
231# Additional stuff for the LaTeX preamble.
232# latex_preamble = ''
233
234# Documents to append as an appendix to all manuals.
235# latex_appendices = []
236
237# If false, no module index is generated.
238# latex_use_modindex = True
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
new file mode 100644
index 0000000..a022bde
--- /dev/null
+++ b/api-ref/source/index.rst
@@ -0,0 +1,12 @@
1:tocdepth: 2
2
3=========================================
4Hardware Introspection for Bare Metal API
5=========================================
6
7.. rest_expand_all::
8
9.. include:: introspection-api-versions.inc
10.. include:: introspection-api-v1-introspection.inc
11.. include:: introspection-api-v1-continue.inc
12.. 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 0000000..2b75176
--- /dev/null
+++ b/api-ref/source/introspection-api-v1-continue.inc
@@ -0,0 +1,68 @@
1.. -*- rst -*-
2
3==========================
4Process introspection data
5==========================
6
7After the ramdisk collects the required information from the bare metal
8node, it should post it back to Inspector via ``POST /v1/continue`` method.
9
10
11.. warning::
12 Operators are reminded not to expose the Ironic Inspector API to
13 unsecured networks. Below method is available to *unauthenticated*
14 clients because **ironic-python-agent** ramdisk does not have access to
15 keystone credentials.
16
17
18Ramdisk Callback
19================
20
21.. rest_method:: POST /v1/continue
22
23It is internal method for the ramdisk to post back all discovered data.
24This should not be used for anything other than the ramdisk.
25
26Full list of hardware inventory keys may be found in **ironic-python-agent**
27documentation: `hardware inventory <https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory>`_.
28
29Normal response codes: 201
30
31Error codes: 400
32
33Request
34-------
35
36List of mandatory hardware keys:
37
38.. rest_parameters:: parameters.yaml
39
40 - inventory: inventory
41 - memory: memory
42 - cpu: cpu
43 - bmc_address: bmc_address
44 - interfaces: interfaces
45 - disks: disks
46 - root_disk: root_disk
47 - boot_interface: boot_interface
48 - logs: logs
49
50**Example node introspection continue request:**
51
52.. literalinclude:: samples/api-v1-continue-request.json
53 :language: javascript
54
55
56Response
57--------
58
59The response will contain Ironic node ``uuid`` record.
60
61.. rest_parameters:: parameters.yaml
62
63 - uuid: node_uuid
64
65**Example JSON representation:**
66
67.. literalinclude:: samples/api-v1-common-node-uuid.json
68 :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 0000000..4c29655
--- /dev/null
+++ b/api-ref/source/introspection-api-v1-introspection.inc
@@ -0,0 +1,226 @@
1.. -*- rst -*-
2
3==================
4Node Introspection
5==================
6
7Start, abort introspection, get introspection status, get introspection data
8are done through the ``/v1/introspection`` resource. There are also several
9sub-resources, which allow further actions to be performed on introspection.
10
11Start Introspection
12===================
13
14.. rest_method:: POST /v1/introspection/{node_id}
15
16Initiate hardware introspection for node {node_id} . All power management
17configuration for this node needs to be done prior to calling the endpoint.
18
19In case missing or invalid authentication response code will be 401 and 403.
20If Inspector don't find node {node_id}, it will return 404.
21
22Normal response codes: 202
23
24Error codes: 400, 401, 403, 404
25
26
27Request
28-------
29
30.. rest_parameters:: parameters.yaml
31
32 - node_id: node_id
33 - manage_boot: manage_boot
34
35
36Response
37--------
38
39The response will be empty body.
40
41Get Introspection status
42========================
43
44.. rest_method:: GET /v1/introspection/{node_id}
45
46Get node introspection status.
47
48In case missing or invalid authentication response code will be 401 and 403.
49If Inspector don't find node {node_id}, it will return 404.
50
51Normal response codes: 200
52
53Error codes: 400, 401, 403, 404
54
55Request
56-------
57
58.. rest_parameters:: parameters.yaml
59
60 - node_id: node_id
61
62
63Response
64--------
65
66The response will contain the complete introspection info, like
67create, finish time, introspection state, errors if any.
68
69.. rest_parameters:: parameters.yaml
70
71 - error: error
72 - finished: finished
73 - finished_at: finished_at
74 - links: links
75 - started_at: started_at
76 - state: state
77 - uuid: node_id
78
79**Example JSON representation of an introspection:**
80
81.. literalinclude:: samples/api-v1-get-introspection-response.json
82 :language: javascript
83
84
85List All Introspection statuses
86===============================
87
88.. rest_method:: GET /v1/introspection/
89
90Returned status list is sorted by the ``started_at, uuid`` attribute pair,
91newer items first.
92
93In case missing or invalid authentication response code will be 401 and 403.
94
95Normal response codes: 200
96
97Error codes: 400, 401, 403
98
99Request
100-------
101
102Status list may be paginated with these query string fields:
103
104.. rest_parameters:: parameters.yaml
105
106 - marker: marker
107 - limit: limit
108
109
110Response
111--------
112
113The response will contain a list of status objects:
114
115.. rest_parameters:: parameters.yaml
116
117 - error: error
118 - finished: finished
119 - finished_at: finished_at
120 - links: links
121 - started_at: started_at
122 - state: state
123 - uuid: node_id
124
125
126**Example JSON representation of an introspection:**
127
128.. literalinclude:: samples/api-v1-get-introspections-response.json
129 :language: javascript
130
131
132Abort Introspection
133===================
134
135.. rest_method:: POST /v1/introspection/{node_id}/abort
136
137Abort running introspection.
138
139Normal response codes: 202
140
141Error codes:
142
143* 400 - bad request
144* 401, 403 - missing or invalid authentication
145* 404 - node cannot be found
146* 409 - inspector has locked this node for processing
147
148Request
149-------
150
151.. rest_parameters:: parameters.yaml
152
153 - node_id: node_id
154
155
156Get Introspection data
157======================
158
159.. rest_method:: GET /v1/introspection/{node_id}/data
160
161Return stored data from successful introspection.
162
163.. note::
164 We do not provide any backward compatibility guarantees regarding the
165 format and contents of the stored data. Notably, it depends on the ramdisk
166 used and plugins enabled both in the ramdisk and in inspector itself.
167
168Normal response codes: 200
169
170Error codes:
171
172* 400 - bad request
173* 401, 403 - missing or invalid authentication
174* 404 - data cannot be found or data storage not configured
175
176Request
177-------
178
179Status list may be paginated with these query string fields:
180
181.. rest_parameters:: parameters.yaml
182
183 - node_id: node_id
184 - limit: limit
185
186
187Response
188--------
189
190The response will contain introspection data in the form of json string.
191
192**Example JSON representation of an introspection data:**
193
194.. literalinclude:: samples/api-v1-data-introspection-response.json
195 :language: javascript
196
197
198Reapply Introspection on stored data
199====================================
200
201.. rest_method:: POST /v1/introspection/{node_id}/data/unprocessed
202
203This method riggers introspection on stored unprocessed data.
204No data is allowed to be sent along with the request.
205
206.. note::
207
208 Requires enabling Swift store in processing section of the
209 configuration file.
210
211Normal response codes: 202
212
213Error codes:
214
215* 400 - bad request or store not configured
216* 401, 403 - missing or invalid authentication
217* 404 - node not found for Node ID
218* 409 - inspector locked node for processing
219
220
221Request
222-------
223
224.. rest_parameters:: parameters.yaml
225
226 - 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 0000000..1bbb440
--- /dev/null
+++ b/api-ref/source/introspection-api-v1-rules.inc
@@ -0,0 +1,155 @@
1.. -*- rst -*-
2
3===================
4Introspection Rules
5===================
6
7Simple JSON-based DSL to define rules, which run during introspection.
8
9
10Create Introspection Rule
11=========================
12
13.. rest_method:: POST /v1/rules
14
15Create a new introspection rule.
16
17Normal response codes:
18
19* 200 - OK for API version < 1.6
20* 201 - OK for API version 1.6 and higher
21
22Error codes:
23
24* 400 - wrong rule format
25
26Request
27-------
28
29.. rest_parameters:: parameters.yaml
30
31 - uuid: uuid
32 - conditions: conditions
33 - actions: actions
34 - description: description
35
36
37**Example creating rule request:**
38
39.. literalinclude:: samples/api-v1-create-rule-request.json
40 :language: javascript
41
42Response
43--------
44
45The response will contain full rule object, also ``condition``
46section may contain additional default fields, like ``invert``,
47``multiple`` and ``field``, see ` Conditions https://docs.openstack.org/ironic-inspector/latest/user/usage.html#conditions>`_
48
49
50.. rest_parameters:: parameters.yaml
51
52 - uuid: uuid
53 - conditions: conditions
54 - actions: actions
55 - description: description
56
57**Example JSON representation:**
58
59.. literalinclude:: samples/api-v1-create-rule-response.json
60 :language: javascript
61
62
63Get Introspection Rules
64=======================
65
66.. rest_method:: GET /v1/rules
67
68List all introspection rules
69
70Normal response codes: 200
71
72Response
73--------
74
75.. rest_parameters:: parameters.yaml
76
77 - uuid: uuid
78 - description: description
79 - links: links
80
81**Example JSON representation:**
82
83.. literalinclude:: samples/api-v1-get-rules-response.json
84 :language: javascript
85
86
87Delete Introspection Rules
88==========================
89
90.. rest_method:: DELETE /v1/rules
91
92Delete all introspection rules
93
94Normal response codes: 204
95
96
97
98Get Introspection Rule
99======================
100
101.. rest_method:: GET /v1/rules/{uuid}
102
103Get one introspection rule by its ``uuid``
104
105Normal response codes: 202
106
107Error codes:
108
109* 404 - rule not found
110
111Request
112-------
113
114.. rest_parameters:: parameters.yaml
115
116 - uuid: uuid
117
118
119Response
120--------
121
122The response will contain full rule object:
123
124.. rest_parameters:: parameters.yaml
125
126 - uuid: uuid
127 - conditions: conditions
128 - actions: actions
129 - description: description
130
131**Example JSON representation:**
132
133.. literalinclude:: samples/api-v1-get-rule-response.json
134 :language: javascript
135
136
137Delete Introspection Rule
138=========================
139
140.. rest_method:: DELETE /v1/rules/{uuid}
141
142Delete introspection rule by ``uuid``.
143
144Normal response codes: 204
145
146Error codes:
147
148* 404 - rule not found
149
150Request
151-------
152
153.. rest_parameters:: parameters.yaml
154
155 - 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 0000000..f8086ac
--- /dev/null
+++ b/api-ref/source/introspection-api-versions.inc
@@ -0,0 +1,81 @@
1.. -*- rst -*-
2
3============
4API versions
5============
6
7Concepts
8========
9
10In order to bring new features to users over time, the Ironic
11Inspector API supports versioning. There are two kinds of versions:
12
13- ``major versions``, which have dedicated urls.
14- ``microversions``, which can be requested through the use of the
15 ``X-OpenStack-Ironic-Inspector-API-Version`` header.
16
17The Version APIs work differently from other APIs as they *do not* require authentication.
18
19All API requests support the ``X-OpenStack-Ironic-Inspector-API-Version`` header.
20This header SHOULD be supplied with every request; in the absence of this header,
21server will default to current supported version in all responses.
22
23List API versions
24=================
25
26.. rest_method:: GET /
27
28This fetches all the information about all known major API versions in the
29deployment. Links to more specific information will be provided for each major
30API version, as well as information about supported min and max microversions.
31
32Normal response codes: 200
33
34Request
35-------
36
37Response Example
38----------------
39
40.. rest_parameters:: parameters.yaml
41
42 - versions: versions
43 - id: id
44 - links: links
45 - status: status
46
47 - x-openstack-ironic-api-min-version: x-openstack-ironic-inspector-api-minimum-version
48 - x-openstack-ironic-api-max-version: x-openstack-ironic-inspector-api-maximum-version
49
50.. literalinclude:: samples/api-root-response.json
51 :language: javascript
52
53
54Show v1 API
55===========
56
57.. rest_method:: GET /v1/
58
59Show all the resources within the Ironic Inspector v1 API.
60
61Normal response codes: 200
62
63Request
64-------
65
66Response Example
67----------------
68
69.. rest_parameters:: parameters.yaml
70
71 - resources: resources
72 - links: links
73 - href: href
74 - rel: rel
75 - name: name
76
77 - x-openstack-ironic-api-min-version: x-openstack-ironic-inspector-api-minimum-version
78 - x-openstack-ironic-api-max-version: x-openstack-ironic-inspector-api-maximum-version
79
80.. literalinclude:: samples/api-v1-root-response.json
81 :language: javascript
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
new file mode 100644
index 0000000..8a02f13
--- /dev/null
+++ b/api-ref/source/parameters.yaml
@@ -0,0 +1,257 @@
1# variables in header
2x-auth-token:
3 description: |
4 The client token being passed into Ironic Inspector API to make
5 authentication.
6 in: header
7 required: true
8 type: string
9x-openstack-ironic-inspector-api-maximum-version:
10 description: |
11 Maximum API microversion supported by this endpoint, eg. "1.10"
12 in: header
13 required: true
14 type: string
15x-openstack-ironic-inspector-api-minimum-version:
16 description: |
17 Minimum API microversion supported by this endpoint, eg. "1.1"
18 in: header
19 required: true
20 type: string
21x-openstack-ironic-inspector-api-version:
22 description: >
23 A request SHOULD include this header to indicate to the Ironic Inspector
24 API service what version the client supports. The server may transform
25 the response object into compliance with the requested version, if it is
26 supported, or return a 406 Not Supported error.
27 If this header is not supplied, the server will default to current
28 supported version in all responses.
29 in: header
30 required: true
31 type: string
32
33# variables in path
34node_id:
35 description: |
36 The UUID of the Ironic node.
37 in: path
38 required: true
39 type: string
40
41uuid:
42 description: |
43 The UUID of the Ironic Inspector rule.
44 in: path
45 required: true
46 type: string
47
48# common variables to query strings
49limit:
50 description: |
51 Requests a page size of items. Returns a number of items up to a limit
52 value. Use the ``limit`` parameter to make an initial limited request and
53 use the ID of the last-seen item from the response as the ``marker``
54 parameter value in a subsequent limited request. This value cannot be
55 larger than the ``api_max_limit`` option in the configuration. If it is
56 higher than ``api_max_limit``, return 400 Bad Request.
57 in: query
58 required: false
59 type: integer
60manage_boot:
61 description: |
62 Whether the current installation of ironic-inspector can manage PXE
63 booting of nodes.
64 in: query
65 required: false
66 type: string
67marker:
68 description: |
69 The ID of the last-seen item. Use the ``limit`` parameter to make an
70 initial limited request and use the ID of the last-seen item from the
71 response as the ``marker`` parameter value in a subsequent request.
72 in: query
73 required: false
74 type: string
75
76
77# variables to methods
78actions:
79 description: |
80 List of operations that will be performed if ``conditions`` of this
81 rule are fulfilled.
82 in: body
83 required: true
84 type: array
85bmc_address:
86 description: |
87 IP address of the node's BMC
88 in: body
89 required: false
90 type: string
91boot_interface:
92 description: |
93 MAC address of the NIC that the machine PXE booted from
94 in: body
95 required: false
96 type: string
97conditions:
98 description: |
99 List of a logic statementd or operations in rules, that can be
100 evaluated as True or False.
101 in: body
102 required: false
103 type: array
104cpu:
105 description: |
106 CPU information containing at least keys ``count`` (CPU count) and
107 ``architecture`` (CPU architecture, e.g. ``x86_64``),
108 in: body
109 required: true
110 type: string
111description:
112 description: |
113 Rule human-readable description.
114 in: body
115 required: false
116 type: string
117disks:
118 description: |
119 List of disk block devices containing at least ``name`` and ``size``
120 keys. In case ``disks`` are not provided **ironic-inspector** assumes
121 that this is a disk-less node.
122 in: body
123 required: true
124 type: array
125error:
126 description: |
127 Error description string or ``null``;
128 ``Canceled by operator`` in case introspection was aborted.
129 in: body
130 required: true
131 type: string
132finished:
133 description: |
134 Whether introspection has finished for this node.
135 in: body
136 required: true
137 type: boolean
138finished_at:
139 description: |
140 UTC ISO8601 timestamp of introspection finished or ``null``.
141 in: body
142 required: true
143 type: string
144href:
145 description: |
146 A bookmark link to resource object.
147 in: body
148 required: true
149 type: string
150id:
151 description: |
152 API microversion, eg, "1.12".
153 in: body
154 required: true
155 type: string
156interfaces:
157 description: |
158 List of dictionaries with interfaces info, contains following keys:
159 ``name``, ``ipv4_address``, ``mac_address``, ``client_id``.
160 in: body
161 required: true
162 type: array
163inventory:
164 description: Dictionary with hardware inventory keys.
165 in: body
166 required: true
167 type: object
168links:
169 description: |
170 A list of relative links. Includes the self and
171 bookmark links.
172 in: body
173 required: true
174 type: array
175logs:
176 description: Base64-encoded logs from the ramdisk.
177 in: body
178 required: false
179 type: string
180memory:
181 description: |
182 Memory information containing at least ``physical_mb`` key,
183 memory size is reported by dmidecod.
184 in: body
185 required: true
186 type: string
187name:
188 description: |
189 Resource name, like `introspection`, `rules`.
190 in: body
191 required: true
192 type: string
193node_uuid:
194 description: Ironic node uui
195 in: body
196 required: true
197 type: string
198rel:
199 description: |
200 The relationship between the version and the href.
201 in: body
202 required: true
203 type: string
204resources:
205 description: |
206 A list of available API resources.
207 in: body
208 required: true
209 type: array
210root_disk:
211 description: |
212 Default deployment root disk as calculated by the **ironic-python-agent**
213 algorithm.
214 in: body
215 required: true
216 type: string
217started_at:
218 description: |
219 UTC ISO8601 timestamp of introspection start.
220 in: body
221 required: true
222 type: string
223state:
224 description: |
225 Current state of the introspection, possible values: ``enrolling``,
226 ``error``, ``finished``, ``processing``, ``reapplying``, ``starting``,
227 ``waiting``. For detail information about states see
228 `Inspector states <https://docs.openstack.org/ironic-inspector/latest/user/workflow.html#state-machine-diagram>`_.
229 in: body
230 required: true
231 type: string
232status:
233 description: |
234 The status of this API version. This can be one of:
235
236 - ``CURRENT`` This version is up to date recent and should be prioritized over all others.
237
238 - ``SUPPORTED`` This version is available and may not be updated in future.
239
240 - ``DEPRECATED`` This version is still available but may be removed in future.
241
242 - ``EXPERIMENTAL`` This version is under development and may be changed in future.
243 in: body
244 required: true
245 type: string
246version:
247 description: |
248 Versioning of this API response, eg. "1.12".
249 in: body
250 required: true
251 type: string
252versions:
253 description: |
254 Array of information about currently supported versions.
255 in: body
256 required: true
257 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 0000000..c0f8a69
--- /dev/null
+++ b/api-ref/source/samples/api-root-response.json
@@ -0,0 +1,14 @@
1{
2 "versions": [
3 {
4 "id": "1.12",
5 "links": [
6 {
7 "href": "http://127.0.0.1:5050/v1",
8 "rel": "self"
9 }
10 ],
11 "status": "CURRENT"
12 }
13 ]
14}
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 0000000..3d23de7
--- /dev/null
+++ b/api-ref/source/samples/api-v1-common-node-uuid.json
@@ -0,0 +1,3 @@
1{
2 "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
3} \ 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 0000000..bf24670
--- /dev/null
+++ b/api-ref/source/samples/api-v1-common-rule-uuid.json
@@ -0,0 +1,3 @@
1{
2 "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
3} \ 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 0000000..4969f1f
--- /dev/null
+++ b/api-ref/source/samples/api-v1-continue-request.json
@@ -0,0 +1,75 @@
1{
2 "root_disk": {
3 "rotational": true,
4 "vendor": "0x1af4",
5 "name": "/dev/vda",
6 "hctl": null,
7 "wwn_vendor_extension": null,
8 "wwn_with_extension": null,
9 "model": "",
10 "wwn": null,
11 "serial": null,
12 "size": 13958643712
13 },
14 "boot_interface": "52:54:00:4e:3d:30",
15 "inventory": {
16 "bmc_address": "192.167.2.134",
17 "interfaces": [
18 {
19 "lldp": null,
20 "product": "0x0001",
21 "vendor": "0x1af4",
22 "name": "eth1",
23 "has_carrier": true,
24 "switch_port_descr": null,
25 "switch_chassis_descr": null,
26 "ipv4_address": "172.24.42.101",
27 "client_id": null,
28 "mac_address": "52:54:00:47:20:4d"
29 },
30 {
31 "lldp": null,
32 "product": "0x0001",
33 "vendor": "0x1af4",
34 "name": "eth0",
35 "has_carrier": true,
36 "switch_port_descr": null,
37 "switch_chassis_descr": null,
38 "ipv4_address": "172.24.42.100",
39 "client_id": null,
40 "mac_address": "52:54:00:4e:3d:30"
41 }
42 ],
43 "disks": [
44 {
45 "rotational": true,
46 "vendor": "0x1af4",
47 "name": "/dev/vda",
48 "hctl": null,
49 "wwn_vendor_extension": null,
50 "wwn_with_extension": null,
51 "model": "",
52 "wwn": null,
53 "serial": null,
54 "size": 13958643712
55 }
56 ],
57 "memory": {
58 "physical_mb": 2048,
59 "total": 2105864192
60 },
61 "cpu": {
62 "count": 2,
63 "frequency": "2100.084",
64 "flags": [
65 "fpu",
66 "mmx",
67 "fxsr",
68 "sse",
69 "sse2",
70 ],
71 "architecture": "x86_64"
72 }
73 },
74 "logs": "<hidden>"
75} \ 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 0000000..20db667
--- /dev/null
+++ b/api-ref/source/samples/api-v1-create-rule-request.json
@@ -0,0 +1,26 @@
1{
2 "uuid":"7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
3 "description":"Set deploy info if not already set on node",
4 "actions":[
5 {
6 "action":"set-attribute",
7 "path":"driver_info/deploy_kernel",
8 "value":"8fd65-c97b-4d00-aa8b-7ed166a60971"
9 },
10 {
11 "action":"set-attribute",
12 "path":"driver_info/deploy_ramdisk",
13 "value":"09e5420c-6932-4199-996e-9485c56b3394"
14 }
15 ],
16 "conditions":[
17 {
18 "op":"is-empty",
19 "field":"node://driver_info.deploy_ramdisk"
20 },
21 {
22 "op":"is-empty",
23 "field":"node://driver_info.deploy_kernel"
24 }
25 ]
26} \ 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 0000000..cfe90c7
--- /dev/null
+++ b/api-ref/source/samples/api-v1-create-rule-response.json
@@ -0,0 +1,36 @@
1{
2 "actions": [
3 {
4 "action": "set-attribute",
5 "path": "driver_info/deploy_kernel",
6 "value": "8fd65-c97b-4d00-aa8b-7ed166a60971"
7 },
8 {
9 "action": "set-attribute",
10 "path": "driver_info/deploy_ramdisk",
11 "value": "09e5420c-6932-4199-996e-9485c56b3394"
12 }
13 ],
14 "conditions": [
15 {
16 "field": "node://driver_info.deploy_ramdisk",
17 "invert": false,
18 "multiple": "any",
19 "op": "is-empty"
20 },
21 {
22 "field": "node://driver_info.deploy_kernel",
23 "invert": false,
24 "multiple": "any",
25 "op": "is-empty"
26 }
27 ],
28 "description": "Set deploy info if not already set on node",
29 "links": [
30 {
31 "href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
32 "rel": "self"
33 }
34 ],
35 "uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c"
36}
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 0000000..4af709f
--- /dev/null
+++ b/api-ref/source/samples/api-v1-data-introspection-response.json
@@ -0,0 +1,114 @@
1{
2 "cpu_arch":"x86_64",
3 "macs":[
4 "52:54:00:4e:3d:30"
5 ],
6 "root_disk":{
7 "rotational":true,
8 "vendor":"0x1af4",
9 "name":"/dev/vda",
10 "hctl":null,
11 "wwn_vendor_extension":null,
12 "wwn_with_extension":null,
13 "model":"",
14 "wwn":null,
15 "serial":null,
16 "size":13958643712
17 },
18 "interfaces":{
19 "eth0":{
20 "ip":"172.24.42.100",
21 "mac":"52:54:00:4e:3d:30",
22 "pxe":true,
23 "client_id":null
24 }
25 },
26 "cpus":2,
27 "boot_interface":"52:54:00:4e:3d:30",
28 "memory_mb":2048,
29 "ipmi_address":"192.167.2.134",
30 "inventory":{
31 "bmc_address":"192.167.2.134",
32 "interfaces":[
33 {
34 "lldp":null,
35 "product":"0x0001",
36 "vendor":"0x1af4",
37 "name":"eth1",
38 "has_carrier":true,
39 "switch_port_descr":null,
40 "switch_chassis_descr":null,
41 "ipv4_address":"172.24.42.101",
42 "client_id":null,
43 "mac_address":"52:54:00:47:20:4d"
44 },
45 {
46 "lldp":null,
47 "product":"0x0001",
48 "vendor":"0x1af4",
49 "name":"eth0",
50 "has_carrier":true,
51 "switch_port_descr":null,
52 "switch_chassis_descr":null,
53 "ipv4_address":"172.24.42.100",
54 "client_id":null,
55 "mac_address":"52:54:00:4e:3d:30"
56 }
57 ],
58 "disks":[
59 {
60 "rotational":true,
61 "vendor":"0x1af4",
62 "name":"/dev/vda",
63 "hctl":null,
64 "wwn_vendor_extension":null,
65 "wwn_with_extension":null,
66 "model":"",
67 "wwn":null,
68 "serial":null,
69 "size":13958643712
70 }
71 ],
72 "boot":{
73 "current_boot_mode":"bios",
74 "pxe_interface":"52:54:00:4e:3d:30"
75 },
76 "system_vendor":{
77 "serial_number":"Not Specified",
78 "product_name":"Bochs",
79 "manufacturer":"Bochs"
80 },
81 "memory":{
82 "physical_mb":2048,
83 "total":2105864192
84 },
85 "cpu":{
86 "count":2,
87 "frequency":"2100.084",
88 "flags": [
89 "fpu",
90 "mmx",
91 "fxsr",
92 "sse",
93 "sse2"
94 ],
95 "architecture":"x86_64"
96 }
97 },
98 "error":null,
99 "local_gb":12,
100 "all_interfaces":{
101 "eth1":{
102 "ip":"172.24.42.101",
103 "mac":"52:54:00:47:20:4d",
104 "pxe":false,
105 "client_id":null
106 },
107 "eth0":{
108 "ip":"172.24.42.100",
109 "mac":"52:54:00:4e:3d:30",
110 "pxe":true,
111 "client_id":null
112 }
113 }
114} \ 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 0000000..d768922
--- /dev/null
+++ b/api-ref/source/samples/api-v1-get-introspection-response.json
@@ -0,0 +1,14 @@
1{
2 "error": null,
3 "finished": true,
4 "finished_at": "2017-08-16T12:24:30",
5 "links": [
6 {
7 "href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b",
8 "rel": "self"
9 }
10 ],
11 "started_at": "2017-08-16T12:22:01",
12 "state": "finished",
13 "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
14} \ 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 0000000..ab91763
--- /dev/null
+++ b/api-ref/source/samples/api-v1-get-introspections-response.json
@@ -0,0 +1,32 @@
1{
2 "introspection": [
3 {
4 "error": null,
5 "finished": true,
6 "finished_at": "2017-08-17T11:36:16",
7 "links": [
8 {
9 "href": "http://127.0.0.1:5050/v1/introspection/05ccda19-581b-49bf-8f5a-6ded99701d87",
10 "rel": "self"
11 }
12 ],
13 "started_at": "2017-08-17T11:33:43",
14 "state": "finished",
15 "uuid": "05ccda19-581b-49bf-8f5a-6ded99701d87"
16 },
17 {
18 "error": null,
19 "finished": true,
20 "finished_at": "2017-08-16T12:24:30",
21 "links": [
22 {
23 "href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b",
24 "rel": "self"
25 }
26 ],
27 "started_at": "2017-08-16T12:22:01",
28 "state": "finished",
29 "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
30 }
31 ]
32}
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 0000000..e6656fe
--- /dev/null
+++ b/api-ref/source/samples/api-v1-get-rule-response.json
@@ -0,0 +1,41 @@
1{
2 "actions": [
3 {
4 "action": "set-attribute",
5 "path": "driver",
6 "value": "agent_ipmitool"
7 },
8 {
9 "action": "set-attribute",
10 "path": "driver_info/ipmi_username",
11 "value": "username"
12 },
13 {
14 "action": "set-attribute",
15 "path": "driver_info/ipmi_password",
16 "value": "password"
17 }
18 ],
19 "conditions": [
20 {
21 "field": "node://driver_info.ipmi_password",
22 "invert": false,
23 "multiple": "any",
24 "op": "is-empty"
25 },
26 {
27 "field": "node://driver_info.ipmi_username",
28 "invert": false,
29 "multiple": "any",
30 "op": "is-empty"
31 }
32 ],
33 "description": "Set IPMI driver_info if no credentials",
34 "links": [
35 {
36 "href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a",
37 "rel": "self"
38 }
39 ],
40 "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
41}
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 0000000..66498de
--- /dev/null
+++ b/api-ref/source/samples/api-v1-get-rules-response.json
@@ -0,0 +1,24 @@
1{
2 "rules": [
3 {
4 "description": "Set deploy info if not already set on node",
5 "links": [
6 {
7 "href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
8 "rel": "self"
9 }
10 ],
11 "uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c"
12 },
13 {
14 "description": "Set IPMI driver_info if no credentials",
15 "links": [
16 {
17 "href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a",
18 "rel": "self"
19 }
20 ],
21 "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
22 }
23 ]
24}
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 0000000..2945885
--- /dev/null
+++ b/api-ref/source/samples/api-v1-root-response.json
@@ -0,0 +1,31 @@
1{
2 "resources": [
3 {
4 "links": [
5 {
6 "href": "http://127.0.0.1:5050/v1/introspection",
7 "rel": "self"
8 }
9 ],
10 "name": "introspection"
11 },
12 {
13 "links": [
14 {
15 "href": "http://127.0.0.1:5050/v1/continue",
16 "rel": "self"
17 }
18 ],
19 "name": "continue"
20 },
21 {
22 "links": [
23 {
24 "href": "http://127.0.0.1:5050/v1/rules",
25 "rel": "self"
26 }
27 ],
28 "name": "rules"
29 }
30 ]
31}
diff --git a/lower-constraints.txt b/lower-constraints.txt
index f4b923c..dc3c40f 100644
--- a/lower-constraints.txt
+++ b/lower-constraints.txt
@@ -56,6 +56,7 @@ netaddr==0.7.18
56netifaces==0.10.6 56netifaces==0.10.6
57openstackdocstheme==1.18.1 57openstackdocstheme==1.18.1
58openstacksdk==0.12.0 58openstacksdk==0.12.0
59os-api-ref==1.4.0
59os-client-config==1.29.0 60os-client-config==1.29.0
60os-service-types==1.2.0 61os-service-types==1.2.0
61os-testr==1.0.0 62os-testr==1.0.0
diff --git a/test-requirements.txt b/test-requirements.txt
index 5e31760..204e4ce 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -8,10 +8,10 @@ hacking>=1.0.0,<1.2.0 # Apache-2.0
8mock>=2.0.0 # BSD 8mock>=2.0.0 # BSD
9sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD 9sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
10openstackdocstheme>=1.18.1 # Apache-2.0 10openstackdocstheme>=1.18.1 # Apache-2.0
11os-api-ref>=1.4.0 # Apache-2.0
11stestr>=1.0.0 # Apache-2.0 12stestr>=1.0.0 # Apache-2.0
12reno>=2.5.0 # Apache-2.0 13reno>=2.5.0 # Apache-2.0
13fixtures>=3.0.0 # Apache-2.0/BSD 14fixtures>=3.0.0 # Apache-2.0/BSD
14testresources>=2.0.0 # Apache-2.0/BSD 15testresources>=2.0.0 # Apache-2.0/BSD
15testscenarios>=0.4 # Apache-2.0/BSD 16testscenarios>=0.4 # Apache-2.0/BSD
16oslotest>=3.2.0 # Apache-2.0 17oslotest>=3.2.0 # Apache-2.0
17
diff --git a/tox.ini b/tox.ini
index 6e64883..b00699d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -19,6 +19,12 @@ passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY
19basepython = python3 19basepython = python3
20commands = {posargs} 20commands = {posargs}
21 21
22[testenv:api-ref]
23basepython = python3
24whitelist_externals = bash
25commands =
26 sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
27
22[testenv:releasenotes] 28[testenv:releasenotes]
23basepython = python3 29basepython = python3
24commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html 30commands = 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 7c2da11..53eb4fe 100644
--- a/zuul.d/legacy-ironic-inspector-jobs.yaml
+++ b/zuul.d/legacy-ironic-inspector-jobs.yaml
@@ -15,6 +15,7 @@
15 irrelevant-files: 15 irrelevant-files:
16 - ^test-requirements.txt$ 16 - ^test-requirements.txt$
17 - ^.*\.rst$ 17 - ^.*\.rst$
18 - ^api-ref/.*$
18 - ^doc/.*$ 19 - ^doc/.*$
19 - ^ironic_inspector/test/(?!.*tempest).*$ 20 - ^ironic_inspector/test/(?!.*tempest).*$
20 - ^ironic_inspector/locale/.*$ 21 - ^ironic_inspector/locale/.*$