Browse Source

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
Anton Arefiev 1 year ago
parent
commit
05a86b3d57

+ 238
- 0
api-ref/source/conf.py View File

@@ -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
+
25
+import os
26
+import subprocess
27
+import sys
28
+import warnings
29
+
30
+import openstackdocstheme
31
+
32
+extensions = [
33
+    'os_api_ref',
34
+    'openstackdocstheme',
35
+]
36
+
37
+
38
+html_theme = 'openstackdocs'
39
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
40
+html_theme_options = {
41
+    "sidebar_dropdown": "api_ref",
42
+    "sidebar_mode": "toc",
43
+}
44
+html_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.
49
+sys.path.insert(0, os.path.abspath('../../'))
50
+sys.path.insert(0, os.path.abspath('../'))
51
+sys.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.
59
+source_suffix = '.rst'
60
+
61
+# The encoding of source files.
62
+#
63
+# source_encoding = 'utf-8'
64
+
65
+# The master toctree document.
66
+master_doc = 'index'
67
+
68
+# openstackdocstheme options
69
+repository_name = 'openstack/ironic-inspector'
70
+use_storyboard = True
71
+bug_project = 'openstack/ironic-inspector'
72
+bug_tag = 'api-ref'
73
+
74
+# General information about the project.
75
+project = 'Hardware Introspection API Reference'
76
+copyright = '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
+#
82
+from ironic_inspector.version import version_info
83
+# The full version, including alpha/beta/rc tags.
84
+release = version_info.release_string()
85
+# The short X.Y version.
86
+version = 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::).
108
+add_module_names = False
109
+
110
+# If true, sectionauthor and moduleauthor directives will be shown in the
111
+# output. They are ignored by default.
112
+show_authors = False
113
+
114
+# The name of the Pygments (syntax highlighting) style to use.
115
+pygments_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'
162
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
163
+    "-n1"]
164
+try:
165
+    html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
166
+except 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.
202
+htmlhelp_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]).
216
+latex_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

+ 12
- 0
api-ref/source/index.rst View File

@@ -0,0 +1,12 @@
1
+:tocdepth: 2
2
+
3
+=========================================
4
+Hardware 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

+ 68
- 0
api-ref/source/introspection-api-v1-continue.inc View File

@@ -0,0 +1,68 @@
1
+.. -*- rst -*-
2
+
3
+==========================
4
+Process introspection data
5
+==========================
6
+
7
+After the ramdisk collects the required information from the bare metal
8
+node, 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
+
18
+Ramdisk Callback
19
+================
20
+
21
+.. rest_method::  POST /v1/continue
22
+
23
+It is internal method for the ramdisk to post back all discovered data.
24
+This should not be used for anything other than the ramdisk.
25
+
26
+Full list of hardware inventory keys may be found in **ironic-python-agent**
27
+documentation: `hardware inventory <https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory>`_.
28
+
29
+Normal response codes: 201
30
+
31
+Error codes: 400
32
+
33
+Request
34
+-------
35
+
36
+List 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
+
56
+Response
57
+--------
58
+
59
+The 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

+ 226
- 0
api-ref/source/introspection-api-v1-introspection.inc View File

@@ -0,0 +1,226 @@
1
+.. -*- rst -*-
2
+
3
+==================
4
+Node Introspection
5
+==================
6
+
7
+Start, abort introspection, get introspection status, get introspection data
8
+are done through the ``/v1/introspection`` resource. There are also several
9
+sub-resources, which allow further actions to be performed on introspection.
10
+
11
+Start Introspection
12
+===================
13
+
14
+.. rest_method::  POST /v1/introspection/{node_id}
15
+
16
+Initiate hardware introspection for node {node_id} . All power management
17
+configuration for this node needs to be done prior to calling the endpoint.
18
+
19
+In case missing or invalid authentication response code will be 401 and 403.
20
+If Inspector don't find node {node_id}, it will return 404.
21
+
22
+Normal response codes: 202
23
+
24
+Error codes: 400, 401, 403, 404
25
+
26
+
27
+Request
28
+-------
29
+
30
+.. rest_parameters:: parameters.yaml
31
+
32
+   - node_id: node_id
33
+   - manage_boot: manage_boot
34
+
35
+
36
+Response
37
+--------
38
+
39
+The response will be empty body.
40
+
41
+Get Introspection status
42
+========================
43
+
44
+.. rest_method::  GET /v1/introspection/{node_id}
45
+
46
+Get node introspection status.
47
+
48
+In case missing or invalid authentication response code will be 401 and 403.
49
+If Inspector don't find node {node_id}, it will return 404.
50
+
51
+Normal response codes: 200
52
+
53
+Error codes: 400, 401, 403, 404
54
+
55
+Request
56
+-------
57
+
58
+.. rest_parameters:: parameters.yaml
59
+
60
+   - node_id: node_id
61
+
62
+
63
+Response
64
+--------
65
+
66
+The response will contain the complete introspection info, like
67
+create, 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
+
85
+List All Introspection statuses
86
+===============================
87
+
88
+.. rest_method::  GET /v1/introspection/
89
+
90
+Returned status list is sorted by the ``started_at, uuid`` attribute pair,
91
+newer items first.
92
+
93
+In case missing or invalid authentication response code will be 401 and 403.
94
+
95
+Normal response codes: 200
96
+
97
+Error codes: 400, 401, 403
98
+
99
+Request
100
+-------
101
+
102
+Status list may be paginated with these query string fields:
103
+
104
+.. rest_parameters:: parameters.yaml
105
+
106
+   - marker: marker
107
+   - limit: limit
108
+
109
+
110
+Response
111
+--------
112
+
113
+The 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
+
132
+Abort Introspection
133
+===================
134
+
135
+.. rest_method::  POST /v1/introspection/{node_id}/abort
136
+
137
+Abort running introspection.
138
+
139
+Normal response codes: 202
140
+
141
+Error 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
+
148
+Request
149
+-------
150
+
151
+.. rest_parameters:: parameters.yaml
152
+
153
+   - node_id: node_id
154
+
155
+
156
+Get Introspection data
157
+======================
158
+
159
+.. rest_method::  GET /v1/introspection/{node_id}/data
160
+
161
+Return 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
+
168
+Normal response codes: 200
169
+
170
+Error 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
+
176
+Request
177
+-------
178
+
179
+Status 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
+
187
+Response
188
+--------
189
+
190
+The 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
+
198
+Reapply Introspection on stored data
199
+====================================
200
+
201
+.. rest_method::  POST /v1/introspection/{node_id}/data/unprocessed
202
+
203
+This method riggers introspection on stored unprocessed data.
204
+No 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
+
211
+Normal response codes: 202
212
+
213
+Error 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
+
221
+Request
222
+-------
223
+
224
+.. rest_parameters:: parameters.yaml
225
+
226
+  - node_id: node_id

+ 155
- 0
api-ref/source/introspection-api-v1-rules.inc View File

@@ -0,0 +1,155 @@
1
+.. -*- rst -*-
2
+
3
+===================
4
+Introspection Rules
5
+===================
6
+
7
+Simple JSON-based DSL to define rules, which run during introspection.
8
+
9
+
10
+Create Introspection Rule
11
+=========================
12
+
13
+.. rest_method::  POST /v1/rules
14
+
15
+Create a new introspection rule.
16
+
17
+Normal response codes:
18
+
19
+* 200 - OK for API version < 1.6
20
+* 201 - OK for API version 1.6 and higher
21
+
22
+Error codes:
23
+
24
+* 400 - wrong rule format
25
+
26
+Request
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
+
42
+Response
43
+--------
44
+
45
+The response will contain full rule object, also ``condition``
46
+section 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
+
63
+Get Introspection Rules
64
+=======================
65
+
66
+.. rest_method::  GET /v1/rules
67
+
68
+List all introspection rules
69
+
70
+Normal response codes: 200
71
+
72
+Response
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
+
87
+Delete Introspection Rules
88
+==========================
89
+
90
+.. rest_method::  DELETE /v1/rules
91
+
92
+Delete all introspection rules
93
+
94
+Normal response codes: 204
95
+
96
+
97
+
98
+Get Introspection Rule
99
+======================
100
+
101
+.. rest_method::  GET /v1/rules/{uuid}
102
+
103
+Get one introspection rule by its ``uuid``
104
+
105
+Normal response codes: 202
106
+
107
+Error codes:
108
+
109
+* 404 - rule not found
110
+
111
+Request
112
+-------
113
+
114
+.. rest_parameters:: parameters.yaml
115
+
116
+    - uuid: uuid
117
+
118
+
119
+Response
120
+--------
121
+
122
+The 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
+
137
+Delete Introspection Rule
138
+=========================
139
+
140
+.. rest_method::  DELETE /v1/rules/{uuid}
141
+
142
+Delete introspection rule by ``uuid``.
143
+
144
+Normal response codes: 204
145
+
146
+Error codes:
147
+
148
+* 404 - rule not found
149
+
150
+Request
151
+-------
152
+
153
+.. rest_parameters:: parameters.yaml
154
+
155
+    - uuid: uuid

+ 81
- 0
api-ref/source/introspection-api-versions.inc View File

@@ -0,0 +1,81 @@
1
+.. -*- rst -*-
2
+
3
+============
4
+API versions
5
+============
6
+
7
+Concepts
8
+========
9
+
10
+In order to bring new features to users over time, the Ironic
11
+Inspector 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
+
17
+The Version APIs work differently from other APIs as they *do not* require authentication.
18
+
19
+All API requests support the ``X-OpenStack-Ironic-Inspector-API-Version`` header.
20
+This header SHOULD be supplied with every request; in the absence of this header,
21
+server will default to current supported version in all responses.
22
+
23
+List API versions
24
+=================
25
+
26
+.. rest_method::  GET /
27
+
28
+This fetches all the information about all known major API versions in the
29
+deployment. Links to more specific information will be provided for each major
30
+API version, as well as information about supported min and max microversions.
31
+
32
+Normal response codes: 200
33
+
34
+Request
35
+-------
36
+
37
+Response 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
+
54
+Show v1 API
55
+===========
56
+
57
+.. rest_method::  GET /v1/
58
+
59
+Show all the resources within the Ironic Inspector v1 API.
60
+
61
+Normal response codes: 200
62
+
63
+Request
64
+-------
65
+
66
+Response 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

+ 257
- 0
api-ref/source/parameters.yaml View File

@@ -0,0 +1,257 @@
1
+# variables in header
2
+x-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
9
+x-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
15
+x-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
21
+x-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
34
+node_id:
35
+  description: |
36
+    The UUID of the Ironic node.
37
+  in: path
38
+  required: true
39
+  type: string
40
+
41
+uuid:
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
49
+limit:
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
60
+manage_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
67
+marker:
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
78
+actions:
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
85
+bmc_address:
86
+  description: |
87
+    IP address of the node's BMC
88
+  in: body
89
+  required: false
90
+  type: string
91
+boot_interface:
92
+  description: |
93
+    MAC address of the NIC that the machine PXE booted from
94
+  in: body
95
+  required: false
96
+  type: string
97
+conditions:
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
104
+cpu:
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
111
+description:
112
+  description: |
113
+    Rule human-readable description.
114
+  in: body
115
+  required: false
116
+  type: string
117
+disks:
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
125
+error:
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
132
+finished:
133
+  description: |
134
+    Whether introspection has finished for this node.
135
+  in: body
136
+  required: true
137
+  type: boolean
138
+finished_at:
139
+  description: |
140
+    UTC ISO8601 timestamp of introspection finished or ``null``.
141
+  in: body
142
+  required: true
143
+  type: string
144
+href:
145
+  description: |
146
+    A bookmark link to resource object.
147
+  in: body
148
+  required: true
149
+  type: string
150
+id:
151
+  description: |
152
+    API microversion, eg, "1.12".
153
+  in: body
154
+  required: true
155
+  type: string
156
+interfaces:
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
163
+inventory:
164
+  description: Dictionary with hardware inventory keys.
165
+  in: body
166
+  required: true
167
+  type: object
168
+links:
169
+  description: |
170
+    A list of relative links. Includes the self and
171
+    bookmark links.
172
+  in: body
173
+  required: true
174
+  type: array
175
+logs:
176
+  description: Base64-encoded logs from the ramdisk.
177
+  in: body
178
+  required: false
179
+  type: string
180
+memory:
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
187
+name:
188
+  description: |
189
+    Resource name, like `introspection`, `rules`.
190
+  in: body
191
+  required: true
192
+  type: string
193
+node_uuid:
194
+  description: Ironic node uui
195
+  in: body
196
+  required: true
197
+  type: string
198
+rel:
199
+  description: |
200
+    The relationship between the version and the href.
201
+  in: body
202
+  required: true
203
+  type: string
204
+resources:
205
+  description: |
206
+    A list of available API resources.
207
+  in: body
208
+  required: true
209
+  type: array
210
+root_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
217
+started_at:
218
+  description: |
219
+    UTC ISO8601 timestamp of introspection start.
220
+  in: body
221
+  required: true
222
+  type: string
223
+state:
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
232
+status:
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
246
+version:
247
+  description: |
248
+    Versioning of this API response, eg. "1.12".
249
+  in: body
250
+  required: true
251
+  type: string
252
+versions:
253
+  description: |
254
+    Array of information about currently supported versions.
255
+  in: body
256
+  required: true
257
+  type: array

+ 14
- 0
api-ref/source/samples/api-root-response.json View File

@@ -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
+}

+ 3
- 0
api-ref/source/samples/api-v1-common-node-uuid.json View File

@@ -0,0 +1,3 @@
1
+{
2
+  "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
3
+}

+ 3
- 0
api-ref/source/samples/api-v1-common-rule-uuid.json View File

@@ -0,0 +1,3 @@
1
+{
2
+  "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
3
+}

+ 75
- 0
api-ref/source/samples/api-v1-continue-request.json View File

@@ -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
+}

+ 26
- 0
api-ref/source/samples/api-v1-create-rule-request.json View File

@@ -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
+}

+ 36
- 0
api-ref/source/samples/api-v1-create-rule-response.json View File

@@ -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
+}

+ 114
- 0
api-ref/source/samples/api-v1-data-introspection-response.json View File

@@ -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
+}

+ 14
- 0
api-ref/source/samples/api-v1-get-introspection-response.json View File

@@ -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
+}

+ 32
- 0
api-ref/source/samples/api-v1-get-introspections-response.json View File

@@ -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
+}

+ 41
- 0
api-ref/source/samples/api-v1-get-rule-response.json View File

@@ -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
+}

+ 24
- 0
api-ref/source/samples/api-v1-get-rules-response.json View File

@@ -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
+}

+ 31
- 0
api-ref/source/samples/api-v1-root-response.json View File

@@ -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
+}

+ 1
- 0
lower-constraints.txt View File

@@ -56,6 +56,7 @@ netaddr==0.7.18
56 56
 netifaces==0.10.6
57 57
 openstackdocstheme==1.18.1
58 58
 openstacksdk==0.12.0
59
+os-api-ref==1.4.0
59 60
 os-client-config==1.29.0
60 61
 os-service-types==1.2.0
61 62
 os-testr==1.0.0

+ 1
- 1
test-requirements.txt View File

@@ -8,10 +8,10 @@ hacking>=1.0.0,<1.2.0 # Apache-2.0
8 8
 mock>=2.0.0 # BSD
9 9
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
10 10
 openstackdocstheme>=1.18.1 # Apache-2.0
11
+os-api-ref>=1.4.0 # Apache-2.0
11 12
 stestr>=1.0.0 # Apache-2.0
12 13
 reno>=2.5.0 # Apache-2.0
13 14
 fixtures>=3.0.0 # Apache-2.0/BSD
14 15
 testresources>=2.0.0 # Apache-2.0/BSD
15 16
 testscenarios>=0.4 # Apache-2.0/BSD
16 17
 oslotest>=3.2.0 # Apache-2.0
17
-

+ 6
- 0
tox.ini View File

@@ -19,6 +19,12 @@ passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY
19 19
 basepython = python3
20 20
 commands = {posargs}
21 21
 
22
+[testenv:api-ref]
23
+basepython = python3
24
+whitelist_externals = bash
25
+commands =
26
+  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
27
+
22 28
 [testenv:releasenotes]
23 29
 basepython = python3
24 30
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html

+ 1
- 0
zuul.d/legacy-ironic-inspector-jobs.yaml View File

@@ -15,6 +15,7 @@
15 15
     irrelevant-files:
16 16
       - ^test-requirements.txt$
17 17
       - ^.*\.rst$
18
+      - ^api-ref/.*$
18 19
       - ^doc/.*$
19 20
       - ^ironic_inspector/test/(?!.*tempest).*$
20 21
       - ^ironic_inspector/locale/.*$

Loading…
Cancel
Save