openstack
/
senlin
Code Issues Proposed changes

Migrate to os-api-ref upstream library 

This migrates to the common upstream os-api-ref library. This patch
currently fails because the Senlin team isn't using the parameters
specification as expected. The 'in' field maps to swagger, and must be
one of 'header', 'path', 'query', 'body'.

Change-Id: I5998e4b4343965b24f827a43fed5bf0633200782
This commit is contained in:
Sean Dague 2016-05-18 08:36:03 -04:00 committed by Qiming Teng
parent db04d6cd3c
commit dcd2ef6a53
15 changed files with 192 additions and 782 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
api-ref/ext/__init__.py
View File

335
api-ref/ext/rest_parameters.py
View File

@ -1,335 +0,0 @@
# 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.
"""This provides a sphinx extension able to create the HTML needed
for the api-ref website.
It contains 2 new stanzas.
.. rest_method:: GET /foo/bar
Which is designed to be used as the first stanza in a new section to
state that section is about that REST method. During processing the
rest stanza will be reparented to be before the section in question,
and used as a show/hide selector for it's details.
.. rest_parameters:: file.yaml
- name1: name_in_file1
- name2: name_in_file2
- name3: name_in_file3
Which is designed to build structured tables for either response or
request parameters. The stanza takes a value which is a file to lookup
details about the parameters in question.
The contents of the stanza are a yaml list of key / value pairs. The
key is the name of the parameter to be shown in the table. The value
is the key in the file.yaml where all other metadata about the
parameter will be extracted. This allows for reusing parameter
definitions widely in API definitions, but still providing for control
in both naming and ordering of parameters at every declaration.
"""
from docutils import nodes
from docutils.parsers.rst.directives.tables import Table
from docutils.statemachine import ViewList
from sphinx.util.compat import Directive
import yaml
def full_name(cls):
return cls.__module__ + '.' + cls.__name__
class rest_method(nodes.Part, nodes.Element):
"""rest_method custom node type
We specify a custom node type for rest_method so that we can
accumulate all the data about the rest method, but not render as
part of the normal rendering process. This means that we need a
renderer for every format we wish to support with this.
"""
pass
class RestMethodDirective(Directive):
# this enables content in the directive
has_content = True
def run(self):
lineno = self.state_machine.abs_line_number()
target = nodes.target()
section = nodes.section(classes=["detail-control"])
# env = self.state.document.settings.env
# env.app.info("Parent %s" % self.state.parent.attributes)
node = rest_method()
# TODO(sdague): this is a super simplistic parser, should be
# more robust.
method, sep, url = self.content[0].partition(' ')
node['method'] = method
node['url'] = url
node['target'] = self.state.parent.attributes['ids'][0]
# We need to build a temporary target that we can replace
# later in the processing to get the TOC to resolve correctly.
temp_target = "%s-selector" % node['target']
target = nodes.target(ids=[temp_target])
self.state.add_target(temp_target, '', target, lineno)
section += node
return [target, section]
class RestParametersDirective(Table):
headers = ["Name", "In", "Type", "Description"]
def yaml_from_file(self, fpath):
"""Collect Parameter stanzas from inline + file.
This allows use to reference an external file for the actual
parameter definitions.
"""
# self.app.info("Fpath: %s" % fpath)
with open(fpath, 'r') as stream:
try:
lookup = yaml.load(stream)
except yaml.YAMLError as exc:
self.app.warn(exc)
raise
content = "\n".join(self.content)
parsed = yaml.load(content)
# self.app.info("Params loaded is %s" % parsed)
# self.app.info("Lookup table looks like %s" % lookup)
new_content = list()
for paramlist in parsed:
definition = {}
name = None
for key, value in paramlist.items():
if key.lower() == 'optional':
definition['optional'] = bool(value)
elif value in lookup:
name = key
definition.update(lookup[value])
else:
self.env.warn(
self.env.docname,
"No field definition for %s found in %s. Skipping." %
(value, fpath))
if name:
new_content.append((name, definition))
# self.app.info("New content %s" % new_content)
self.yaml = new_content
def run(self):
self.env = self.state.document.settings.env
self.app = self.env.app
# Make sure we have some content, which should be yaml that
# defines some parameters.
if not self.content:
error = self.state_machine.reporter.error(
'No parameters defined',
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return [error]
if not len(self.arguments) >= 1:
self.state_machine.reporter.error(
'No reference file defined',
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return [error]
# NOTE(sdague): it's important that we pop the arg otherwise
# we end up putting the filename as the table caption.
rel_fpath, fpath = self.env.relfn2path(self.arguments.pop())
self.yaml_from_file(fpath)
self.max_cols = len(self.headers)
# TODO(sdague): it would be good to dynamically set column
# widths (or basically make the colwidth thing go away
# entirely)
self.options['widths'] = (20, 10, 10, 60)
self.col_widths = self.get_column_widths(self.max_cols)
# Actually convert the yaml
title, messages = self.make_title()
# self.app.info("Title %s, messages %s" % (title, messages))
table_node = self.build_table()
self.add_name(table_node)
if title:
table_node.insert(0, title)
return [table_node] + messages
def get_rows(self, table_data):
rows = []
groups = []
trow = nodes.row()
entry = nodes.entry()
para = nodes.paragraph(text=unicode(table_data))
entry += para
trow += entry
rows.append(trow)
return rows, groups
def collect_rows(self):
# Add a column for a field. In order to have the RST inside
# these fields get rendered, we need to use the
# ViewList. Note, ViewList expects a list of lines, so chunk
# up our content as a list to make it happy.
def add_col(value):
entry = nodes.entry()
result = ViewList(value.split('\n'))
self.state.nested_parse(result, 0, entry)
return entry
rows = []
groups = []
try:
# self.app.info("Parsed content is: %s" % self.yaml)
for key, values in self.yaml:
min_version = values.get('min_version', '')
desc = values.get('description', '')
classes = []
if min_version:
desc += ("\n\n**New in version %s**\n" % min_version)
min_ver_css_name = ("rp_min_ver_" +
str(min_version).replace('.', '_'))
classes.append(min_ver_css_name)
trow = nodes.row(classes=classes)
name = key
if values.get('optional') is True:
name += " (Optional)"
trow += add_col(name)
trow += add_col(values.get('in'))
trow += add_col(values.get('type'))
trow += add_col(desc)
rows.append(trow)
except AttributeError as exc:
self.app.warn("Failure on key: %s, values: %s. %s" %
(key, values, exc))
raise
return rows, groups
def build_table(self):
table = nodes.table()
tgroup = nodes.tgroup(cols=len(self.headers))
table += tgroup
# TODO(sdague): it would be really nice to figure out how not
# to have this stanza, it kind of messes up all of the table
# formatting because it doesn't let tables just be the right
# size.
tgroup.extend(
nodes.colspec(colwidth=col_width, colname='c' + str(idx))
for idx, col_width in enumerate(self.col_widths)
)
thead = nodes.thead()
tgroup += thead
row_node = nodes.row()
thead += row_node
row_node.extend(nodes.entry(h, nodes.paragraph(text=h))
for h in self.headers)
tbody = nodes.tbody()
tgroup += tbody
rows, groups = self.collect_rows()
tbody.extend(rows)
table.extend(groups)
return table
def rest_method_html(self, node):
tmpl = """
<div class="row operation-grp">
<div class="col-md-1 operation">
<a name="%(target)s" class="operation-anchor" href="#%(target)s">
<span class="glyphicon glyphicon-link"></span></a>
<span class="label label-success">%(method)s</span>
</div>
<div class="col-md-5">%(url)s</div>
<div class="col-md-5">%(desc)s</div>
<div class="col-md-1">
<button
class="btn btn-info btn-sm btn-detail"
data-target="#%(target)s-detail"
data-toggle="collapse"
id="%(target)s-detail-btn"
>detail</button>
</div>
</div>"""
self.body.append(tmpl % node)
raise nodes.SkipNode
def resolve_rest_references(app, doctree):
"""Resolve RST reference."""
for node in doctree.traverse():
if isinstance(node, rest_method):
rest_node = node
rest_method_section = node.parent
rest_section = rest_method_section.parent
gp = rest_section.parent
# Added required classes to the top section
rest_section.attributes['classes'].append('api-detail')
rest_section.attributes['classes'].append('collapse')
# Pop the title off the collapsed section
title = rest_section.children.pop(0)
rest_node['desc'] = title.children[0]
# In order to get the links in the sidebar to be right, we
# have to do some id flipping here late in the game. The
# rest_method_section has basically had a dummy id up
# until this point just to keep it from colliding with
# it's parent.
rest_section.attributes['ids'][0] = (
"%s-detail" % rest_section.attributes['ids'][0])
rest_method_section.attributes['ids'][0] = rest_node['target']
# Pop the overall section into it's grand parent,
# right before where the current parent lives
idx = gp.children.index(rest_section)
rest_section.remove(rest_method_section)
gp.insert(idx, rest_method_section)
def setup(app):
"""Setup environment for doc build."""
app.add_node(rest_method,
html=(rest_method_html, None))
app.add_directive('rest_parameters', RestParametersDirective)
app.add_directive('rest_method', RestMethodDirective)
app.add_stylesheet('bootstrap.min.css')
app.add_stylesheet('api-site.css')
app.add_javascript('bootstrap.min.js')
app.add_javascript('api-site.js')
app.connect('doctree-read', resolve_rest_references)
return {'version': '0.1'}

53
api-ref/source/_static/api-site.css
View File

@ -1,53 +0,0 @@
tt.literal {
padding: 2px 4px;
font-size: 90%;
color: #c7254e;
white-space: nowrap;
background-color: #f9f2f4;
border-radius: 4px;
}
pre {
display: block;
padding: 9.5px;
margin: 0 0 10px;
font-size: 13px;
line-height: 1.428571429;
color: #333;
word-break: break-all;
word-wrap: break-word;
background-color: #f5f5f5;
border: 1px solid #ccc;
border-radius: 4px;
}
tbody>tr:nth-child(odd)>td,
tbody>tr:nth-child(odd)>th {
background-color: #f9f9f9;
}
table>thead>tr>th, table>tbody>tr>th, table>tfoot>tr>th, table>thead>tr>td, table>tbody>tr>td, table>tfoot>tr>td {
padding: 8px;
line-height: 1.428571429;
vertical-align: top;
border-top: 1px solid #ddd;
}
td>p {
margin: 0 0 0.5em;
}
div.document {
width: 80% !important;
}
@media (max-width: 1200px) {
div.document {
width: 960px !important;
}
}
.operation-grp {
padding-top: 0.5em;
padding-bottom: 1em;
}

95
api-ref/source/_static/api-site.js
View File

@ -1,95 +0,0 @@
(function() {
var pageCache;
$(document).ready(function() {
pageCache = $('.api-documentation').html();
// Show the proper JSON/XML example when toggled
$('.example-select').on('change', function(e) {
$(e.currentTarget).find(':selected').tab('show')
});
// Change the text on the expando buttons when appropriate
$('.api-detail')
.on('hide.bs.collapse', function(e) {
processButton(this, 'detail');
})
.on('show.bs.collapse', function(e) {
processButton(this, 'close');
});
// Wire up the search button
$('#search-btn').on('click', function(e) {
searchPage();
});
// Wire up the search box enter
$('#search-box').on('keydown', function(e) {
if (e.keyCode === 13) {
searchPage();
return false;
}
});
});
/**
* highlight terms based on the regex in the provided $element
*/
function highlightTextNodes($element, regex) {
var markup = $element.html();
// Do regex replace
// Inject span with class of 'highlighted termX' for google style highlighting
$element.html(markup.replace(regex, '>$1<span class="highlight">$2</span>$3<'));
}
function searchPage() {
$(".api-documentation").html(pageCache);
//make sure that all div's are expanded/hidden accordingly
$('.api-detail.in').each(function (e) {
$(this).collapse('hide');
});
var startTime = new Date().getTime(),
searchTerm = $('#search-box').val();
// The regex is the secret, it prevents text within tag declarations to be affected
var regex = new RegExp(">([^<]*)?(" + searchTerm + ")([^>]*)?<", "ig");
highlightTextNodes($('.api-documentation'), regex);
// Once we've highlighted the node, lets expand any with a search match in them
$('.api-detail').each(function () {
var $elem = $(this);
if ($elem.html().indexOf('<span class="highlight">') !== -1) {
$elem.collapse('show');
processButton($elem, 'close');
}
});
// log the results
if (console.log) {
console.log("search completed in: " + ((new Date().getTime()) - startTime) + "ms");
}
$('.api-detail')
.on('hide.bs.collapse', function (e) {
processButton(this, 'detail');
})
.on('show.bs.collapse', function (e) {
processButton(this, 'close');
});
}
/**
* Helper function for setting the text, styles for expandos
*/
function processButton(button, text) {
$('#' + $(button).attr('id') + '-btn').text(text)
.toggleClass('btn-info')
.toggleClass('btn-default');
}
})();

5
api-ref/source/_static/bootstrap.min.css vendored
View File

File diff suppressed because one or more lines are too long

6
api-ref/source/_static/bootstrap.min.js vendored
View File

File diff suppressed because one or more lines are too long

8
api-ref/source/actions.inc
View File

@ -47,7 +47,6 @@ Reponse Parameters
- cause: cause
- context: action_context
- created_at: created_at
in: action
- depended_by: depended_by
- depends_on: depends_on
- start_time: start_time
@ -56,16 +55,13 @@ Reponse Parameters
- inputs: inputs
- interval: interval
- name: name
in: action
- outputs: outputs
- owner: action_owner
- status: action_status
- status_reason: status_reason
in: action
- target: target
- timeout: timeout
- updated_at: updated_at
in: action
Response Example
----------------
@ -108,7 +104,6 @@ Response Parameters:
- cause: cause
- context: action_context
- created_at: created_at
in: action
- depended_by: depended_by
- depends_on: depends_on
- start_time: start_time
@ -117,16 +112,13 @@ Response Parameters:
- inputs: inputs
- interval: interval
- name: name
in: action
- outputs: outputs
- owner: action_owner
- status: action_status
- status_reason: status_reason
in: action
- target: target
- timeout: timeout
- updated_at: updated_at
in: action
Response Example
----------------

55
api-ref/source/clusters.inc
View File

@ -102,21 +102,12 @@ Request Parameters
- OpenStack-API-Version: microversion
- cluster: cluster
- name: name
in: cluster
- desired_capacity: desired_capacity
optional: true
- profile_id: profile_id_url
in: cluster
- min_size: min_size
optional: true
- timeout: timeout
optional: true
- max_size: max_size
optional: true
- metadata: metadata
in: cluster
optional: true
Request Example
---------------
@ -133,19 +124,15 @@ Response Parameters
- location: location
- cluster: cluster
- created_at: created_at
in: cluster
- data: cluster_data
- desired_capacity: desired_capacity
- domain: domain
in: cluster
- id: cluster_id
- init_at: init_at
- max_size: max_size
- metadata: metadata
in: cluster
- min_size: min_size
- name: cluster_name
in: cluster
- nodes: cluster_nodes
- policies: cluster_policies_property
- profile_id: cluster_profile_id
@ -154,13 +141,9 @@ Response Parameters
in: cluster
- status: cluster_status
- status_reason: status_reason
in: cluster
- timeout: timeout
- updated_at: updated_at
in: cluster
- user: user
in: cluster
Response Example
----------------
@ -205,29 +188,22 @@ Response Parameters
- data: cluster_data
- desired_capacity: desired_capacity
- domain: domain
in: cluster
- id: cluster_id
- init_at: init_at
- max_size: max_size
- metadata: metadata
in: cluster
- min_size: min_size
- name: cluster_name
in: cluster
- nodes: cluster_nodes
- policies: cluster_policies_property
- profile_id: cluster_profile_id
- profile_name: cluster_profile_name
- project: project
in: cluster
- status: cluster_status
- status_reason: status_reason
in: cluster
- timeout: timeout
- updated_at: updated_at
in: cluster
- user: user
in: cluster
Response Example
----------------
@ -262,15 +238,10 @@ Request
- cluster_id: cluster_id_url
- cluster: cluster
- name: cluster_name
optional: true
- profile_id: profile_id_url
in: cluster
optional: true
- profile_id: cluster_profile_identity
- timeout: timeout
optional: true
- metadata: metadata
in: cluster
optional: true
Request Example
---------------
@ -287,33 +258,25 @@ Response Parameters
- location: location
- cluster: cluster
- created_at: created_at
in: cluster
- data: cluster_data
- desired_capacity: desired_capacity
- domain: domain
in: cluster
- id: cluster_id
- init_at: init_at
- max_size: max_size
- metadata: metadata
in: cluster
- min_size: min_size
- name: cluster_name
in: cluster
- nodes: cluster_nodes
- policies: cluster_policies_property
- profile_id: cluster_profile_id
- profile_name: cluster_profile_name
- project: project
in: cluster
- status: cluster_status
- status_reason: status_reason
in: cluster
- timeout: timeout
- updated_at: updated_at
in: cluster
- user: user
in: cluster
Response Example
----------------
@ -612,11 +575,8 @@ Request Parameters
- OpenStack-API-Version: microversion
- cluster_id: cluster_id_url
- action: action_request
- policy_id: policy_id_url
in: action
- policy_id: policy_identity
- enabled: cluster_policy_enabled
in: action
optional: true
The ``action_name`` in the request body has to be ``attach_policy``.
@ -659,8 +619,7 @@ Request Parameters
- OpenStack-API-Version: microversion
- cluster_id: cluster_id_url
- action: action_request
- policy_id: policy_id_url
in: action
- policy_id: policy_identity
The ``action_name`` in the request body has to be ``detach_policy``.
@ -703,10 +662,8 @@ Request Parameters
- OpenStack-API-Version: microversion
- cluster_id: cluster_id_url
- action: action_request
- policy_id: policy_id_url
in: action
- policy_id: policy_identity
- enabled: cluster_policy_enabled
in: action
The ``action_name`` in the request body has to be ``update_policy``.
@ -750,7 +707,6 @@ Request Parameters
- cluster_id: cluster_id_url
- action: action_request
- params: check_params
in: action
The ``action_name`` in the request body has to be ``check``.
@ -794,7 +750,6 @@ Request Parameters
- cluster_id: cluster_id_url
- action: action_request
- params: recover_params
in: action
The ``action_name`` in the request body has to be ``recover``.

4
api-ref/source/conf.py
View File

@ -41,7 +41,7 @@ sys.path.insert(0, os.path.abspath('./'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'ext.rest_parameters',
'os_api_ref',
'oslosphinx',
]
@ -138,7 +138,7 @@ pygments_style = 'sphinx'
# 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']
# html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.

14
api-ref/source/events.inc
View File

@ -33,9 +33,7 @@ Request Parameters
- obj_id: obj_id_query
- obj_type: obj_type_query
- obj_name: obj_name_query
- cluster_id: cluster_id
in: query
optional: True
- cluster_id: cluster_identity_query
- action: action_name_query
Response Parameters
@ -45,22 +43,17 @@ Response Parameters
- events: events
- action: action_name
in: event
- cluster_id: cluster_id
in: event
- id: event_id
- level: event_level
- obj_id: obj_id
- obj_name: obj_name
- obj_type: obj_type
- project: project
in: event
- status: event_status
- status_reason: status_reason
in: event
- timestamp: event_timestamp
- user: user
in: event
Response Example
----------------
@ -101,22 +94,17 @@ Response Parameters
- event: event
- action: action_name
in: event
- cluster_id: cluster_id
in: event
- id: event_id
- level: event_level
- obj_id: obj_id
- obj_name: obj_name
- obj_type: obj_type
- project: project
in: event
- status: event_status
- status_reason: status_reason
in: event
- timestamp: event_timestamp
- user: user
in: event
Response Example
----------------

56
api-ref/source/nodes.inc
View File

@ -32,9 +32,7 @@ Request Parameters
- marker: marker
- sort: sort
- global_project: global_project
- cluster_id: cluster_id
in: query
optional: true
- cluster_id: cluster_identity_query
- name: name_query
- status: status_query
@ -45,33 +43,23 @@ Response Parameters
- nodes: nodes
- cluster_id: cluster_id
in: node
- created_at: created_at
in: node
- data: node_data
- domain: domain
in: node
- id: node_id
- index: index
- init_at: init_at
in: node
- metadata: metadata
in: node
- name: name
in: node
- physical_id: physical_id
- profile_id: node_profile_id
- profile_name: node_profile_name
- project: project
in: node
- role: role
- status: node_status
- status_reason: status_reason
in: node
- updated_at: updated_at
in: node
- user: user
in: node
Response Example
----------------
@ -104,18 +92,10 @@ Request Parameters
- OpenStack-API-Version: microversion
- node: node
- role: role
optional: true
- profile_id: profile_id_url
in: node
- cluster_id: cluster_id_url
in: node
optional: true
- profile_id: profile_identity
- cluster_id: cluster_identity
- name: name
in: node
optional: true
- metadata: metadata
in: node
optional: true
Request Example
---------------
@ -131,33 +111,23 @@ Response Parameters
- location: location
- node: node
- cluster_id: cluster_id
in: node
- created_at: created_at
in: node
- data: node_data
- domain: domain
in: node
- id: node_id
- index: index
- init_at: init_at
in: node
- metadata: metadata
in: node
- name: name
in: node
- physical_id: physical_id
- profile_id: node_profile_id
- profile_name: node_profile_name
- project: project
in: node
- role: role
- status: node_status
- status_reason: status_reason
in: node
- updated_at: updated_at
in: node
- user: user
in: node
Response Example
----------------
@ -192,7 +162,6 @@ Request Parameters
- OpenStack-API-Version: microversion
- node_id: node_id_url
- show_details: show_details
optional: true
Response Example
----------------
@ -228,16 +197,9 @@ Request
- node_id: node_id_url
- node: node
- name: name
in: node
optional: true
- profile_id: profile_id_url
in: node
optional: true
- profile_id: profile_identity
- role: role
optional: true
- metadata: metadata
in: node
optional: true
Request Example
---------------
@ -253,33 +215,23 @@ Response Parameters
- location: location
- node: node
- cluster_id: cluster_id
in: node
- created_at: created_at
in: node
- data: node_data
- domain: domain
in: node
- id: node_id
- index: index
- init_at: init_at
in: node
- metadata: metadata
in: node
- name: name
in: node
- physical_id: physical_id
- profile_id: node_profile_id
- profile_name: node_profile_name
- project: project
in: node
- role: role
- status: node_status
- status_reason: status_reason
in: node
- updated_at: updated_at
in: node
- user: user
in: node
Response Example
----------------

307
api-ref/source/parameters.yaml
View File

@ -4,43 +4,12 @@ action:
description: |
A structured definition of an action object.
action_action:
type: string
in: action
description: |
A string representation of the action for execution.
action_action_query:
type: string
in: query
description: |
Filters the resulted list using the ``action`` field of the object.
action_context:
type: object
in: action
description: |
A collection of key-value pairs that are used as security context when
executing the action.
action_id:
type: UUID
in: action
description: |
An UUID that uniquely identifies an action object.
action_id_url:
type: string
in: URL
description: |
The name or short-ID or UUID that identifies an action object.
action_name:
type: string
in: body
description: |
The name of an action object.
action_name_query:
type: string
in: query
@ -49,9 +18,47 @@ action_name_query:
Filters the response by the action name associated with an event.
Use this filter multiple times to filter by multiple actions.
action_status_query:
type: string
in: query
optional: true
description: |
Filters the results by the ``status`` property of an action object.
action_action:
type: string
in: body
description: |
A string representation of the action for execution.
action_context:
type: object
in: body
description: |
A collection of key-value pairs that are used as security context when
executing the action.
action_id:
type: UUID
in: body
description: |
An UUID that uniquely identifies an action object.
action_id_url:
type: string
in: path
description: |
The name or short-ID or UUID that identifies an action object.
action_name:
type: string
in: body
description: |
The name of an action object.
action_owner:
type: string
in: action
in: body
description: |
The UUID of the owning engine that is currently locking the action for
execution.
@ -75,20 +82,13 @@ action_request:
action_status:
type: string
in: action
in: body
description: |
A string representation of the current status of the action.
action_status_query:
type: string
in: query
optional: true
description: |
Filters the results by the ``status`` property of an action object.
action_timeout:
type: integer
in: action
in: body
description: |
The number of seconds after which an unfinished action execution will be
treated as timeout.
@ -101,21 +101,21 @@ actions:
adjustment_max_size:
type: integer
in: action
in: body
optional: true
description: |
The value to be set as the new ``max_size`` of the cluster.
adjustment_min_size:
type: integer
in: action
in: body
optional: true
description: |
The value to be set as the new ``min_size`` of the cluster.
adjustment_min_step:
type: integer
in: action
in: body
optional: true
description: |
When ``adjustment_type`` is set to ``CHANGE_IN_PERCENTAGE``, often times
@ -125,7 +125,7 @@ adjustment_min_step:
adjustment_number:
type: number
in: action
in: body
optional: true
description: |
The number of adjustment. The interpretion of the value depends on the
@ -138,7 +138,7 @@ adjustment_number:
adjustment_strict:
type: bool
in: action
in: body
optional: true
default: false
description: |
@ -153,7 +153,7 @@ adjustment_strict:
adjustment_type:
type: string
in: action
in: body
optional: true
description: |
The type of size adjustment. The valid values are:
@ -183,25 +183,25 @@ build_info:
build_info_api:
type: object
in: build_info
in: body
description: |
Revision information of Senlin API service.
build_info_engine:
type: object
in: build_info
in: body
description: |
Revision information of Senlin engine service.
cause:
type: string
in: action
in: body
description: |
An explanation why an action was started.
check_params:
type: object
in: action
in: body
optional: true
description: |
The optional parameters provided to a cluster check operation. The detailed
@ -215,25 +215,39 @@ cluster:
cluster_data:
type: object
in: cluster
in: body
description: |
The structured data associated with the cluster.
cluster_id:
type: UUID
in: cluster
in: body
description: |
The UUID of the cluster object.
cluster_identity:
type: string
in: body
optional: True
description: |
The name, short-ID or UUID of the cluster object.
cluster_identity_query:
type: string
in: query
optional: True
description: |
The name, short-ID or UUID of the cluster object.
cluster_id_url:
type: string
in: URL
in: path
description: |
The name, UUID or short-UUID of a cluster object.
cluster_member_nodes:
type: list
in: action
in: body
optional: false
description: |
The candidate nodes to be added to or removed from a cluster. The meaning
@ -243,7 +257,8 @@ cluster_member_nodes:
cluster_name:
type: string
in: cluster
in: body
optional: True
description: |
The name of the cluster object.
@ -255,7 +270,7 @@ cluster_policies:
cluster_policies_property:
type: list
in: cluster
in: body
description: |
A list of UUIDs of the policies attached to current cluster.
@ -267,45 +282,54 @@ cluster_policy:
cluster_policy_enabled:
type: bool
in: cluster_policy
in: body
optional: True
description: |
Whether the policy is enabled on the attached cluster.
cluster_policy_id:
type: UUID
in: cluster_policy
in: body
description: |
The UUID of a cluster_policy object.
cluster_nodes:
type: list
in: cluster
in: body
description: |
A list of the UUIDs of node objects which are members of the current
cluster.
cluster_policy_property:
type: list
in: cluster
in: body
description: |
A list of the UUIDs of policy objects which are attached to the current
cluster.
cluster_profile_id:
type: UUID
in: cluster
in: body
description: |
The UUID of the profile object referenced by the current cluster.
cluster_profile_identity:
type: string
in: body
optional: True
description: |
The name, short-ID or UUID of the profile object referenced by the current
cluster.
cluster_profile_name:
type: string
in: cluster
in: body
description: |
The name of the profile object referenced by the current cluster.
cluster_status:
type: string
in: cluster
in: body
description: |
The string representation of the current status of the cluster.
@ -325,19 +349,20 @@ created_at:
depended_by:
type: list
in: action
in: body
description: |
A list of UUIDs of the actions that depend on the current action.
depends_on:
type: list
in: action
in: body
description: |
A list of UUIDs of the actions that the current action depends on.
desired_capacity:
type: integer
in: cluster
in: body
optional: True
description: |
The desired capacity of a cluster. When creating a cluster, this value is
set to 0 by default.
@ -357,7 +382,7 @@ enabled_query:
end_time:
type: float
in: action
in: body
description: |
A floating point number that represents when an action's execution has
completed.
@ -376,31 +401,31 @@ events:
event_id:
type: UUID
in: event
in: body
description: |
The UUID of an event object.
event_id_url:
type: string
in: URL
in: path
description: |
The name, UUID or short-UUID of an event object.
event_level:
type: string
in: event
in: body
description: |
The level of an event object.
event_status:
type: string
in: event
in: body
description: |
The current status of the object associated with the event.
event_timestamp:
type: string
in: event
in: body
description: |
The date and time when the event was generated. The date and time stamp
format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``.
@ -420,13 +445,13 @@ global_project:
index:
type: integer
in: node
in: body
description: |
An integer that uniquely identifies a node within its owning cluster.
init_at:
type: string
in: cluster
in: body
description: |
The date and time when the object was initialized. The date and
time stamp format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
@ -434,14 +459,14 @@ init_at:
inputs:
type: object
in: action
in: body
description: |
A collection of key-value pairs that are fed to the action as input
parameters.
interval:
type: integer
in: action
in: body
description: |
An integer that indicates the interval in seconds between two consecutive
executions of a repeatable action.
@ -475,7 +500,9 @@ marker:
max_size:
type: integer
in: cluster
default: -1
in: body
optional: True
description: |
The maximum size of a cluster, i.e. the maximum number of nodes that can
be members of the cluster. A value of -1 means that the cluster doesn't
@ -484,6 +511,7 @@ max_size:
metadata:
type: object
in: body
optional: True
description: |
A collection of key-value pairs associated with an object.
@ -499,7 +527,8 @@ microversion:
min_size:
type: integer
default: 0
in: cluster
in: body
optional: True
description: |
The minmum size of a cluster, i.e. the minimum number of nodes that can
be members of the cluster.
@ -507,6 +536,7 @@ min_size:
name:
type: string
in: body
optional: True
description:
The name of the object in question.
@ -525,37 +555,37 @@ node:
node_data:
type: object
in: node
in: body
description: |
A map containing key-value pairs associated with a node object.
node_id:
type: UUID
in: node
in: body
description: |
A UUID string that uniquely identifies a node object.
node_id_url:
type: string
in: URL
in: path
description: |
The name, short-ID or UUID of a node object.
node_profile_id:
type: UUID
in: node
in: body
description: |
The UUID of the profile object referenced by the current node object.
node_profile_name:
type: string
in: node
in: body
description: |
The name of the profile object referenced by the current node object.
node_status:
type: string
in: node
in: body
description: |
The string representation of the current status of the node object.
@ -568,7 +598,7 @@ nodes:
obj_id:
type: UUID
in: event
in: body
description: |
The UUID of an object associated with the event.
@ -582,7 +612,7 @@ obj_id_query:
obj_name:
type: string
in: event
in: body
description: |
The name of an object associated with the event.
@ -596,7 +626,7 @@ obj_name_query:
obj_type:
type: string
in: event
in: body
description: |
The type of an object associated with the event.
@ -611,14 +641,14 @@ obj_type_query:
outputs:
type: object
in: action
in: body
description: |
A collection of key-value pairs that were produced during the execution of
an action as its outputs.
physical_id:
type: UUID
in: node
in: body
description: |
The UUID of the physical resource represented by the node object.
@ -630,20 +660,20 @@ policy_type:
policy_type_name:
type: string
in: policy_type
in: body
description: |
The name of the policy type.
policy_type_schema:
type: object
in: policy_type
in: body
description: |
The schema of a policy type. The schema of a policy type varies a lot
based on the specific type implementation.
policy_type_url:
type: string
in: URL
in: path
optional: False
description: |
The name of a policy type.
@ -668,19 +698,25 @@ policy:
policy_data:
type: object
in: policy
in: body
description: |
A structured representation of data associated with a policy object.
policy_id:
type: UUID
in: policy
in: body
description: |
The UUID of a policy object.
policy_id_url:
type: string
in: URL
in: path
description: |
The name, UUID or short-UUID of a policy object.
policy_identity:
type: string
in: body
description: |
The name, UUID or short-UUID of a policy object.
@ -692,13 +728,13 @@ policy_name:
policy_spec:
type: object
in: policy
in: body
description: |
The detailed specification of a policy object.
policy_type_property:
type: string
in: policy
in: body
description: |
The ``type`` property of a policy object.
@ -710,19 +746,25 @@ profile:
profile_id:
type: UUID
in: profile
in: body
description: |
The UUID of a profile.
profile_identity:
type: string
in: body
description: |
The name, short-ID, or UUID of a profile.
profile_id_url:
type: string
in: URL
in: path
description: |
The name, UUID or short-UUID of a profile.
profile_spec:
type: object
in: profile
in: body
description: |
The detailed specification of the profile.
@ -734,7 +776,7 @@ profile_type:
profile_type_name:
type: string
in: profile_type
in: body
description: |
The name of the profile type.
@ -746,7 +788,7 @@ profile_type_property:
profile_type_schema:
type: object
in: profile_type
in: body
description: |
The schema of a profile type. The schema of a profile type varies
a lot based on the specific type implementation. All profile types
@ -758,7 +800,7 @@ profile_type_schema:
profile_type_url:
type: string
in: URL
in: path
optional: False
description: |
The name of a profile type.
@ -795,7 +837,7 @@ receivers:
receiver_action:
type: string
in: receiver
in: body
description: |
The action to initiate when the receiver is triggered. A valid value
should be the name of an action that can be applied on a cluster.
@ -808,41 +850,43 @@ receiver_action_query:
Filters the response by the action targeted by the receiver.
receiver_actor:
type: dict
in: receiver
type: object
in: body
optional: True
description: |
A map of key and value pairs to use for authentication. If omitted,
the requester is assumed to be the actor.
receiver_channel:
type: dict
in: receiver
type: object
in: body
description: |
The target to be used by user to trigger a receiver. For webhook type
of receiver, channel is a webhook URL.
receiver_id:
type: UUID
in: receiver
in: body
description: |
The UUID of the receiver object.
receiver_id_url:
type: string
in: URL
in: path
description: |
The name, UUID or short-UUID of a receiver object.
receiver_params:
type: dict
in: receiver
type: object
in: body
optional: True
description: |
A map of key and value pairs to use for action creation. Some actions
might require certain input parameters.
receiver_type:
type: string
in: receiver
in: body
description: |
The type of the receiver. The only valid value is webhook currently.
@ -855,7 +899,7 @@ receiver_type_query:
recover_params:
type: object
in: action
in: body
optional: true
description: |
The optional parameters provided to a cluster recover operation. The
@ -871,13 +915,14 @@ request_id:
role:
type: string
in: node
in: body
optional: True
description: |
A string describing the role played by a node inside a cluster.
scale_count:
type: integer
in: action
in: body
optional: true
default: 1
description: |
@ -913,7 +958,7 @@ sort:
start_time:
type: float
in: action
in: body
description: |
A floating point number that represents the time when an action started
execution.
@ -927,13 +972,14 @@ status_query:
status_reason:
type: string
in: body
description: |
The string representation of the reason why the object has transited to
its current status.
target:
type: string
in: action
in: body
descrption: |
The UUID of the targeted object (which is usually a cluster).
@ -947,7 +993,8 @@ target_query:
timeout:
type: integer
in: cluster
in: body
optional: True
description: |
The default timeout value (in seconds) of cluster operations.
@ -993,43 +1040,43 @@ versions:
version_id:
type: string
in: version
in: body
description: |
The string representation of an API version number, e.g. ``1.0``.
version_links:
type: list
in: version
in: body
description: |
A list of relative URLs to different version objects.
version_max_version:
type: string
in: version
in: body
description: |
The string representation of the maximum microversion supported.
version_media_types:
type: list
in: version
in: body
description: |
A list of content-type based media type request supported.
version_min_version:
type: string
in: version
in: body
description: |
The string representation of the minimum microversion supported.
version_status:
type: string
in: version
in: body
description: |
A string indicating the supporting status of the version.
version_updated:
type: string
in: version
in: body
description: |
The date and time when the version was last updated. The date and time
stamp format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
@ -1037,19 +1084,19 @@ version_updated:
version_url:
type: string
in: URL
in: path
optional: False
description: |
A string indicating the major version of Clustering API.
webhook_id_url:
type: UUID
in: URL
in: path
description: |
The UUID of a webhook object.
webhook_params:
type: dict
type: object
in: query
optional: True
description: |

3
api-ref/source/profiles.inc
View File

@ -82,7 +82,6 @@ Request Parameters
- profile: profile
- name: name
- metadata: metadata
optional: true
- spec: profile_spec
Request Example
@ -191,9 +190,7 @@ Request Parameters
- profile_id: profile_id_url
- profile: profile
- metadata: metadata
optional: true
- name: name
optional: true
Request Example
---------------

32
api-ref/source/receivers.inc
View File

@ -35,9 +35,7 @@ Request Parameters
- name: name_query
- type: receiver_type_query
- user: user_query
- cluster_id: cluster_id
in: query
optional: true
- cluster_id: cluster_identity_query
- action: receiver_action_query
Response Parameters
@ -51,20 +49,14 @@ Response Parameters
- channel: receiver_channel
- cluster_id: cluster_id
- created_at: created_at
in: receiver
- domain: domain
in: receiver
- id: receiver_id
- name: name
in: receiver
- params: receiver_params
- project: project
in: receiver
- type: receiver_type
- updated_at: updated_at
in: receiver
- user: user
in: receiver
Response Example
----------------
@ -97,17 +89,11 @@ Request Parameters
- OpenStack-API-Version: microversion
- receiver: receiver
- name: name
in: receiver
optional: true
- cluster_id: cluster_id_url
in: receiver
- cluster_id: cluster_identity
- type: receiver_type
- action: receiver_action
- actor: receiver_actor
optional: true
- params: receiver_params
optional: true
Request Example
---------------
@ -127,21 +113,14 @@ Response Parameters
- channel: receiver_channel
- cluster_id: cluster_id
- created_at: created_at
in: receiver
- domain: domain
in: receiver
- id: receiver_id
- name: name
in: receiver
- params: receiver_params
- project: project
in: receiver
- type: receiver_type
- updated_at: updated_at
in: receiver
- user: user
in: receiver
Response Example
----------------
@ -186,21 +165,14 @@ Response Parameters
- channel: receiver_channel
- cluster_id: cluster_id
- created_at: created_at
in: receiver
- domain: domain
in: receiver
- id: receiver_id
- name: name
in: receiver
- params: receiver_params
- project: project
in: receiver
- type: receiver_type
- updated_at: updated_at
in: receiver
- user: user
in: receiver
Response Example
----------------

1
test-requirements.txt
View File

@ -20,6 +20,7 @@ testscenarios>=0.4 # Apache-2.0/BSD
testtools>=1.4.0 # MIT
# Documentation
os-api-ref>=0.1.0 # Apache-2.0
oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0
sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2 # BSD
reno>=1.6.2 # Apache2