From 4170566618426960b0ac850ba8e41a5f73b95c5e Mon Sep 17 00:00:00 2001 From: Jay Dobies Date: Wed, 4 May 2016 15:23:15 -0400 Subject: [PATCH] Migrate API documentations into the Heat tree For more information, see: http://lists.openstack.org/pipermail/openstack-dev/2016-May/093765.html This is the initial port from api-site. The includes in source/v1/index.rst are alphabetized, but we may want to revisit that and reorder them according to importance. Change-Id: I6f578107e17d3a97e667f645a05493da12ae2048 Implements: blueprint api-doc-migration --- api-ref/ext/__init__.py | 0 api-ref/ext/rest_parameters.py | 377 ++++ api-ref/source/conf.py | 224 +++ api-ref/source/index.rst | 24 + api-ref/source/v1/build-info.inc | 39 + api-ref/source/v1/general-info.inc | 13 + api-ref/source/v1/heat-versions.inc | 38 + api-ref/source/v1/index.rst | 32 + api-ref/source/v1/parameters.yaml | 1580 +++++++++++++++++ .../v1/samples/build-info-response.json | 8 + .../v1/samples/config-create-request.json | 28 + .../v1/samples/config-create-response.json | 32 + .../v1/samples/config-show-response.json | 32 + .../v1/samples/deployment-create-request.json | 8 + .../samples/deployment-create-response.json | 14 + .../samples/deployment-metadata-response.json | 130 ++ .../v1/samples/deployment-show-response.json | 14 + .../v1/samples/deployment-update-request.json | 10 + .../samples/deployment-update-response.json | 19 + .../v1/samples/deployments-list-response.json | 21 + .../v1/samples/event-show-response.json | 33 + .../v1/samples/events-list-response.json | 50 + .../v1/samples/heat-versions-response.json | 14 + .../samples/resource-metadata-response.json | 6 + .../v1/samples/resource-schema-response.json | 30 + .../v1/samples/resource-show-response.json | 27 + .../resource-type-template-response.json | 50 + .../samples/resource-types-list-response.json | 61 + .../v1/samples/resources-list-response.json | 25 + .../v1/samples/services-list-response.json | 30 + .../v1/samples/stack-abandon-response.json | 69 + .../stack-action-cancel-update-request.json | 3 + .../samples/stack-action-check-request.json | 3 + .../samples/stack-action-resume-request.json | 3 + .../samples/stack-action-suspend-request.json | 3 + .../v1/samples/stack-adopt-request.json | 33 + .../v1/samples/stack-create-request.json | 32 + .../v1/samples/stack-create-response.json | 11 + .../v1/samples/stack-find-response.json | 27 + .../samples/stack-outputs-list-response.json | 10 + .../v1/samples/stack-preview-response.json | 168 ++ .../samples/stack-show-output-response.json | 8 + .../v1/samples/stack-show-response.json | 32 + .../samples/stack-show-snapshot-response.json | 47 + .../v1/samples/stack-snapshot-request.json | 3 + .../v1/samples/stack-snapshot-response.json | 8 + .../stack-snapshots-list-response.json | 12 + .../stack-update-preview-response.json | 67 + .../v1/samples/stack-update-request.json | 28 + .../v1/samples/stacks-list-response.json | 20 + .../v1/samples/template-show-response.json | 28 + .../v1/samples/template-validate-request.json | 3 + .../samples/template-validate-response.json | 41 + .../samples/template-versions-response.json | 32 + api-ref/source/v1/service-status.inc | 67 + api-ref/source/v1/software-config.inc | 416 +++++ api-ref/source/v1/stack-actions.inc | 173 ++ api-ref/source/v1/stack-events.inc | 155 ++ api-ref/source/v1/stack-resources.inc | 191 ++ api-ref/source/v1/stack-templates.inc | 300 ++++ api-ref/source/v1/stacks.inc | 818 +++++++++ tox.ini | 18 + 62 files changed, 5798 insertions(+) create mode 100644 api-ref/ext/__init__.py create mode 100644 api-ref/ext/rest_parameters.py create mode 100644 api-ref/source/conf.py create mode 100644 api-ref/source/index.rst create mode 100644 api-ref/source/v1/build-info.inc create mode 100644 api-ref/source/v1/general-info.inc create mode 100644 api-ref/source/v1/heat-versions.inc create mode 100644 api-ref/source/v1/index.rst create mode 100644 api-ref/source/v1/parameters.yaml create mode 100644 api-ref/source/v1/samples/build-info-response.json create mode 100644 api-ref/source/v1/samples/config-create-request.json create mode 100644 api-ref/source/v1/samples/config-create-response.json create mode 100644 api-ref/source/v1/samples/config-show-response.json create mode 100644 api-ref/source/v1/samples/deployment-create-request.json create mode 100644 api-ref/source/v1/samples/deployment-create-response.json create mode 100644 api-ref/source/v1/samples/deployment-metadata-response.json create mode 100644 api-ref/source/v1/samples/deployment-show-response.json create mode 100644 api-ref/source/v1/samples/deployment-update-request.json create mode 100644 api-ref/source/v1/samples/deployment-update-response.json create mode 100644 api-ref/source/v1/samples/deployments-list-response.json create mode 100644 api-ref/source/v1/samples/event-show-response.json create mode 100644 api-ref/source/v1/samples/events-list-response.json create mode 100644 api-ref/source/v1/samples/heat-versions-response.json create mode 100644 api-ref/source/v1/samples/resource-metadata-response.json create mode 100644 api-ref/source/v1/samples/resource-schema-response.json create mode 100644 api-ref/source/v1/samples/resource-show-response.json create mode 100644 api-ref/source/v1/samples/resource-type-template-response.json create mode 100644 api-ref/source/v1/samples/resource-types-list-response.json create mode 100644 api-ref/source/v1/samples/resources-list-response.json create mode 100644 api-ref/source/v1/samples/services-list-response.json create mode 100644 api-ref/source/v1/samples/stack-abandon-response.json create mode 100644 api-ref/source/v1/samples/stack-action-cancel-update-request.json create mode 100644 api-ref/source/v1/samples/stack-action-check-request.json create mode 100644 api-ref/source/v1/samples/stack-action-resume-request.json create mode 100644 api-ref/source/v1/samples/stack-action-suspend-request.json create mode 100644 api-ref/source/v1/samples/stack-adopt-request.json create mode 100644 api-ref/source/v1/samples/stack-create-request.json create mode 100644 api-ref/source/v1/samples/stack-create-response.json create mode 100644 api-ref/source/v1/samples/stack-find-response.json create mode 100644 api-ref/source/v1/samples/stack-outputs-list-response.json create mode 100644 api-ref/source/v1/samples/stack-preview-response.json create mode 100644 api-ref/source/v1/samples/stack-show-output-response.json create mode 100644 api-ref/source/v1/samples/stack-show-response.json create mode 100644 api-ref/source/v1/samples/stack-show-snapshot-response.json create mode 100644 api-ref/source/v1/samples/stack-snapshot-request.json create mode 100644 api-ref/source/v1/samples/stack-snapshot-response.json create mode 100644 api-ref/source/v1/samples/stack-snapshots-list-response.json create mode 100644 api-ref/source/v1/samples/stack-update-preview-response.json create mode 100644 api-ref/source/v1/samples/stack-update-request.json create mode 100644 api-ref/source/v1/samples/stacks-list-response.json create mode 100644 api-ref/source/v1/samples/template-show-response.json create mode 100644 api-ref/source/v1/samples/template-validate-request.json create mode 100644 api-ref/source/v1/samples/template-validate-response.json create mode 100644 api-ref/source/v1/samples/template-versions-response.json create mode 100644 api-ref/source/v1/service-status.inc create mode 100644 api-ref/source/v1/software-config.inc create mode 100644 api-ref/source/v1/stack-actions.inc create mode 100644 api-ref/source/v1/stack-events.inc create mode 100644 api-ref/source/v1/stack-resources.inc create mode 100644 api-ref/source/v1/stack-templates.inc create mode 100644 api-ref/source/v1/stacks.inc diff --git a/api-ref/ext/__init__.py b/api-ref/ext/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/api-ref/ext/rest_parameters.py b/api-ref/ext/rest_parameters.py new file mode 100644 index 0000000000..88e7513434 --- /dev/null +++ b/api-ref/ext/rest_parameters.py @@ -0,0 +1,377 @@ +# 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 rest_expand_all(nodes.Part, nodes.Element): + pass + + +class RestExpandAllDirective(Directive): + has_content = True + + def run(self): + return [rest_expand_all()] + + +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) + try: + with open(fpath, 'r') as stream: + lookup = yaml.load(stream) + except IOError: + self.env.warn( + self.env.docname, + "Parameters file %s not found" % fpath) + return + 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: + for name, ref in paramlist.items(): + if ref in lookup: + new_content.append((name, lookup[ref])) + else: + # TODO(sdague): this provides a kind of confusing + # error message because env.warn isn't meant to be + # used this way, however it does provide a way to + # track down where the parameters list is that is + # wrong. So it's good enough for now. + self.env.warn( + "%s:%s " % ( + self.state_machine.node.source, + self.state_machine.node.line), + ("No field definition for ``%s`` found in ``%s``. " + " Skipping." % (ref, fpath))) + + # 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_file = fpath + self.yaml_from_file(self.yaml_file) + + 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 + + # 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(self, value): + entry = nodes.entry() + result = ViewList(value.split('\n')) + self.state.nested_parse(result, 0, entry) + return entry + + def show_no_yaml_error(self): + trow = nodes.row(classes=["no_yaml"]) + trow += self.add_col("No yaml found %s" % self.yaml_file) + trow += self.add_col("") + trow += self.add_col("") + trow += self.add_col("") + return trow + + def collect_rows(self): + 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('required', False) is False: + name += " (Optional)" + trow += self.add_col(name) + trow += self.add_col(values.get('in')) + trow += self.add_col(values.get('type')) + trow += self.add_col(desc) + rows.append(trow) + except AttributeError as exc: + if 'key' in locals(): + self.app.warn("Failure on key: %s, values: %s. %s" % + (key, values, exc)) + else: + rows.append(self.show_no_yaml_error()) + 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 = """ +
+
+ + + %(method)s +
+
%(url)s
+
%(desc)s
+
+ +
+
""" + + self.body.append(tmpl % node) + raise nodes.SkipNode + + +def rest_expand_all_html(self, node): + tmpl = """ +
+
+
+ +
+
""" + + self.body.append(tmpl % node) + raise nodes.SkipNode + + +def resolve_rest_references(app, doctree): + 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): + app.add_node(rest_method, + html=(rest_method_html, None)) + app.add_node(rest_expand_all, + html=(rest_expand_all_html, None)) + app.add_directive('rest_parameters', RestParametersDirective) + app.add_directive('rest_method', RestMethodDirective) + app.add_directive('rest_expand_all', RestExpandAllDirective) + 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'} diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 0000000000..0a2eb9f878 --- /dev/null +++ b/api-ref/source/conf.py @@ -0,0 +1,224 @@ +# -*- coding: utf-8 -*- +# +# 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. +# +# heat documentation build config file, copied from: +# nova documentation build configuration file, created by +# sphinx-quickstart on Sat May 1 15:17:47 2010. +# +# This file is execfile()d with the current directory set to +# its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +import subprocess +import sys +import warnings + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) + +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. + +extensions = [ + 'ext.rest_parameters', + 'oslosphinx', +] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Orchestration API Reference' +copyright = u'2010-present, OpenStack Foundation' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +from heat.version import version_info +# The full version, including alpha/beta/rc tags. +release = version_info.release_string() +# The short X.Y version. +version = version_info.version_string() + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# The reST default role (used for this markup: `text`) to use +# for all documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = False + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for man page output ---------------------------------------------- + +# Grouping the document tree for man pages. +# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' + + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# html_last_updated_fmt = '%b %d, %Y' +git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", + "-n1"] +try: + html_last_updated_fmt = subprocess.Popen( + git_cmd, stdout=subprocess.PIPE).communicate()[0] +except Exception: + warnings.warn('Cannot get last updated time from git repository. ' + 'Not setting "html_last_updated_fmt".') + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_use_modindex = True + +# If false, no index is generated. +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'heatdoc' + + +# -- Options for LaTeX output ------------------------------------------------- + +# The paper size ('letter' or 'a4'). +# latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +# latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', 'Heat.tex', u'OpenStack Orchestration API Documentation', + u'OpenStack Foundation', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +# latex_preamble = '' + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_use_modindex = True + diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 0000000000..e537344363 --- /dev/null +++ b/api-ref/source/index.rst @@ -0,0 +1,24 @@ +.. + Copyright 2010 OpenStack Foundation + All Rights Reserved. + + 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. + +========================== +Orchestration Service APIs +========================== + +.. toctree:: + :maxdepth: 1 + + v1/index diff --git a/api-ref/source/v1/build-info.inc b/api-ref/source/v1/build-info.inc new file mode 100644 index 0000000000..3236228b0a --- /dev/null +++ b/api-ref/source/v1/build-info.inc @@ -0,0 +1,39 @@ +.. -*- rst -*- + +========== +Build info +========== + + + + +Show build information +====================== + +.. rest_method:: GET /v1/{tenant_id}/build_info + +Shows build information for an Orchestration deployment. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + + + + +Response Example +---------------- + +.. literalinclude:: samples/build-info-response.json + :language: javascript + + + diff --git a/api-ref/source/v1/general-info.inc b/api-ref/source/v1/general-info.inc new file mode 100644 index 0000000000..6efdb58b95 --- /dev/null +++ b/api-ref/source/v1/general-info.inc @@ -0,0 +1,13 @@ +.. -*- rst -*- + +======================= +General API information +======================= + +Authenticated calls that target a known URI but that use an HTTP +method that the implementation does not support return a ``405 +Method Not Allowed`` error code. In addition, the HTTP ``OPTIONS`` +method is supported for each known URI. In both cases, the +``Allow`` response header indicates the HTTP methods that are +supported for the resource. + diff --git a/api-ref/source/v1/heat-versions.inc b/api-ref/source/v1/heat-versions.inc new file mode 100644 index 0000000000..bef1b4568b --- /dev/null +++ b/api-ref/source/v1/heat-versions.inc @@ -0,0 +1,38 @@ +.. -*- rst -*- + +============ +API versions +============ + + + + +List versions +============= + +.. rest_method:: GET / + +Lists all Orchestration API versions. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + + + + +Response Example +---------------- + +.. literalinclude:: samples/heat-versions-response.json + :language: javascript + + + diff --git a/api-ref/source/v1/index.rst b/api-ref/source/v1/index.rst new file mode 100644 index 0000000000..9f609c2556 --- /dev/null +++ b/api-ref/source/v1/index.rst @@ -0,0 +1,32 @@ +.. + Copyright 2010 OpenStack Foundation + All Rights Reserved. + + 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. + +:tocdepth: 2 + +============================ +Orchestration Service API v1 +============================ + +.. include:: build-info.inc +.. include:: general-info.inc +.. include:: heat-versions.inc +.. include:: service-status.inc +.. include:: software-config.inc +.. include:: stack-actions.inc +.. include:: stack-events.inc +.. include:: stack-resources.inc +.. include:: stack-templates.inc +.. include:: stacks.inc diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml new file mode 100644 index 0000000000..9f8b42c1d9 --- /dev/null +++ b/api-ref/source/v1/parameters.yaml @@ -0,0 +1,1580 @@ +# variables in header + +# variables in path +config_id: + description: | + The UUID of the configuration. + in: path + required: false + type: string +deployment_id: + description: | + The UUID of the deployment. + in: path + required: false + type: string +event_id: + description: | + The UUID of the event that is related to the + resource in the stack. + in: path + required: false + type: string +output_key_1: + description: | + The key of a stack output. + in: path + required: false + type: string +resource_name: + description: | + The name of a resource in the stack. + in: path + required: false + type: string +server_id_2: + description: | + The UUID of the server for which to fetch + configuration metadata. + in: path + required: false + type: string +snapshot_id: + description: | + The UUID of the snapshot. + in: path + required: false + type: string +stack_id: + description: | + The UUID of the stack. + in: path + required: false + type: string +stack_name: + description: | + The name of a stack. + in: path + required: false + type: string +tenant_id: + description: | + The UUID of the tenant. A tenant is also known as + an account or project. + in: path + required: false + type: string +type_name: + description: | + The name of a resource type. + in: path + required: false + type: string + +# variables in query +action_3: + description: | + Filters the stack list by an action. Use this + filter multiple times to filter by multiple actions. + in: query + required: false + type: string +global_tenant: + description: | + Set to ``true`` to include stacks from all + tenants in the stack list. Specify policy requirements in the + Orchestration ``policy.json`` file. Default is ``false``. + in: query + required: false + type: boolean +id_4: + description: | + Filters the stack list by a stack ID. Use this + filter multiple times to filter by multiple IDs. + in: query + required: false + type: string +limit: + description: | + Requests a page size of items. Returns a number + of items up to a limit value. Use the ``limit`` parameter to make + an initial limited request and use the ID of the last-seen item + from the response as the ``marker`` parameter value in a + subsequent limited request. + in: query + required: false + type: integer +marker: + description: | + The ID of the last-seen item. Use the ``limit`` + parameter to make an initial limited request and use the ID of the + last-seen item from the response as the ``marker`` parameter value + in a subsequent limited request. + in: query + required: false + type: string +name: + description: | + Filters the response by a resource type name. You + can set this value to a regular expression. Use this filter + multiple times to filter by multiple names. + in: query + required: false + type: string +name_4: + description: | + Filters the stack list by a name. Use this filter + multiple times to filter by multiple names. + in: query + required: false + type: string +nested_depth: + description: | + Includes resources from nested stacks up to the + ``nested_depth`` levels of recursion. + in: query + required: false + type: integer +not_tags: + description: | + Lists stacks that do not contain one or more + simple string tags. To specify multiple tags, separate the tags + with commas. For example, ``tag1,tag2``. The boolean AND + expression is used to combine multiple tags. + in: query + required: false + type: string +not_tags_any: + description: | + Lists stacks that do not contain one or more + simple string tags. To specify multiple tags, separate the tags + with commas. For example, ``tag1,tag2``. The boolean OR expression + is used to combine multiple tags. + in: query + required: false + type: string +owner_id: + description: | + Filters the stack list by an owner ID, which is + the ID of the parent stack of listed stack. Use this filter + multiple times to filter by multiple owner IDs. + in: query + required: false + type: string +resource_action: + description: | + Filters the event list by a resource action. You + can use this filter multiple times to filter by multiple resource + actions. Valid resource actions are ``ADOPT``, ``CHECK``, + ``CREATE``, ``DELETE``, ``INIT``, ``RESTORE``, ``RESUME``, + ``ROLLBACK``, ``SNAPSHOT``, ``SUSPEND``, and ``UPDATE``. + in: query + required: false + type: string +resource_name_2: + description: | + Filters the event list by a resource name. You + can use this filter multiple times to filter by multiple resource + names. + in: query + required: false + type: string +resource_status: + description: | + Filters the event list by a resource status. You + can use this filter multiple times to filter by multiple resource + statuses. Valid resource statuses are ``COMPLETE``, ``FAILED``, + and ``IN_PROGRESS``. + in: query + required: false + type: string +resource_type: + description: | + Filters the event list by a resource type. You + can use this filter multiple times to filter by multiple resource + types. Valid resource types include ``OS::Cinder::Volume``, + ``OS::Nova::Server``, ``OS::Neutron::Port``, and so on. + in: query + required: false + type: string +show_deleted: + description: | + Set to ``true`` to include deleted stacks in the + list. Default is ``false``, which excludes deleted stacks from the + list. + in: query + required: false + type: boolean +show_nested: + description: | + Set to ``true`` to include nested stacks in the + list. Default is ``false``, which excludes nested stacks from the + list. + in: query + required: false + type: boolean +sort_dir: + description: | + The sort direction of the list. A valid value is + ``asc`` (ascending) or ``desc`` (descending). + in: query + required: false + type: string +sort_keys: + description: | + Sorts the list by the ``resource_type`` or + ``created_at`` key. + in: query + required: false + type: string +sort_keys_1: + description: | + Sorts the stack list by ``stack_name``, + ``stack_status``, ``creation_time``, or ``updated_time`` key. + in: query + required: false + type: string +status_5: + description: | + Filters the stack list by a status. Use this + filter multiple times to filter by multiple statuses. + in: query + required: false + type: string +support_status_1: + description: | + Filters the response by resource types by a + support status. Valid support status values are ``UNKNOWN``, + ``SUPPORTED``, ``DEPRECATED``, ``UNSUPPORTED``, and ``HIDDEN``. + Use this filter multiple times to filter by multiple support + statuses. + in: query + required: false + type: string +tags_1: + description: | + Lists stacks that contain one or more simple + string tags. To specify multiple tags, separate the tags with + commas. For example, ``tag1,tag2``. The boolean AND expression is + used to combine multiple tags. + in: query + required: false + type: string +tags_any: + description: | + Lists stacks that contain one or more simple + string tags. To specify multiple tags, separate the tags with + commas. For example, ``tag1,tag2``. The boolean OR expression is + used to combine multiple tags. + in: query + required: false + type: string +tenant: + description: | + Filters the stack list by a tenant. Use this + filter multiple times to filter by multiple tenants. + in: query + required: false + type: string +username: + description: | + Filters the stack list by a user name. Use this + filter multiple times to filter by multiple user names. + in: query + required: false + type: string +version: + description: | + Filters the response by resource types by heat + version. For example, ``2016.1`` or ``5.0.0``. Use this filter + multiple times to filter by multiple versions. + in: query + required: false + type: string +with_count: + description: | + Set to ``true`` to include a count key in the + response. The count key value is the number of stacks that match + the query criteria. Default is ``false``. + in: query + required: false + type: boolean +with_detail: + description: | + Enables detailed resource information for each + resource in list of resources. + in: query + required: false + type: boolean + +# variables in body +Description: + description: | + The description specified in the template. + in: body + required: true + type: string +HeatTemplateFormatVersion: + description: | + The version of the heat template. + in: body + required: true + type: string +Outputs: + description: | + Key and value pairs that contain output data. + in: body + required: true + type: object +ParameterGroups: + description: | + A list of parameter groups. Each group contains a + list of parameter names. + in: body + required: false + type: array +Parameters: + description: | + Key and value pairs that contain template + parameters. + in: body + required: true + type: object +Parameters_1: + description: | + An object that defines all input parameters that + are defined in the template. Indexed by parameter name. + in: body + required: true + type: object +Resources: + description: | + Contain ``KeyPair`` for resource template. + in: body + required: true + type: object +action: + description: | + The current stack action that triggers this + deployment resource. + in: body + required: true + type: string +action_1: + description: | + The deployment action. + in: body + required: true + type: string +action_2: + description: | + Current stack action in which this deployment + resource is being triggered. + in: body + required: true + type: string +adopt_stack_data: + description: | + Existing resources data to adopt a stack. Data + returned by abandon stack could be provided as + ``adopt_stack_data``. + in: body + required: true + type: object +attributes: + description: | + Key and value pairs that contain resource + attributes. + in: body + required: true + type: object +binary: + description: | + The name of the binary form of the heat engine. + in: body + required: true + type: string +cancel_update: + description: | + Specify the ``cancel_update`` action in the + request body. + in: body + required: true + type: string +capabilities: + description: | + List of stack capabilities for stack. + in: body + required: true + type: array +capabilities_1: + description: | + A list of stack capabilities. + in: body + required: true + type: array +check: + description: | + Specify the ``check`` action in the request body. + in: body + required: true + type: string +config: + description: | + Configuration script or manifest that defines + which configuration is performed. + in: body + required: false + type: string +config_1: + description: | + The configuration code. + in: body + required: true + type: string +config_id_1: + description: | + The UUID of the software configuration resource + that runs when applying to the server. + in: body + required: true + type: string +config_id_2: + description: | + The UUID of the configuration. + in: body + required: true + type: string +config_id_3: + description: | + The UUID of the software configuration resource + to run when applying to the server. This UUID might not be the + same configuration UUID with which the deployment was created + because ephemeral configurations are created throughout the life + cycle of the deployment. + in: body + required: true + type: string +created_at: + description: | + The date and time when the resource was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + in: body + required: true + type: string +creation_time: + description: | + The date and time when the stack resource was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + in: body + required: true + type: string +creation_time_1: + description: | + The date and time when the software was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + in: body + required: true + type: string +creation_time_2: + description: | + The date and time when the resource was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + in: body + required: true + type: string +creation_time_3: + description: | + The date and time when the snapshot was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + in: body + required: true + type: string +creation_time_4: + description: | + The date and time when the software was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2016-03-30T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + in: body + required: true + type: string +creation_time_5: + description: | + The date and time when the stack was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + in: body + required: true + type: string +data: + description: | + The snapshot data. + in: body + required: true + type: object +deleted_at: + description: | + The date and time when the resource was deleted. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. In the previous example, the offset value is ``-05:00``. + in: body + required: true + type: string +description: + description: | + The description of the stack resource. + in: body + required: true + type: string +description_1: + description: | + The description of the resource attribute. + in: body + required: true + type: string +description_2: + description: | + The description of a stack output. + in: body + required: true + type: string +description_3: + description: | + The description of the active stack. + in: body + required: true + type: string +description_4: + description: | + A description of the stack. + in: body + required: true + type: string +description_5: + description: | + The description of the stack. + in: body + required: true + type: string +description_6: + description: | + The description of the stack template. + in: body + required: true + type: string +disable_rollback: + description: | + Enables or disables deletion of all stack + resources when stack creation fails. Set to ``true`` to keep all + resources when stack creation fails. Set to ``false`` to delete + all resources when stack creation fails. Default is ``true``. + in: body + required: false + type: boolean +disable_rollback_1: + description: | + Enables or disables deletion of all previously- + created stack resources when stack creation fails. Set to ``true`` + to keep all previously-created stack resources when stack creation + fails. Set to ``false`` to delete all previously-created stack + resources when stack creation fails. Default is ``true``. + in: body + required: false + type: boolean +disable_rollback_2: + description: | + Enables or disables stack rollback when stack + creation fails. Set to ``true`` to rollback the stack when stack + creation fails. Set to ``false`` to disable stack rollback when + stack creation fails. Default is ``true``. + in: body + required: true + type: boolean +environment: + description: | + A JSON environment for the stack. + in: body + required: false + type: object +files: + description: | + Supplies the contents of files referenced in the template or the + environment. Stack templates and resource templates can explicitly + reference files by using the ``get_file`` intrinsic function. In + addition, the ``environment`` parameter can contain implicit + references to files. + + The value is a JSON object, where each key is a relative or + absolute URI which serves as the name of a file, and the associated + value provides the contents of the file. The following code shows + the general structure of this parameter. + + .. code-block:: json + + { ... + "files": { + "fileA.yaml": "Contents of the file", + "file:///usr/fileB.template": "Contents of the file", + "http://example.com/fileC.template": "Contents of the file" + } + ... + } + + Additionally, some template authors encode their user data in a + local file. The Orchestration client examines the template for the + ``get_file`` intrinsic function and adds an entry to the ``files`` + map with the path to the file as the name and the file contents as + the value. So, a simple example looks like this: + + .. code-block:: json + + { +    "files": { +       "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" +    }, + ..., +    "stack_name": "teststack", +    "template": { + ..., +       "resources": { +          "my_server": { +             "type": "OS::Nova::Server", +             "properties": { + ..., +                "user_data": { +                   "get_file": "myfile" +                } +             } +          } +       } +    }, +    "timeout_mins": 60 + } + + Do not use this parameter to provide the content of the template + located at the ``template_url`` address. Instead, use the + ``template`` parameter to supply the template content as part of + the request. + in: body + required: false + type: object +group: + description: | + Namespace that groups this software configuration + by when it is delivered to a server. This setting might simply + define which configuration tool performs the configuration. + in: body + required: false + type: string +group_1: + description: | + The name of the group in which the software is + configured. + in: body + required: true + type: string +heat_template_version: + description: | + The version of the heat template. + in: body + required: true + type: string +hostname: + description: | + The name of the host for the service. + in: body + required: true + type: string +id: + description: | + The UUID of the heat engine. + in: body + required: true + type: string +id_1: + description: | + The UUID of the software deployment. + in: body + required: true + type: string +id_2: + description: | + The UUID of the system-assigned stack. + in: body + required: true + type: string +id_3: + description: | + The UUID of the snapshot. + in: body + required: true + type: string +id_5: + description: | + The UUID of the stack. + in: body + required: true + type: string +input_values: + description: | + A list of input data. + in: body + required: true + type: array +inputs: + description: | + Schema that represents the inputs that this + software configuration expects. + in: body + required: false + type: array +inputs_1: + description: | + A list of inputs to configure the software. + in: body + required: true + type: array +links: + description: | + A list of URLs for the stack. Each URL is a JSON + object with an ``href`` key indicating the URL and a ``rel`` key + indicating its relationship to the stack in question. There may be + multiple links returned. The ``self`` relationship identifies the + URL of the stack itself. + in: body + required: true + type: array +links_1: + description: | + A list of stack links. + in: body + required: true + type: array +logical_resource_id: + description: | + The ID of the logical stack resource. + in: body + required: true + type: string +name_1: + description: | + The name of the configuration to create. + in: body + required: false + type: string +name_2: + description: | + The name of the software configuration. + in: body + required: true + type: string +name_3: + description: | + The name of the snapshot. + in: body + required: true + type: string +notification_topics: + description: | + List of notification topics for stack. + in: body + required: true + type: array +notification_topics_1: + description: | + A list of stack notifications. + in: body + required: true + type: array +options: + description: | + Map that contains options that are specific to + the configuration management tool that this resource uses. + in: body + required: false + type: string +options_1: + description: | + The options, if any, to include in the code. For + example any dependent flags. + in: body + required: true + type: string +output_error: + description: | + The error in a stack output. + in: body + required: true + type: string +output_key: + description: | + The name of a stack output. + in: body + required: true + type: string +output_value: + description: | + The value of a stack output. + in: body + required: true + type: string +output_values: + description: | + A list of output data. + in: body + required: true + type: array +output_values_1: + description: | + Map of output values for the deployment, as + signaled from the server. + in: body + required: false + type: object +outputs: + description: | + Schema that represents the outputs that this + software configuration produces. + in: body + required: false + type: array +outputs_1: + description: | + A list of software configuration output data. + in: body + required: true + type: array +outputs_2: + description: | + A list of stack outputs. + in: body + required: true + type: array +outputs_3: + description: | + Key and value pairs that contain output data. + in: body + required: true + type: object +parameters: + description: | + Supplies arguments for parameters defined in the stack template. + + The value is a JSON object, where each key is the name of a + parameter defined in the template and the associated value is the + argument to use for that parameter when instantiating the template. + The following code shows the general structure of this parameter. + In the example, ``a`` and ``b`` would be the names of two + parameters defined in the template. + + .. code-block:: json + + { ... + "parameters": { + "a": "Value", + "b": "3" + } + ... + } + + While the service accepts JSON numbers for parameters with the type + ``number`` and JSON objects for parameters with the type ``json``, + all parameter values are converted to their string representation + for storage in the created Stack. Clients are encouraged to send + all parameter values using their string representation for + consistency between requests and responses from the Orchestration + service. + + A value must be provided for each template parameter which does not + specify a default value. However, this parameter is not allowed to + contain JSON properties with names that do not match a parameter + defined in the template. + + The ``files`` parameter maps logical file names to file contents. + Both the ``get_file`` intrinsic function and provider template + functionality use this mapping. When you want to use a provider + template, for example, the Orchestration service adds an entry to + the ``files`` map by using: + + - The URL of the provider template as the name. + + - The contents of that file as the value. + + Additionally, some template authors encode their user data in a + local file. The Orchestration client examines the template for the + ``get_file`` intrinsic function and adds an entry to the ``files`` + map with the path to the file as the name and the file contents as + the value. So, a simple example looks like this: + + .. code-block:: json + + { + "files": { + "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" + }, + ..., + "stack_name": "teststack", + "template": { + ..., + "resources": { + "my_server": { + "type": "OS::Nova::Server", + "properties": { + ..., + "user_data": { + "get_file": "myfile" + } + } + } + } + }, + "timeout_mins": 60 + } + in: body + required: false + type: object +parameters_1: + description: | + Key and value pairs that contain stack + parameters. + in: body + required: true + type: object +parameters_2: + description: | + Key and value pairs that contain template + parameters. + in: body + required: true + type: object +parameters_3: + description: "Supplies updated arguments for parameters that are defined in the\n\ + stack template.\n\nThe value is a JSON object, where each key is the name of a\n\ + parameter defined in the template and the associated value is the\nargument to\ + \ use for that parameter when instantiating the template.\nThe following code\ + \ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\ + \ are the names of two parameters\ndefined in the template.\n\n.. code-block::\ + \ json\n\n { ...\n \"parameters\": {\n \ + \ \"a\": \"Value\",\n \"b\": \"3\"\n \ + \ }\n ... }\n \n\ + \nWhile the service accepts JSON numbers for parameters with the type\n``number``\ + \ and JSON objects for parameters with the type ``json``,\nall parameter values\ + \ are converted to their string representation\nfor storage in the created Stack.\ + \ Clients are encouraged to send\nall parameter values using their string representation\ + \ for\nconsistency between requests and responses from the Orchestration\nservice.\n\ + \nYou must specify a value for each template parameter that does not\nhave a default\ + \ value. However, this parameter cannot contain JSON\nproperties with names that\ + \ do not match a parameter that is defined\nin the template.\n" + in: body + required: false + type: object +parameters_4: + description: "This parameter supplies updated arguments for parameters defined in\n\ + the stack template.\n\nThe value is a JSON object, where each key is the name\ + \ of a\nparameter defined in the template and the associated value is the\nargument\ + \ to use for that parameter when instantiating the template.\nThe following code\ + \ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\ + \ are the names of two parameters\ndefined in the template.\n\n.. code-block::\ + \ json\n\n { ...\n \"parameters\": {\n \ + \ \"a\": \"Value\",\n \"b\": \"3\"\n \ + \ }\n ... }\n \n\nWhile\ + \ the service accepts JSON numbers for parameters with the type\n``number`` and\ + \ JSON objects for parameters with the type ``json``,\nall parameter values are\ + \ converted to their string representation\nfor storage in the created Stack.\ + \ Clients are encouraged to send\nall parameter values using their string representation\ + \ for\nconsistency between requests and responses from the Orchestration\nservice.\n\ + \nYou must specify a value for each template parameter that does not\nhave a default\ + \ value. However, this parameter cannot contain JSON\nproperties with names that\ + \ do not match a parameter that is defined\nin the template.\n" + in: body + required: false + type: object +parent: + description: | + The stack ID of the parent stack, if this is a + nested stack. + in: body + required: true + type: string +parent_1: + description: | + The parent of the stack. + in: body + required: true + type: string +physical_resource_id: + description: | + The ID of the stack physical resource. + in: body + required: true + type: string +project_id: + description: | + The UUID of the project. + in: body + required: true + type: string +properties: + description: | + The properties of the resource. Includes + description, type, and so on. + in: body + required: true + type: object +report_interval: + description: | + The polling interval, in seconds. The API reports + events at this interval until heat engine creation completes. + in: body + required: true + type: integer +required: + description: | + If set to ``true`` the attribute is required. + in: body + required: true + type: boolean +required_by: + description: | + The list of resources that require this stack + resource. + in: body + required: true + type: array +resource: + description: | + Key and value pairs that contain stack resource + properties. + in: body + required: true + type: object +resource_name_1: + description: | + The name of the resource. + in: body + required: true + type: string +resource_status_1: + description: | + The status of the resource. + in: body + required: true + type: string +resource_status_reason: + description: | + The reason for the current stack resource state. + in: body + required: true + type: string +resource_type_1: + description: | + The type of the resource. + in: body + required: true + type: string +resources: + description: | + A list of resources and their properties. + in: body + required: true + type: array +resources_1: + description: | + List of stack resources. + in: body + required: true + type: array +resources_2: + description: | + The snapshot resources. + in: body + required: true + type: object +resources_3: + description: | + The required sources for creating the stack + template. + in: body + required: true + type: object +resume: + description: | + Specify the ``resume`` action in the request + body. + in: body + required: true + type: string +server_id: + description: | + The UUID of the compute server to which the + configuration applies. + in: body + required: true + type: string +server_id_1: + description: | + The UUID of the server. + in: body + required: true + type: string +services: + description: | + A list of heat engines. + in: body + required: true + type: array +snapshot: + description: | + Key and value pairs that contain snapshot + properties. + in: body + required: true + type: object +snapshots: + description: | + A list of snapshots and their properties. + in: body + required: true + type: array +stack: + description: | + The ``stack`` object. + in: body + required: true + type: object +stack_name_1: + description: | + A name for the new stack. The value must be + unique within a project. The name must start with an ASCII letter + and can contain ASCII letters, digits, underscores, periods, and + hyphens. Specifically, the name must match the + ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression. When you delete + or abandon a stack, its name will not become available for reuse + until the deletion completes successfully. + in: body + required: true + type: string +stack_name_2: + description: | + A name for the new stack. This value must be + unique within a project. The name must start with an ASCII letter + and can contain ASCII letters, digits, underscores, periods, and + hyphens. Specifically, the name must match the + ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression. When you delete + or abandon a stack, its name will not become available for reuse + until the deletion completes successfully. + in: body + required: true + type: string +stack_name_3: + description: | + The name of the active stack. + in: body + required: true + type: string +stack_owner: + description: | + Stack owner name. + in: body + required: true + type: string +stack_owner_1: + description: | + The owner of the stack. + in: body + required: true + type: string +stack_status: + description: | + The status of the active stack. + in: body + required: true + type: string +stack_status_1: + description: | + The status of the stack. + in: body + required: true + type: string +stack_status_reason: + description: | + The reason for the current status of the stack. + in: body + required: true + type: string +stack_user_project_id: + description: | + Authentication project ID, which can also perform + operations on this deployment. + in: body + required: false + type: string +stack_user_project_id_1: + description: | + The project UUID of the stack user. + in: body + required: true + type: string +status: + description: | + The status of the heat engine. + in: body + required: true + type: string +status_1: + description: | + Current status of the deployment. A valid value + is ``COMPLETE``, ``IN_PROGRESS``, or ``FAILED``. + in: body + required: false + type: string +status_2: + description: | + The status of the software deployment. The value + is ``INPROGRESS`` or ``COMPLETE``. + in: body + required: true + type: string +status_3: + description: | + Current status of the deployment. Value is + ``IN_PROGRESS``, ``COMPLETE``, or ``FAILED``. + in: body + required: false + type: string +status_4: + description: | + The status of the snapshot. + in: body + required: true + type: string +status_reason: + description: | + Error description for the last status change, + which is ``FAILED`` status. + in: body + required: false + type: string +status_reason_1: + description: | + The debug information for the current status. + in: body + required: true + type: string +status_reason_2: + description: | + The reason for the current snapshot status. + in: body + required: true + type: string +support_status: + description: | + Information about the current status. + in: body + required: true + type: object +suspend: + description: | + Specify the ``suspend`` action in the request + body. + in: body + required: true + type: string +tags: + description: | + One or more simple string tags to associate with + the stack. To associate multiple tags with a stack, separate the + tags with commas. For example, ``tag1,tag2``. + in: body + required: false + type: string +tags_2: + description: | + The stack tags. + in: body + required: true + type: string +template: + description: | + The stack template on which to perform the operation. + + This parameter is always provided as a ``string`` in the JSON + request body. The content of the string is a JSON- or YAML- + formatted Orchestration template. For example: + + .. code-block:: json + + "template": { + "heat_template_version": "2013-05-23", + ...} + + This parameter is required only when you omit the ``template_url`` + parameter. If you specify both parameters, this value overrides the + ``template_url`` parameter value. + in: body + required: true + type: object +template_1: + description: | + Information about the template. + in: body + required: true + type: object +template_2: + description: | + The stack template on which to perform the operation. + + This parameter is always provided as a ``string`` in the JSON + request body. The content of the string is a JSON- or YAML- + formatted Orchestration template. For example: + + .. code-block:: json + + "template": { + "heat_template_version": "2013-05-23", + ...} + + This parameter is required only when you omit the ``template_url`` + parameter. If you specify both parameters, this value overrides the + ``template_url`` parameter value. + in: body + required: false + type: object +template_description: + description: | + A description of the template that defines the + stack. + in: body + required: true + type: string +template_description_1: + description: | + The description of the stack template. + in: body + required: true + type: string +template_url: + description: | + A URI to the location containing the stack + template on which to perform the operation. See the description + of the ``template`` parameter for information about the expected + template content located at the URI. This parameter is only + required when you omit the ``template`` parameter. If you specify + both parameters, this parameter is ignored. + in: body + required: false + type: string +timeout_mins: + description: | + The timeout for stack creation in minutes. + in: body + required: false + type: integer +timeout_mins_1: + description: | + Time-lines for stack creation. + in: body + required: true + type: integer +timeout_mins_2: + description: | + The timeout, in minutes. + in: body + required: true + type: string +topic: + description: | + The topic of the heat engine. + in: body + required: true + type: string +type: + description: | + The property type. + in: body + required: true + type: string +update_allowed: + description: | + If set to ``true``, update is allowed. + in: body + required: true + type: boolean +updated_at: + description: | + The date and time when the resource was updated. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. In the previous example, the offset value is ``-05:00``. + + If the ``updated_at`` date and time stamp is not set, its value is + ``null``. + in: body + required: true + type: string +updated_time: + description: | + The date and time when the stack resource was updated. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + + If the ``updated_at`` date and time stamp is not set, its value is + ``null``. + in: body + required: true + type: string +updated_time_1: + description: | + The date and time when the stack resource was updated. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2016-03-30T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + + If the ``updated_at`` date and time stamp is not set, its value is + ``null``. + in: body + required: true + type: string +updated_time_2: + description: | + Time of last stack update in the following + format: ``YYYY-MM- DDThh:mm:ssTZD``, where ``TZD`` is the time + zone designator. + in: body + required: true + type: string +updated_time_3: + description: | + The date and time when the stack was updated. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + For example, ``2015-08-27T09:49:58-05:00``. + + The ``±hh:mm`` value, if included, is the time zone as an offset + from UTC. + + If the ``updated_at`` date and time stamp is not set, its value is + ``null``. + in: body + required: true + type: string + diff --git a/api-ref/source/v1/samples/build-info-response.json b/api-ref/source/v1/samples/build-info-response.json new file mode 100644 index 0000000000..650200f887 --- /dev/null +++ b/api-ref/source/v1/samples/build-info-response.json @@ -0,0 +1,8 @@ +{ + "api": { + "revision": "{api_build_revision}" + }, + "engine": { + "revision": "{engine_build_revision}" + } +} diff --git a/api-ref/source/v1/samples/config-create-request.json b/api-ref/source/v1/samples/config-create-request.json new file mode 100644 index 0000000000..d9f44241b8 --- /dev/null +++ b/api-ref/source/v1/samples/config-create-request.json @@ -0,0 +1,28 @@ +{ + "inputs": [ + { + "default": null, + "type": "String", + "name": "foo", + "description": null + }, + { + "default": null, + "type": "String", + "name": "bar", + "description": null + } + ], + "group": "script", + "name": "a-config-we5zpvyu7b5o", + "outputs": [ + { + "type": "String", + "name": "result", + "error_output": false, + "description": null + } + ], + "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2", + "options": null +} diff --git a/api-ref/source/v1/samples/config-create-response.json b/api-ref/source/v1/samples/config-create-response.json new file mode 100644 index 0000000000..5025435b92 --- /dev/null +++ b/api-ref/source/v1/samples/config-create-response.json @@ -0,0 +1,32 @@ +{ + "software_config": { + "creation_time": "2015-01-31T15:12:36Z", + "inputs": [ + { + "default": null, + "type": "String", + "name": "foo", + "description": null + }, + { + "default": null, + "type": "String", + "name": "bar", + "description": null + } + ], + "group": "script", + "name": "a-config-we5zpvyu7b5o", + "outputs": [ + { + "type": "String", + "name": "result", + "error_output": false, + "description": null + } + ], + "options": null, + "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2", + "id": "ddee7aca-aa32-4335-8265-d436b20db4f1" + } +} diff --git a/api-ref/source/v1/samples/config-show-response.json b/api-ref/source/v1/samples/config-show-response.json new file mode 100644 index 0000000000..e89b2b1c09 --- /dev/null +++ b/api-ref/source/v1/samples/config-show-response.json @@ -0,0 +1,32 @@ +{ + "software_config": { + "inputs": [ + { + "default": null, + "type": "String", + "name": "foo", + "description": null + }, + { + "default": null, + "type": "String", + "name": "bar", + "description": null + } + ], + "group": "script", + "name": "a-config-we5zpvyu7b5o", + "outputs": [ + { + "type": "String", + "name": "result", + "error_output": false, + "description": null + } + ], + "creation_time": "2015-01-31T15:12:36Z", + "id": "ddee7aca-aa32-4335-8265-d436b20db4f1", + "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2", + "options": null + } +} diff --git a/api-ref/source/v1/samples/deployment-create-request.json b/api-ref/source/v1/samples/deployment-create-request.json new file mode 100644 index 0000000000..92ad840690 --- /dev/null +++ b/api-ref/source/v1/samples/deployment-create-request.json @@ -0,0 +1,8 @@ +{ + "status": "IN_PROGRESS", + "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", + "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd", + "stack_user_project_id": "c024bfada67845ddb17d2b0c0be8cd79", + "action": "CREATE", + "status_reason": "Deploy data available" +} diff --git a/api-ref/source/v1/samples/deployment-create-response.json b/api-ref/source/v1/samples/deployment-create-response.json new file mode 100644 index 0000000000..736f1e15bf --- /dev/null +++ b/api-ref/source/v1/samples/deployment-create-response.json @@ -0,0 +1,14 @@ +{ + "software_deployment": { + "status": "IN_PROGRESS", + "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", + "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd", + "output_values": null, + "input_values": null, + "action": "CREATE", + "status_reason": "Deploy data available", + "id": "ef422fa5-719a-419e-a10c-72e3a367b0b8", + "creation_time": "2015-01-31T15:12:36Z", + "updated_time": "2015-01-31T15:18:21Z" + } +} diff --git a/api-ref/source/v1/samples/deployment-metadata-response.json b/api-ref/source/v1/samples/deployment-metadata-response.json new file mode 100644 index 0000000000..8c5bd9a9dc --- /dev/null +++ b/api-ref/source/v1/samples/deployment-metadata-response.json @@ -0,0 +1,130 @@ +{ + "metadata": [ + { + "inputs": [ + { + "default": null, + "type": "String", + "name": "foo", + "value": "fooooo", + "description": null + }, + { + "default": null, + "type": "String", + "name": "bar", + "value": "baaaaa", + "description": null + }, + { + "type": "String", + "name": "deploy_server_id", + "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", + "description": "ID of the server being deployed to" + }, + { + "type": "String", + "name": "deploy_action", + "value": "CREATE", + "description": "Name of the current action being deployed" + }, + { + "type": "String", + "name": "deploy_stack_id", + "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc", + "description": "ID of the stack this deployment belongs to" + }, + { + "type": "String", + "name": "deploy_resource_name", + "value": "deployment", + "description": "Name of this deployment resource in the stack" + }, + { + "type": "String", + "name": "deploy_signal_id", + "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fdeployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=ca3571413e4a49998d580215517b3685&SignatureVersion=2&Signature=w6Iu%2BNbg86mqwSOUf1GLuKPO7KaD82PiGpL4ig9Q1l4%3D", + "description": "ID of signal to use for signalling output values" + } + ], + "group": "script", + "name": "a-config-we5zpvyu7b5o", + "outputs": [ + { + "type": "String", + "name": "result", + "error_output": false, + "description": null + } + ], + "options": null, + "creation_time": "2015-01-31T15:12:36Z", + "updated_time": "2015-01-31T15:18:21Z", + "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2", + "id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434" + }, + { + "inputs": [ + { + "default": null, + "type": "String", + "name": "foo", + "value": "fu", + "description": null + }, + { + "default": null, + "type": "String", + "name": "bar", + "value": "barmy", + "description": null + }, + { + "type": "String", + "name": "deploy_server_id", + "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", + "description": "ID of the server being deployed to" + }, + { + "type": "String", + "name": "deploy_action", + "value": "CREATE", + "description": "Name of the current action being deployed" + }, + { + "type": "String", + "name": "deploy_stack_id", + "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc", + "description": "ID of the stack this deployment belongs to" + }, + { + "type": "String", + "name": "deploy_resource_name", + "value": "other_deployment", + "description": "Name of this deployment resource in the stack" + }, + { + "type": "String", + "name": "deploy_signal_id", + "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fother_deployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=7b761482f8254946bcd3d5ccb36fe939&SignatureVersion=2&Signature=giMfv%2BhrAw6y%2FCMKQIQz2IhO5PkAj5%2BfP5YsL6rul3o%3D", + "description": "ID of signal to use for signalling output values" + } + ], + "group": "script", + "name": "a-config-we5zpvyu7b5o", + "outputs": [ + { + "type": "String", + "name": "result", + "error_output": false, + "description": null + } + ], + "options": null, + "creation_time": "2015-01-31T16:14:13Z", + "updated_time": "2015-01-31T16:18:19Z", + "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2", + "id": "8da95794-2ad9-4979-8ae5-739ce314c5cd" + } + ] +} diff --git a/api-ref/source/v1/samples/deployment-show-response.json b/api-ref/source/v1/samples/deployment-show-response.json new file mode 100644 index 0000000000..b234235acd --- /dev/null +++ b/api-ref/source/v1/samples/deployment-show-response.json @@ -0,0 +1,14 @@ +{ + "software_deployment": { + "status": "IN_PROGRESS", + "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", + "config_id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434", + "output_values": null, + "input_values": null, + "action": "CREATE", + "status_reason": "Deploy data available", + "id": "06e87bcc-33a2-4bce-aebd-533e698282d3", + "creation_time": "2015-01-31T15:12:36Z", + "updated_time": "2015-01-31T15:18:21Z" + } +} diff --git a/api-ref/source/v1/samples/deployment-update-request.json b/api-ref/source/v1/samples/deployment-update-request.json new file mode 100644 index 0000000000..a9877f5887 --- /dev/null +++ b/api-ref/source/v1/samples/deployment-update-request.json @@ -0,0 +1,10 @@ +{ + "status": "COMPLETE", + "output_values": { + "deploy_stdout": "Writing to /tmp/baaaaa\nWritten to /tmp/baaaaa\n", + "deploy_stderr": "+ echo Writing to /tmp/baaaaa\n+ echo fooooo\n+ cat /tmp/baaaaa\n+ echo -n The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/baaaaa\n+ echo Output to stderr\nOutput to stderr\n", + "deploy_status_code": 0, + "result": "The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE" + }, + "status_reason": "Outputs received" +} diff --git a/api-ref/source/v1/samples/deployment-update-response.json b/api-ref/source/v1/samples/deployment-update-response.json new file mode 100644 index 0000000000..19b7bbfec7 --- /dev/null +++ b/api-ref/source/v1/samples/deployment-update-response.json @@ -0,0 +1,19 @@ +{ + "software_deployment": { + "status": "COMPLETE", + "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", + "config_id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434", + "output_values": { + "deploy_stdout": "Writing to /tmp/baaaaa\nWritten to /tmp/baaaaa\n", + "deploy_stderr": "+ echo Writing to /tmp/baaaaa\n+ echo fooooo\n+ cat /tmp/baaaaa\n+ echo -n The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/baaaaa\n+ echo Output to stderr\nOutput to stderr\n", + "deploy_status_code": 0, + "result": "The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE" + }, + "input_values": null, + "action": "CREATE", + "status_reason": "Outputs received", + "id": "06e87bcc-33a2-4bce-aebd-533e698282d3", + "creation_time": "2015-01-31T15:12:36Z", + "updated_time": "2015-01-31T15:18:21Z" + } +} diff --git a/api-ref/source/v1/samples/deployments-list-response.json b/api-ref/source/v1/samples/deployments-list-response.json new file mode 100644 index 0000000000..95b783c554 --- /dev/null +++ b/api-ref/source/v1/samples/deployments-list-response.json @@ -0,0 +1,21 @@ +{ + "software_deployments": [ + { + "status": "COMPLETE", + "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5", + "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd", + "output_values": { + "deploy_stdout": "Writing to /tmp/barmy\nWritten to /tmp/barmy\n", + "deploy_stderr": "+ echo Writing to /tmp/barmy\n+ echo fu\n+ cat /tmp/barmy\n+ echo -n The file /tmp/barmy contains fu for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/barmy\n+ echo Output to stderr\nOutput to stderr\n", + "deploy_status_code": 0, + "result": "The file /tmp/barmy contains fu for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE" + }, + "input_values": null, + "action": "CREATE", + "status_reason": "Outputs received", + "id": "ef422fa5-719a-419e-a10c-72e3a367b0b8", + "creation_time": "2015-01-31T15:12:36Z", + "updated_time": "2015-01-31T15:18:21Z" + } + ] +} diff --git a/api-ref/source/v1/samples/event-show-response.json b/api-ref/source/v1/samples/event-show-response.json new file mode 100644 index 0000000000..3631e8ac3e --- /dev/null +++ b/api-ref/source/v1/samples/event-show-response.json @@ -0,0 +1,33 @@ +{ + "event": { + "event_time": "2015-06-25T14:59:53", + "id": "8db23e2e-72b2-47a2-9ed9-b52417f56e50", + "links": [ + { + "href": "http://hostname/v1/1234/stacks/mystack/56789/resources/random_key_name/events/8db23e2e-72b2-47a2-9ed9-b52417f56e50", + "rel": "self" + }, + { + "href": "http://hostname/v1/1234/stacks/mystack/56789/resources/random_key_name", + "rel": "resource" + }, + { + "href": "http://hostname/v1/1234/stacks/mystack/56789", + "rel": "stack" + } + ], + "logical_resource_id": "random_key_name", + "physical_resource_id": null, + "resource_name": "random_key_name", + "resource_properties": { + "character_classes": null, + "character_sequences": null, + "length": 8, + "salt": null, + "sequence": null + }, + "resource_status": "CREATE_IN_PROGRESS", + "resource_status_reason": "state changed", + "resource_type": "OS::Heat::RandomString" + } +} diff --git a/api-ref/source/v1/samples/events-list-response.json b/api-ref/source/v1/samples/events-list-response.json new file mode 100644 index 0000000000..83d8f88c4c --- /dev/null +++ b/api-ref/source/v1/samples/events-list-response.json @@ -0,0 +1,50 @@ +{ + "events": [ + { + "resource_name": "port", + "event_time": "2014-07-23T08:14:47Z", + "links": [ + { + "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/474bfdf0-a450-46ec-a78a-0c7faa404073", + "rel": "self" + }, + { + "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port", + "rel": "resource" + }, + { + "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5", + "rel": "stack" + } + ], + "logical_resource_id": "port", + "resource_status": "CREATE_FAILED", + "resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found", + "physical_resource_id": null, + "id": "474bfdf0-a450-46ec-a78a-0c7faa404073" + }, + { + "resource_name": "port", + "event_time": "2014-07-23T08:14:47Z", + "links": [ + { + "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/66fa95b6-e6f8-4f05-b1af-e828f5aba04c", + "rel": "self" + }, + { + "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port", + "rel": "resource" + }, + { + "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5", + "rel": "stack" + } + ], + "logical_resource_id": "port", + "resource_status": "CREATE_IN_PROGRESS", + "resource_status_reason": "state changed", + "physical_resource_id": null, + "id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c" + } + ] +} diff --git a/api-ref/source/v1/samples/heat-versions-response.json b/api-ref/source/v1/samples/heat-versions-response.json new file mode 100644 index 0000000000..e13cf94f30 --- /dev/null +++ b/api-ref/source/v1/samples/heat-versions-response.json @@ -0,0 +1,14 @@ +{ + "versions": [ + { + "status": "CURRENT", + "id": "v1.0", + "links": [ + { + "href": "http://23.253.228.211:8000/v1/", + "rel": "self" + } + ] + } + ] +} diff --git a/api-ref/source/v1/samples/resource-metadata-response.json b/api-ref/source/v1/samples/resource-metadata-response.json new file mode 100644 index 0000000000..7f1860ce86 --- /dev/null +++ b/api-ref/source/v1/samples/resource-metadata-response.json @@ -0,0 +1,6 @@ +{ + "metadata": { + "some_key": "some_value", + "some_other_key": "some_other_value" + } +} diff --git a/api-ref/source/v1/samples/resource-schema-response.json b/api-ref/source/v1/samples/resource-schema-response.json new file mode 100644 index 0000000000..9f930f1fd2 --- /dev/null +++ b/api-ref/source/v1/samples/resource-schema-response.json @@ -0,0 +1,30 @@ +{ + "attributes": { + "an_attribute": { + "description": "A runtime value of the resource." + } + }, + "properties": { + "a_property": { + "constraints": [ + { + "description": "Must be between 1 and 255 characters", + "length": { + "max": 255, + "min": 1 + } + } + ], + "description": "A resource description.", + "required": true, + "type": "string", + "update_allowed": false + } + }, + "resource_type": "OS::Heat::AResourceName", + "support_status": { + "message": "A status message", + "status": "SUPPORTED", + "version": "2014.1" + } +} diff --git a/api-ref/source/v1/samples/resource-show-response.json b/api-ref/source/v1/samples/resource-show-response.json new file mode 100644 index 0000000000..6062ab2db5 --- /dev/null +++ b/api-ref/source/v1/samples/resource-show-response.json @@ -0,0 +1,27 @@ +{ + "resource": { + "attributes": { + "value": "I9S20uIp" + }, + "creation_time": "2015-06-25T14:59:53", + "description": "", + "links": [ + { + "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c/resources/random_key_name", + "rel": "self" + }, + { + "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c", + "rel": "stack" + } + ], + "logical_resource_id": "random_key_name", + "physical_resource_id": "mystack-random_key_name-pmjmy5pks735", + "required_by": [], + "resource_name": "random_key_name", + "resource_status": "CREATE_COMPLETE", + "resource_status_reason": "state changed", + "resource_type": "OS::Heat::RandomString", + "updated_time": "2015-06-25T14:59:53" + } +} diff --git a/api-ref/source/v1/samples/resource-type-template-response.json b/api-ref/source/v1/samples/resource-type-template-response.json new file mode 100644 index 0000000000..13cc0f5cc8 --- /dev/null +++ b/api-ref/source/v1/samples/resource-type-template-response.json @@ -0,0 +1,50 @@ +{ + "HeatTemplateFormatVersion": "2012-12-12", + "Outputs": { + "private_key": { + "Description": "The private key if it has been saved.", + "Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"private_key\"]}" + }, + "public_key": { + "Description": "The public key.", + "Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"public_key\"]}" + } + }, + "Parameters": { + "name": { + "Description": "The name of the key pair.", + "Type": "String" + }, + "public_key": { + "Description": "The optional public key. This allows users to supply the public key from a pre-existing key pair. If not supplied, a new key pair will be generated.", + "Type": "String" + }, + "save_private_key": { + "AllowedValues": [ + true, + "true", + false, + "false" + ], + "Default": false, + "Description": "true if the system should remember a generated private key; false otherwise.", + "Type": "String" + } + }, + "Resources": { + "KeyPair": { + "Properties": { + "name": { + "Ref": "name" + }, + "public_key": { + "Ref": "public_key" + }, + "save_private_key": { + "Ref": "save_private_key" + } + }, + "Type": "OS::Nova::KeyPair" + } + } +} diff --git a/api-ref/source/v1/samples/resource-types-list-response.json b/api-ref/source/v1/samples/resource-types-list-response.json new file mode 100644 index 0000000000..f9cbef5d6c --- /dev/null +++ b/api-ref/source/v1/samples/resource-types-list-response.json @@ -0,0 +1,61 @@ +{ + "resource_types": [ + "AWS::EC2::Instance", + "OS::Heat::ScalingPolicy", + "AWS::CloudFormation::Stack", + "OS::Keystone::Group", + "OS::Glance::Image", + "AWS::EC2::Volume", + "OS::Heat::SoftwareDeployment", + "AWS::AutoScaling::ScalingPolicy", + "AWS::EC2::InternetGateway", + "OS::Heat::SoftwareDeployments", + "AWS::EC2::VolumeAttachment", + "AWS::CloudFormation::WaitConditionHandle", + "OS::Cinder::VolumeAttachment", + "OS::Cinder::EncryptedVolumeType", + "OS::Heat::AutoScalingGroup", + "OS::Nova::FloatingIP", + "OS::Heat::HARestarter", + "OS::Keystone::Project", + "OS::Keystone::Endpoint", + "OS::Heat::InstanceGroup", + "AWS::CloudWatch::Alarm", + "AWS::AutoScaling::AutoScalingGroup", + "OS::Heat::CloudConfig", + "OS::Heat::SoftwareComponent", + "OS::Cinder::Volume", + "OS::Keystone::Service", + "OS::Heat::WaitConditionHandle", + "OS::Heat::SoftwareConfig", + "AWS::CloudFormation::WaitCondition", + "OS::Heat::StructuredDeploymentGroup", + "OS::Heat::RandomString", + "OS::Heat::SoftwareDeploymentGroup", + "OS::Nova::KeyPair", + "OS::Heat::MultipartMime", + "OS::Heat::UpdateWaitConditionHandle", + "OS::Nova::Server", + "AWS::IAM::AccessKey", + "AWS::EC2::SecurityGroup", + "AWS::EC2::EIPAssociation", + "AWS::EC2::EIP", + "OS::Heat::AccessPolicy", + "AWS::IAM::User", + "OS::Heat::WaitCondition", + "OS::Heat::StructuredDeployment", + "AWS::RDS::DBInstance", + "AWS::AutoScaling::LaunchConfiguration", + "OS::Heat::Stack", + "OS::Nova::FloatingIPAssociation", + "OS::Heat::ResourceGroup", + "OS::Heat::StructuredConfig", + "OS::Nova::ServerGroup", + "OS::Heat::StructuredDeployments", + "OS::Keystone::Role", + "OS::Keystone::User", + "AWS::ElasticLoadBalancing::LoadBalancer", + "OS::Nova::Flavor", + "OS::Cinder::VolumeType" + ] +} diff --git a/api-ref/source/v1/samples/resources-list-response.json b/api-ref/source/v1/samples/resources-list-response.json new file mode 100644 index 0000000000..5df952ca04 --- /dev/null +++ b/api-ref/source/v1/samples/resources-list-response.json @@ -0,0 +1,25 @@ +{ + "resources": [ + { + "creation_time": "2015-06-25T14:59:53", + "links": [ + { + "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c/resources/random_key_name", + "rel": "self" + }, + { + "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c", + "rel": "stack" + } + ], + "logical_resource_id": "random_key_name", + "physical_resource_id": "mystack-random_key_name-pmjmy5pks735", + "required_by": [], + "resource_name": "random_key_name", + "resource_status": "CREATE_COMPLETE", + "resource_status_reason": "state changed", + "resource_type": "OS::Heat::RandomString", + "updated_time": "2015-06-25T14:59:53" + } + ] +} diff --git a/api-ref/source/v1/samples/services-list-response.json b/api-ref/source/v1/samples/services-list-response.json new file mode 100644 index 0000000000..b49be73147 --- /dev/null +++ b/api-ref/source/v1/samples/services-list-response.json @@ -0,0 +1,30 @@ +{ + "services": [ + { + "status": "up", + "binary": "heat-engine", + "report_interval": 60, + "engine_id": "9d9242c3-4b9e-45e1-9e74-7615fbf20e5d", + "created_at": "2015-02-03T05:55:59.000000", + "hostname": "mrkanag", + "updated_at": "2015-02-03T05:57:59.000000", + "topic": "engine", + "host": "engine-1", + "deleted_at": null, + "id": "e1908f44-42f9-483f-b778-bc814072c33d" + }, + { + "status": "down", + "binary": "heat-engine", + "report_interval": 60, + "engine_id": "2d2434bf-adb6-4453-9c6b-b22fb8bd2306", + "created_at": "2015-02-03T06:03:14.000000", + "hostname": "mrkanag", + "updated_at": "2015-02-03T06:09:55.000000", + "topic": "engine", + "host": "engine", + "deleted_at": null, + "id": "582b5657-6db7-48ad-8483-0096350faa21" + } + ] +} diff --git a/api-ref/source/v1/samples/stack-abandon-response.json b/api-ref/source/v1/samples/stack-abandon-response.json new file mode 100644 index 0000000000..57bd22da23 --- /dev/null +++ b/api-ref/source/v1/samples/stack-abandon-response.json @@ -0,0 +1,69 @@ +{ + "status": "COMPLETE", + "name": "g", + "dry_run": true, + "template": { + "outputs": { + "instance_ip": { + "value": { + "str_replace": { + "params": { + "username": "ec2-user", + "hostname": { + "get_attr": [ + "server", + "first_address" + ] + } + }, + "template": "ssh username@hostname" + } + } + } + }, + "heat_template_version": "2013-05-23", + "resources": { + "server": { + "type": "OS::Nova::Server", + "properties": { + "key_name": { + "get_param": "key_name" + }, + "image": { + "get_param": "image" + }, + "flavor": { + "get_param": "flavor" + } + } + } + }, + "parameters": { + "key_name": { + "default": "heat_key", + "type": "string" + }, + "image": { + "default": "fedora-amd64", + "type": "string" + }, + "flavor": { + "default": "m1.small", + "type": "string" + } + } + }, + "action": "CREATE", + "id": "16934ca3-40e0-4fb2-a289-a700662ec05a", + "resources": { + "server": { + "status": "COMPLETE", + "name": "server", + "resource_data": {}, + "resource_id": "39d5dad7-7d7a-4cc8-bd84-851e9e2ff4ea", + "action": "CREATE", + "type": "OS::Nova::Server", + "metadata": {} + } + } +} diff --git a/api-ref/source/v1/samples/stack-action-cancel-update-request.json b/api-ref/source/v1/samples/stack-action-cancel-update-request.json new file mode 100644 index 0000000000..ad76bd690b --- /dev/null +++ b/api-ref/source/v1/samples/stack-action-cancel-update-request.json @@ -0,0 +1,3 @@ +{ + "cancel_update": null +} diff --git a/api-ref/source/v1/samples/stack-action-check-request.json b/api-ref/source/v1/samples/stack-action-check-request.json new file mode 100644 index 0000000000..019b28e776 --- /dev/null +++ b/api-ref/source/v1/samples/stack-action-check-request.json @@ -0,0 +1,3 @@ +{ + "check": null +} diff --git a/api-ref/source/v1/samples/stack-action-resume-request.json b/api-ref/source/v1/samples/stack-action-resume-request.json new file mode 100644 index 0000000000..ff00d97a14 --- /dev/null +++ b/api-ref/source/v1/samples/stack-action-resume-request.json @@ -0,0 +1,3 @@ +{ + "resume": null +} diff --git a/api-ref/source/v1/samples/stack-action-suspend-request.json b/api-ref/source/v1/samples/stack-action-suspend-request.json new file mode 100644 index 0000000000..8c2206a063 --- /dev/null +++ b/api-ref/source/v1/samples/stack-action-suspend-request.json @@ -0,0 +1,3 @@ +{ + "suspend": null +} diff --git a/api-ref/source/v1/samples/stack-adopt-request.json b/api-ref/source/v1/samples/stack-adopt-request.json new file mode 100644 index 0000000000..242afb1611 --- /dev/null +++ b/api-ref/source/v1/samples/stack-adopt-request.json @@ -0,0 +1,33 @@ +{ + "adopt_stack_data": { + "action": "CREATE", + "id": "bxxxxx4-0xx2-4xx1-axx6-exxxxxxxc", + "name": "teststack", + "resources": { + "MyServer": { + "action": "CREATE", + "metadata": {}, + "name": "MyServer", + "resource_data": {}, + "resource_id": "cxxxx3-dxx3-4xx-bxx2-3xxxxxxxxa", + "status": "COMPLETE", + "type": "OS::Trove::Instance" + } + }, + "status": "COMPLETE", + "template": { + "heat_template_version": "2013-05-23", + "resources": { + "MyServer": { + "type": "OS::Trove::Instance", + "properties": { + "flavor": "m1.small", + "size": 10 + } + } + } + } + }, + "stack_name": "{stack_name}", + "timeout_mins": "{timeout_mins}" +} diff --git a/api-ref/source/v1/samples/stack-create-request.json b/api-ref/source/v1/samples/stack-create-request.json new file mode 100644 index 0000000000..9b03d44bf9 --- /dev/null +++ b/api-ref/source/v1/samples/stack-create-request.json @@ -0,0 +1,32 @@ +{ + "files": {}, + "disable_rollback": true, + "parameters": { + "flavor": "m1.heat" + }, + "stack_name": "teststack", + "template": { + "heat_template_version": "2013-05-23", + "description": "Simple template to test heat commands", + "parameters": { + "flavor": { + "default": "m1.tiny", + "type": "string" + } + }, + "resources": { + "hello_world": { + "type": "OS::Nova::Server", + "properties": { + "key_name": "heat_key", + "flavor": { + "get_param": "flavor" + }, + "image": "40be8d1a-3eb9-40de-8abd-43237517384f", + "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n" + } + } + } + }, + "timeout_mins": 60 +} diff --git a/api-ref/source/v1/samples/stack-create-response.json b/api-ref/source/v1/samples/stack-create-response.json new file mode 100644 index 0000000000..81c91ce7fd --- /dev/null +++ b/api-ref/source/v1/samples/stack-create-response.json @@ -0,0 +1,11 @@ +{ + "stack": { + "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c", + "links": [ + { + "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/teststack/3095aefc-09fb-4bc7-b1f0-f21a304e864c", + "rel": "self" + } + ] + } +} diff --git a/api-ref/source/v1/samples/stack-find-response.json b/api-ref/source/v1/samples/stack-find-response.json new file mode 100644 index 0000000000..06b05c5c54 --- /dev/null +++ b/api-ref/source/v1/samples/stack-find-response.json @@ -0,0 +1,27 @@ +{ + "stack": { + "capabilities": [], + "creation_time": "2014-06-04T20:36:12Z", + "description": "sample stack", + "disable_rollback": true, + "id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7", + "links": [ + { + "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/5333af0c-cc26-47ee-ac3d-8784cefafbd7", + "rel": "self" + } + ], + "notification_topics": [], + "outputs": [], + "parameters": { + "OS::stack_id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7", + "OS::stack_name": "simple_stack" + }, + "stack_name": "simple_stack", + "stack_status": "CREATE_COMPLETE", + "stack_status_reason": "Stack CREATE completed successfully", + "template_description": "sample stack", + "timeout_mins": null, + "updated_time": null + } +} diff --git a/api-ref/source/v1/samples/stack-outputs-list-response.json b/api-ref/source/v1/samples/stack-outputs-list-response.json new file mode 100644 index 0000000000..8cb61499f1 --- /dev/null +++ b/api-ref/source/v1/samples/stack-outputs-list-response.json @@ -0,0 +1,10 @@ +{ + "outputs": [ + { + "output_key": "output name", + "output_value": "output value", + "description": "output description", + "output_error": null + } + ] +} diff --git a/api-ref/source/v1/samples/stack-preview-response.json b/api-ref/source/v1/samples/stack-preview-response.json new file mode 100644 index 0000000000..a36f8cf5d2 --- /dev/null +++ b/api-ref/source/v1/samples/stack-preview-response.json @@ -0,0 +1,168 @@ +{ + "stack": { + "capabilities": [], + "creation_time": "2015-01-31T15:12:36Z", + "description": "HOT template for Nova Server resource.\n", + "disable_rollback": true, + "id": "None", + "links": [ + { + "href": "http://192.168.122.102:8004/v1/6e18cc2bdbeb48a5basad2dc499f6804/stacks/test_stack/None", + "rel": "self" + } + ], + "notification_topics": [], + "parameters": { + "OS::project_id": "6e18cc2bdbeb48a5basad2dc499f6804", + "OS::stack_id": "None", + "OS::stack_name": "teststack", + "admin_user": "cloud-user", + "flavor": "m1.small", + "image": "F20-cfg", + "key_name": "heat_key", + "server_name": "MyServer" + }, + "parent": null, + "resources": [ + { + "attributes": {}, + "description": "", + "metadata": {}, + "physical_resource_id": "", + "properties": { + "description": "Ping and SSH", + "name": "the_sg", + "rules": [ + { + "direction": "ingress", + "ethertype": "IPv4", + "port_range_max": null, + "port_range_min": null, + "protocol": "icmp", + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_mode": "remote_ip_prefix" + }, + { + "direction": "ingress", + "ethertype": "IPv4", + "port_range_max": 65535, + "port_range_min": 1, + "protocol": "tcp", + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_mode": "remote_ip_prefix" + }, + { + "direction": "ingress", + "ethertype": "IPv4", + "port_range_max": 65535, + "port_range_min": 1, + "protocol": "udp", + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_mode": "remote_ip_prefix" + } + ] + }, + "required_by": [ + "server1" + ], + "resource_action": "INIT", + "resource_identity": { + "path": "/resources/the_sg_res", + "stack_id": "None", + "stack_name": "teststack", + "tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804" + }, + "resource_name": "the_sg_res", + "resource_status": "COMPLETE", + "resource_status_reason": "", + "resource_type": "OS::Neutron::SecurityGroup", + "stack_identity": { + "path": "", + "stack_id": "None", + "stack_name": "teststack", + "tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804" + }, + "stack_name": "teststack", + "updated_time": "2015-01-31T15:12:36Z" + }, + { + "attributes": { + "accessIPv4": "", + "accessIPv6": "", + "addresses": "", + "console_urls": "", + "first_address": "", + "instance_name": "", + "name": "MyServer", + "networks": "", + "show": "" + }, + "description": "", + "metadata": {}, + "physical_resource_id": "", + "properties": { + "admin_pass": null, + "admin_user": "cloud-user", + "availability_zone": null, + "block_device_mapping": null, + "config_drive": null, + "diskConfig": null, + "flavor": "m1.small", + "flavor_update_policy": "RESIZE", + "image": "F20-cfg", + "image_update_policy": "REPLACE", + "key_name": "heat_key", + "metadata": { + "ha_stack": "None" + }, + "name": "MyServer", + "networks": [ + { + "fixed_ip": null, + "network": "private", + "port": null, + "uuid": null + } + ], + "personality": {}, + "reservation_id": null, + "scheduler_hints": null, + "security_groups": [ + "None" + ], + "software_config_transport": "POLL_SERVER_CFN", + "user_data": "", + "user_data_format": "HEAT_CFNTOOLS" + }, + "required_by": [], + "resource_action": "INIT", + "resource_identity": { + "path": "/resources/hello_world", + "stack_id": "None", + "stack_name": "teststack", + "tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234" + }, + "resource_name": "hello_world", + "resource_status": "COMPLETE", + "resource_status_reason": "", + "resource_type": "OS::Nova::Server", + "stack_identity": { + "path": "", + "stack_id": "None", + "stack_name": "teststack", + "tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234" + }, + "stack_name": "teststack", + "updated_time": "2015-01-31T15:12:36Z" + } + ], + "stack_name": "test_stack", + "stack_owner": "admin", + "template_description": "HOT template for Nova Server resource.\n", + "timeout_mins": null, + "updated_time": null + } +} diff --git a/api-ref/source/v1/samples/stack-show-output-response.json b/api-ref/source/v1/samples/stack-show-output-response.json new file mode 100644 index 0000000000..356eb60b6e --- /dev/null +++ b/api-ref/source/v1/samples/stack-show-output-response.json @@ -0,0 +1,8 @@ +{ + "output": { + "output_key": "output_name", + "output_value": "output_value", + "description": "output description", + "output_error": null + } +} diff --git a/api-ref/source/v1/samples/stack-show-response.json b/api-ref/source/v1/samples/stack-show-response.json new file mode 100644 index 0000000000..c0b840c1ed --- /dev/null +++ b/api-ref/source/v1/samples/stack-show-response.json @@ -0,0 +1,32 @@ +{ + "stack": { + "capabilities": [], + "creation_time": "2014-06-03T20:59:46Z", + "description": "sample stack", + "disable_rollback": true, + "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c", + "links": [ + { + "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c", + "rel": "self" + } + ], + "notification_topics": [], + "outputs": [], + "parameters": { + "OS::project_id": "3ab5b02f-a01f-4f95-afa1-e254afc4a435", + "OS::stack_id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c", + "OS::stack_name": "simple_stack" + }, + "stack_name": "simple_stack", + "stack_owner": "simple_username", + "stack_status": "CREATE_COMPLETE", + "stack_status_reason": "Stack CREATE completed successfully", + "template_description": "sample stack", + "stack_user_project_id": "65728b74-cfe7-4f17-9c15-11d4f686e591", + "timeout_mins": "", + "updated_time": "", + "parent": "", + "tags": "" + } +} diff --git a/api-ref/source/v1/samples/stack-show-snapshot-response.json b/api-ref/source/v1/samples/stack-show-snapshot-response.json new file mode 100644 index 0000000000..6646b9fb27 --- /dev/null +++ b/api-ref/source/v1/samples/stack-show-snapshot-response.json @@ -0,0 +1,47 @@ +{ + "snapshot": { + "id": "7c4e1ef4-bf1b-41ab-a0c8-ce01f4ffdfa1", + "name": "vol_snapshot", + "status": "COMPLETE", + "status_reason": "Stack SNAPSHOT completed successfully", + "creation_time": "2015-08-04T20:57:55Z", + "data": { + "status": "COMPLETE", + "name": "stack_vol1", + "stack_user_project_id": "fffa11067b1c48129ddfb78fba2bf09f", + "environment": { + "parameters": {}, + "resource_registry": { + "resources": {} + } + }, + "template": { + "heat_template_version": "2013-05-23", + "resources": { + "volume": { + "type": "OS::Cinder::Volume", + "properties": { + "size": 1 + } + } + } + }, + "action": "SNAPSHOT", + "project_id": "ecdb08032cd042179692a1b148f6565e", + "id": "656452c2-e151-40da-8704-c844e69b485c", + "resources": { + "volume": { + "status": "COMPLETE", + "name": "volume", + "resource_data": { + "backup_id": "99108cf8-398f-461b-a043-bdceb7c9f572" + }, + "resource_id": "3ab8cf79-807b-4c40-b743-0655f91e072f", + "action": "SNAPSHOT", + "type": "OS::Cinder::Volume", + "metadata": {} + } + } + } + } +} diff --git a/api-ref/source/v1/samples/stack-snapshot-request.json b/api-ref/source/v1/samples/stack-snapshot-request.json new file mode 100644 index 0000000000..f7d3a6210c --- /dev/null +++ b/api-ref/source/v1/samples/stack-snapshot-request.json @@ -0,0 +1,3 @@ +{ + "name": "vol_snapshot" +} diff --git a/api-ref/source/v1/samples/stack-snapshot-response.json b/api-ref/source/v1/samples/stack-snapshot-response.json new file mode 100644 index 0000000000..d3ecfcde1d --- /dev/null +++ b/api-ref/source/v1/samples/stack-snapshot-response.json @@ -0,0 +1,8 @@ +{ + "id": "13c3a4b5-0585-440e-85a4-6f96b20e7a78", + "name": "vol_snapshot", + "status": "IN_PROGRESS", + "status_reason": null, + "data": null, + "creation_time": "2015-09-01T20:57:55Z" +} diff --git a/api-ref/source/v1/samples/stack-snapshots-list-response.json b/api-ref/source/v1/samples/stack-snapshots-list-response.json new file mode 100644 index 0000000000..d25bdf114c --- /dev/null +++ b/api-ref/source/v1/samples/stack-snapshots-list-response.json @@ -0,0 +1,12 @@ +{ + "snapshots": [ + { + "id": "7c4e1ef4-bf1b-41ab-a0c8-ce01f4ffdfa1", + "name": "vol_snapshot", + "status": "IN_PROGRESS", + "status_reason": null, + "creation_time": "2015-08-04T20:57:55Z", + "data": null + } + ] +} diff --git a/api-ref/source/v1/samples/stack-update-preview-response.json b/api-ref/source/v1/samples/stack-update-preview-response.json new file mode 100644 index 0000000000..9a511a1788 --- /dev/null +++ b/api-ref/source/v1/samples/stack-update-preview-response.json @@ -0,0 +1,67 @@ +{ + "unchanged": [ + { + "updated_time": "datetime", + "resource_name": "", + "physical_resource_id": "{resource id or ''}", + "resource_action": "CREATE", + "resource_status": "COMPLETE", + "resource_status_reason": "", + "resource_type": "restype", + "stack_identity": "{stack_id}", + "stack_name": "{stack_name}" + } + ], + "updated": [ + { + "updated_time": "datetime", + "resource_name": "", + "physical_resource_id": "{resource id or ''}", + "resource_action": "CREATE", + "resource_status": "COMPLETE", + "resource_status_reason": "", + "resource_type": "restype", + "stack_identity": "{stack_id}", + "stack_name": "{stack_name}" + } + ], + "replaced": [ + { + "updated_time": "datetime", + "resource_name": "", + "physical_resource_id": "{resource id or ''}", + "resource_action": "CREATE", + "resource_status": "COMPLETE", + "resource_status_reason": "", + "resource_type": "restype", + "stack_identity": "{stack_id}", + "stack_name": "{stack_name}" + } + ], + "added": [ + { + "updated_time": "datetime", + "resource_name": "", + "physical_resource_id": "{resource id or ''}", + "resource_action": "CREATE", + "resource_status": "COMPLETE", + "resource_status_reason": "", + "resource_type": "restype", + "stack_identity": "{stack_id}", + "stack_name": "{stack_name}" + } + ], + "deleted": [ + { + "updated_time": "datetime", + "resource_name": "", + "physical_resource_id": "{resource id or ''}", + "resource_action": "CREATE", + "resource_status": "COMPLETE", + "resource_status_reason": "", + "resource_type": "restype", + "stack_identity": "{stack_id}", + "stack_name": "{stack_name}" + } + ] +} diff --git a/api-ref/source/v1/samples/stack-update-request.json b/api-ref/source/v1/samples/stack-update-request.json new file mode 100644 index 0000000000..407a3c03c2 --- /dev/null +++ b/api-ref/source/v1/samples/stack-update-request.json @@ -0,0 +1,28 @@ +{ + "template": { + "heat_template_version": "2013-05-23", + "description": "Create a simple stack", + "parameters": { + "flavor": { + "default": "m1.tiny", + "type": "string" + } + }, + "resources": { + "hello_world": { + "type": "OS::Nova::Server", + "properties": { + "key_name": "heat_key", + "flavor": { + "get_param": "flavor" + }, + "image": "40be8d1a-3eb9-40de-8abd-43237517384f", + "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n" + } + } + } + }, + "parameters": { + "flavor": "m1.small" + } +} diff --git a/api-ref/source/v1/samples/stacks-list-response.json b/api-ref/source/v1/samples/stacks-list-response.json new file mode 100644 index 0000000000..b758c840c6 --- /dev/null +++ b/api-ref/source/v1/samples/stacks-list-response.json @@ -0,0 +1,20 @@ +{ + "stacks": [ + { + "creation_time": "2014-06-03T20:59:46Z", + "description": "sample stack", + "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c", + "links": [ + { + "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c", + "rel": "self" + } + ], + "stack_name": "simple_stack", + "stack_status": "CREATE_COMPLETE", + "stack_status_reason": "Stack CREATE completed successfully", + "updated_time": "", + "tags": "" + } + ] +} diff --git a/api-ref/source/v1/samples/template-show-response.json b/api-ref/source/v1/samples/template-show-response.json new file mode 100644 index 0000000000..06cdc4c33b --- /dev/null +++ b/api-ref/source/v1/samples/template-show-response.json @@ -0,0 +1,28 @@ +{ + "description": "Hello world HOT template that just defines a single server. Contains just base features to verify base HOT support.\n", + "heat_template_version": "2013-05-23", + "outputs": { + "foo": { + "description": "Show foo parameter value", + "value": { + "get_param": "foo" + } + } + }, + "parameters": { + "foo": { + "default": "secret", + "description": "Name of an existing key pair to use for the server", + "hidden": true, + "type": "string" + } + }, + "resources": { + "random_key_name": { + "properties": { + "length": 8 + }, + "type": "OS::Heat::RandomString" + } + } +} diff --git a/api-ref/source/v1/samples/template-validate-request.json b/api-ref/source/v1/samples/template-validate-request.json new file mode 100644 index 0000000000..7ba5f97869 --- /dev/null +++ b/api-ref/source/v1/samples/template-validate-request.json @@ -0,0 +1,3 @@ +{ + "template_url": "/PATH_TO_HEAT_TEMPLATES/WordPress_Single_Instance.template" +} diff --git a/api-ref/source/v1/samples/template-validate-response.json b/api-ref/source/v1/samples/template-validate-response.json new file mode 100644 index 0000000000..cbdf7c26f1 --- /dev/null +++ b/api-ref/source/v1/samples/template-validate-response.json @@ -0,0 +1,41 @@ +{ + "Description": "A template that provides a single server instance.", + "Parameters": { + "server-size": { + "default": "1GB Standard Instance", + "description": "Server size", + "type": "String", + "constraints": [ + { + "allowed_values": [ + "512MB Standard Instance", + "1GB Standard Instance", + "4GB Standard Instance", + "8GB Standard Instance" + ], + "description": "Must be a valid server size." + } + ] + }, + "key_name": { + "description": "Keypair name for SSH access to the server", + "required": true, + "type": "String" + }, + "server_name": { + "default": "My server", + "description": "My server", + "type": "String" + } + }, + "ParameterGroups": [ + { + "label": "Parameter groups", + "description": "My parameter groups", + "parameters": [ + "param_name-1", + "param_name-2" + ] + } + ] +} diff --git a/api-ref/source/v1/samples/template-versions-response.json b/api-ref/source/v1/samples/template-versions-response.json new file mode 100644 index 0000000000..f82a8c2a17 --- /dev/null +++ b/api-ref/source/v1/samples/template-versions-response.json @@ -0,0 +1,32 @@ +{ + "template_versions": [ + { + "version": "heat_template_version.2014-10-16", + "type": "hot" + }, + { + "version": "heat_template_version.2015-04-30", + "type": "hot" + }, + { + "version": "HeatTemplateFormatVersion.2012-12-12", + "type": "cfn" + }, + { + "version": "heat_template_version.2015-10-15", + "type": "hot" + }, + { + "version": "AWSTemplateFormatVersion.2010-09-09", + "type": "cfn" + }, + { + "version": "heat_template_version.2013-05-23", + "type": "hot" + }, + { + "version": "heat_template_version.2016-04-08", + "type": "hot" + } + ] +} diff --git a/api-ref/source/v1/service-status.inc b/api-ref/source/v1/service-status.inc new file mode 100644 index 0000000000..e6940bb2bf --- /dev/null +++ b/api-ref/source/v1/service-status.inc @@ -0,0 +1,67 @@ +.. -*- rst -*- + +============== +Manage service +============== + + + + +Show orchestration engine status +================================ + +.. rest_method:: GET /v1/{tenant_id}/services + +Enables administrative users to view details for all orchestration engines. + +Orchestration engine details include ``engine_id``, topic name, +last updated time, health status, and host name. + +Troubleshooting + +- A ``503`` error code indicates that the heat engines are not + operational. Run the heat-manage service list command or contact + your cloud provider to determine why the heat engines are not + operational. + + +Normal response codes: 200 +Error response codes:403,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - binary: binary + - report_interval: report_interval + - created_at: created_at + - hostname: hostname + - updated_at: updated_at + - topic: topic + - services: services + - deleted_at: deleted_at + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/services-list-response.json + :language: javascript + + + + + diff --git a/api-ref/source/v1/software-config.inc b/api-ref/source/v1/software-config.inc new file mode 100644 index 0000000000..e79cc5d3c1 --- /dev/null +++ b/api-ref/source/v1/software-config.inc @@ -0,0 +1,416 @@ +.. -*- rst -*- + +====================== +Software configuration +====================== + + + + +List deployments +================ + +.. rest_method:: GET /v1/{tenant_id}/software_deployments + +Lists all available software deployments. + + +Normal response codes: 200 +Error response codes:404,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - server_id: server_id + - config_id: config_id + - output_values: output_values + - creation_time: creation_time + - updated_at: updated_at + - input_values: input_values + - action: action + - status_reason: status_reason + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/deployments-list-response.json + :language: javascript + + + + + + + + +Create deployment +================= + +.. rest_method:: POST /v1/{tenant_id}/software_deployments + +Creates a software deployment. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - status: status + - server_id: server_id + - config_id: config_id + - stack_user_project_id: stack_user_project_id + - action: action + - status_reason: status_reason + - tenant_id: tenant_id + +Request Example +--------------- + +.. literalinclude:: samples/deployment-create-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - server_id: server_id + - config_id: config_id + - output_values: output_values + - creation_time: creation_time + - updated_at: updated_at + - input_values: input_values + - action: action + - status_reason: status_reason + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/deployment-create-response.json + :language: javascript + + + + +Show server configuration metadata +================================== + +.. rest_method:: GET /v1/{tenant_id}/software_deployments/metadata/{server_id} + +Shows the deployment configuration metadata for a server. + +Use the ``group`` property to specify the configuration hook to +which the pass the metadata item. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - server_id: server_id + - tenant_id: tenant_id + + + + +Response Example +---------------- + +.. literalinclude:: samples/deployment-metadata-response.json + :language: javascript + + + + +Create configuration +==================== + +.. rest_method:: POST /v1/{tenant_id}/software_configs + +Creates a software configuration. + + +Normal response codes: 200 +Error response codes:404,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - inputs: inputs + - group: group + - name: name + - outputs: outputs + - config: config + - options: options + - tenant_id: tenant_id + +Request Example +--------------- + +.. literalinclude:: samples/config-create-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - inputs: inputs + - group: group + - name: name + - outputs: outputs + - creation_time: creation_time + - config: config + - options: options + + + +Response Example +---------------- + +.. literalinclude:: samples/config-create-response.json + :language: javascript + + + + + + + +Show deployment details +======================= + +.. rest_method:: GET /v1/{tenant_id}/software_deployments/{deployment_id} + +Shows details for a software deployment. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - deployment_id: deployment_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - server_id: server_id + - config_id: config_id + - output_values: output_values + - creation_time: creation_time + - updated_at: updated_at + - input_values: input_values + - action: action + - status_reason: status_reason + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/deployment-show-response.json + :language: javascript + + + + +Update deployment +================= + +.. rest_method:: PUT /v1/{tenant_id}/software_deployments/{deployment_id} + +Updates a software deployment. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - action: action + - output_values: output_values + - config_id: config_id + - status: status + - status_reason: status_reason + - tenant_id: tenant_id + - deployment_id: deployment_id + +Request Example +--------------- + +.. literalinclude:: samples/deployment-update-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - server_id: server_id + - config_id: config_id + - output_values: output_values + - creation_time: creation_time + - updated_at: updated_at + - input_values: input_values + - action: action + - status_reason: status_reason + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/deployment-update-response.json + :language: javascript + + + + +Delete deployment +================= + +.. rest_method:: DELETE /v1/{tenant_id}/software_deployments/{deployment_id} + +Deletes a software deployment. + +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - deployment_id: deployment_id + + + + + + +Show configuration details +========================== + +.. rest_method:: GET /v1/{tenant_id}/software_configs/{config_id} + +Shows details for a software configuration. + + +Normal response codes: 200 +Error response codes:404,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - config_id: config_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - inputs: inputs + - group: group + - name: name + - outputs: outputs + - creation_time: creation_time + - config: config + - options: options + + + +Response Example +---------------- + +.. literalinclude:: samples/config-show-response.json + :language: javascript + + + + + + + +Delete config +============= + +.. rest_method:: DELETE /v1/{tenant_id}/software_configs/{config_id} + +Deletes a software configuration. + +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - config_id: config_id + + + + + diff --git a/api-ref/source/v1/stack-actions.inc b/api-ref/source/v1/stack-actions.inc new file mode 100644 index 0000000000..e1d49ac761 --- /dev/null +++ b/api-ref/source/v1/stack-actions.inc @@ -0,0 +1,173 @@ +.. -*- rst -*- + +============= +Stack actions +============= + +Performs non-lifecycle operations on the stack. Specify the action +in the request body. + + +Suspend stack +============= + +.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions + +Suspends a stack. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - suspend: suspend + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-action-suspend-request.json + :language: javascript + + + + + +Response Example +---------------- + +.. literalinclude:: + :language: javascript + + + + +Resume stack +============ + +.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions + +Resumes a suspended stack. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - resume: resume + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-action-resume-request.json + :language: javascript + + + + + +Response Example +---------------- + +.. literalinclude:: + :language: javascript + + + + +Cancel stack update +=================== + +.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions + +Cancels a currently running update of a stack. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - cancel_update: cancel_update + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-action-cancel-update-request.json + :language: javascript + + + + + +Response Example +---------------- + +.. literalinclude:: + :language: javascript + + + + +Check stack resources +===================== + +.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions + +Checks whether the resources are in expected states for a stack. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - check: check + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-action-check-request.json + :language: javascript + + + + + +Response Example +---------------- + +.. literalinclude:: + :language: javascript + + + diff --git a/api-ref/source/v1/stack-events.inc b/api-ref/source/v1/stack-events.inc new file mode 100644 index 0000000000..f51f31a0b2 --- /dev/null +++ b/api-ref/source/v1/stack-events.inc @@ -0,0 +1,155 @@ +.. -*- rst -*- + +============ +Stack events +============ + + + + +Show event details +================== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events/{event_id} + +Shows details for an event. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - resource_name: resource_name + - stack_name: stack_name + - tenant_id: tenant_id + - event_id: event_id + - stack_id: stack_id + + + + +Response Example +---------------- + +.. literalinclude:: samples/event-show-response.json + :language: javascript + + + + +Find stack events +================= + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/events + +Finds the canonical URL for the event list of a stack. + +Error response codes:302, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + + + + + + +List stack events +================= + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/events + +Lists events for a stack. + + +Normal response codes: 200 +Error response codes:404,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + - resource_action: resource_action + - resource_status: resource_status + - resource_name: resource_name + - resource_type: resource_type + - limit: limit + - marker: marker + - sort_keys: sort_keys + - sort_dir: sort_dir + + + + +Response Example +---------------- + +.. literalinclude:: samples/events-list-response.json + :language: javascript + + + + + + + + +List resource events +==================== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events + +Lists events for a stack resource. + + +Normal response codes: 200 +Error response codes:404,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - resource_name: resource_name + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + - resource_action: resource_action + - resource_status: resource_status + - resource_type: resource_type + - limit: limit + - marker: marker + - sort_keys: sort_keys + - sort_dir: sort_dir + + + + +Response Example +---------------- + +.. literalinclude:: samples/events-list-response.json + :language: javascript + + + + + + diff --git a/api-ref/source/v1/stack-resources.inc b/api-ref/source/v1/stack-resources.inc new file mode 100644 index 0000000000..23f6f46f8d --- /dev/null +++ b/api-ref/source/v1/stack-resources.inc @@ -0,0 +1,191 @@ +.. -*- rst -*- + +=============== +Stack resources +=============== + + + + +Show resource metadata +====================== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/metadata + +Shows metadata for a resource. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - resource_name: resource_name + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + + + +Response Example +---------------- + +.. literalinclude:: samples/resource-metadata-response.json + :language: javascript + + + + +Show resource data +================== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name} + +Shows data for a resource. + + +Normal response codes: 200 +Error response codes:404,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - resource_name: resource_name + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - resource_name: resource_name + - resource: resource + - description: description + - logical_resource_id: logical_resource_id + - creation_time: creation_time + - resource_status: resource_status + - updated_time: updated_time + - required_by: required_by + - resource_status_reason: resource_status_reason + - physical_resource_id: physical_resource_id + - resource_type: resource_type + + + +Response Example +---------------- + +.. literalinclude:: samples/resource-show-response.json + :language: javascript + + + + + + + +List resources +============== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources + +Lists resources in a stack. + + +Normal response codes: 200 +Error response codes:404,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + - nested_depth: nested_depth + - with_detail: with_detail + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - resource_name: resource_name + - description: description + - logical_resource_id: logical_resource_id + - creation_time: creation_time + - resource_status: resource_status + - updated_time: updated_time + - required_by: required_by + - resources: resources + - resource_status_reason: resource_status_reason + - physical_resource_id: physical_resource_id + - resource_type: resource_type + + + +Response Example +---------------- + +.. literalinclude:: samples/resources-list-response.json + :language: javascript + + + + + + + +Send a signal to a resource +=========================== + +.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/signal + +Sends a signal to a resource. + +The contents of the request body depends on the resource to which +you send a signal. + +Some resources cannot receive signals. If you send them a signal, +they return a 400 error code. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - resource_name: resource_name + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + + + +Response Example +---------------- + +.. literalinclude:: + :language: javascript + + + diff --git a/api-ref/source/v1/stack-templates.inc b/api-ref/source/v1/stack-templates.inc new file mode 100644 index 0000000000..aa5e229f65 --- /dev/null +++ b/api-ref/source/v1/stack-templates.inc @@ -0,0 +1,300 @@ +.. -*- rst -*- + +========= +Templates +========= + + + + +List resource types +=================== + +.. rest_method:: GET /v1/{tenant_id}/resource_types + +Lists all supported template resource types. + + +Normal response codes: 200 +Error response codes:401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - name: name + - version: version + - support_status: support_status + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - template_versions: template_versions + - type: type + - version: version + + + +Response Example +---------------- + +.. literalinclude:: samples/resource-types-list-response.json + :language: javascript + + + + + + +List template versions +====================== + +.. rest_method:: GET /v1/{tenant_id}/template_versions + +Lists all available template versions. + + +Normal response codes: 200 +Error response codes:404,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + + + + +Response Example +---------------- + +.. literalinclude:: samples/template-versions-response.json + :language: javascript + + + + + + + + +Validate template +================= + +.. rest_method:: POST /v1/{tenant_id}/validate + +Validates a template. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - environment: environment + - template_url: template_url + - template: template + - tenant_id: tenant_id + +Request Example +--------------- + +.. literalinclude:: samples/template-validate-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - ParameterGroups: ParameterGroups + - Description: Description + - Parameters: Parameters + + + +Response Example +---------------- + +.. literalinclude:: samples/template-validate-response.json + :language: javascript + + + + +Show resource template +====================== + +.. rest_method:: GET /v1/{tenant_id}/resource_types/{type_name}/template + +Shows the template representation for a resource type. + +The returned template contains a single resource type. Each +resource property is mapped to a template parameter and each +resource attribute is mapped to a template output. + +You can use these templates as a starting place for creating +customized, template-based resources or as examples of using the +particular resource in another template. + +Use the ``template_type`` query parameter to specify the resource +template type. Default type is ``cfn``. The ``hot`` template type +is supported. For example: + +:: + + /v1/{tenant_id}/resource_types/{type_name}/template?template_type=cfn + + +Normal response codes: 200 +Error response codes:404,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - type_name: type_name + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Outputs: Outputs + - HeatTemplateFormatVersion: HeatTemplateFormatVersion + - Resources: Resources + - Parameters: Parameters + + + +Response Example +---------------- + +.. literalinclude:: samples/resource-type-template-response.json + :language: javascript + + + + + + + +Get stack template +================== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/template + +Gets a template for a stack. + + +Normal response codes: 200 +Error response codes:404,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - outputs: outputs + - heat_template_version: heat_template_version + - description: description + - parameters: parameters + - resources: resources + + + +Response Example +---------------- + +.. literalinclude:: samples/template-show-response.json + :language: javascript + + + + + + + + +Show resource schema +==================== + +.. rest_method:: GET /v1/{tenant_id}/resource_types/{type_name} + +Shows the interface schema for a resource type. + +A schema describes the properties that can be set on the resource, +their types, constraints, descriptions, and default values. +Additionally, the response shows the resource attributes and their +descriptions. + + +Normal response codes: 200 +Error response codes:401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - type_name: type_name + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - description: description + - required: required + - update_allowed: update_allowed + - support_status: support_status + - attributes: attributes + - type: type + - properties: properties + - resource_type: resource_type + + + +Response Example +---------------- + +.. literalinclude:: samples/resource-schema-response.json + :language: javascript + + + + + diff --git a/api-ref/source/v1/stacks.inc b/api-ref/source/v1/stacks.inc new file mode 100644 index 0000000000..7594698de9 --- /dev/null +++ b/api-ref/source/v1/stacks.inc @@ -0,0 +1,818 @@ +.. -*- rst -*- + +====== +Stacks +====== + + + + +Abandon stack +============= + +.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/abandon + +Deletes a stack but leaves its resources intact, and returns data that describes the stack and its resources. + +This method can be disabled from the server side. If it is +disabled, this call throws an exception. + + +Normal response codes: 200 +Error response codes:404,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-abandon-response.json + :language: javascript + + + + + + + + +Show snapshot +============= + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id} + +Shows details for a snapshot. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + - snapshot_id: snapshot_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - name: name + - status_reason: status_reason + - creation_time: creation_time + - snapshot: snapshot + - template: template + - project_id: project_id + - data: data + - id: id + - resources: resources + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-show-snapshot-response.json + :language: javascript + + + + +Delete snapshot +=============== + +.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id} + +Deletes a stack snapshot. + +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + - snapshot_id: snapshot_id + + + + + + +Preview stack +============= + +.. rest_method:: POST /v1/{tenant_id}/stacks/preview + +Previews a stack. + + +Normal response codes: 200 +Error response codes:500,409,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - files: files + - stack_name: stack_name + - template_url: template_url + - template: template + - parameters: parameters + - tenant_id: tenant_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-create-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - parent: parent + - disable_rollback: disable_rollback + - description: description + - links: links + - stack_name: stack_name + - timeout_mins: timeout_mins + - creation_time: creation_time + - capabilities: capabilities + - notification_topics: notification_topics + - updated_time: updated_time + - stack_owner: stack_owner + - stack: stack + - parameters: parameters + - id: id + - resources: resources + - template_description: template_description + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-preview-response.json + :language: javascript + + + + + + + + +Restore snapshot +================ + +.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}/restore + +Restores a stack snapshot. + +You can restore only active stacks from a snapshot. You must +recreate deleted stacks. + +Error response codes:202, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + - snapshot_id: snapshot_id + + + + + + +List outputs +============ + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs + +Lists outputs for a stack. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - output_value: output_value + - output_error: output_error + - description: description + - output_key: output_key + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-outputs-list-response.json + :language: javascript + + + + +Preview stack update +==================== + +.. rest_method:: PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/preview + +Previews an update for a stack. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - files: files + - parameters: parameters + - tags: tags + - environment: environment + - template_url: template_url + - template: template + - timeout_mins: timeout_mins + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-update-request.json + :language: javascript + + + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-update-preview-response.json + :language: javascript + + + + +Find stack resources +==================== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/resources + +Finds the canonical URL for a resource list of a stack. + +The canonical URL is returned for only non-deleted stacks. To fetch +the resource list for deleted stacks, use the following endpoint: + +:: + + /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources + +Error response codes:302, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + + + + + + +Show stack details +================== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id} + +Shows details for a stack. + + +Normal response codes: 200 +Error response codes:404,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - parent: parent + - updated_time: updated_time + - description: description + - links: links + - stack_status_reason: stack_status_reason + - stack_name: stack_name + - outputs: outputs + - tags: tags + - creation_time: creation_time + - capabilities: capabilities + - notification_topics: notification_topics + - timeout_mins: timeout_mins + - stack_owner: stack_owner + - stack_status: stack_status + - stack: stack + - parameters: parameters + - id: id + - stack_user_project_id: stack_user_project_id + - template_description: template_description + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-show-response.json + :language: javascript + + + + + + + + +Update stack +============ + +.. rest_method:: PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id} + +Updates a stack. + +Error response codes:404,202,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - files: files + - disable_rollback: disable_rollback + - parameters: parameters + - tags: tags + - environment: environment + - template_url: template_url + - template: template + - timeout_mins: timeout_mins + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-update-request.json + :language: javascript + + + + + + + + + + + +Delete stack +============ + +.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id} + +Deletes a stack and its snapshots. + +Error response codes:500,404,204,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + + + + + + + + + +Show output +=========== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs/{output_key} + +Shows details for a stack output. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + - output_key: output_key + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - output_value: output_value + - output_error: output_error + - description: description + - output_key: output_key + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-show-output-response.json + :language: javascript + + + + +List stack data +=============== + +.. rest_method:: GET /v1/{tenant_id}/stacks + +Lists active stacks. + + +Normal response codes: 200 +Error response codes:500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - id: id + - status: status + - name: name + - action: action + - tenant: tenant + - username: username + - owner_id: owner_id + - limit: limit + - marker: marker + - show_deleted: show_deleted + - show_nested: show_nested + - sort_keys: sort_keys + - tags: tags + - tags_any: tags_any + - not_tags: not_tags + - not_tags_any: not_tags_any + - sort_dir: sort_dir + - global_tenant: global_tenant + - with_count: with_count + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - description: description + - links: links + - stack_status_reason: stack_status_reason + - stack_name: stack_name + - tags: tags + - creation_time: creation_time + - updated_time: updated_time + - stack_status: stack_status + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/stacks-list-response.json + :language: javascript + + + + + + + +Create stack +============ + +.. rest_method:: POST /v1/{tenant_id}/stacks + +Creates a stack. + +Error response codes:201,500,409,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - files: files + - disable_rollback: disable_rollback + - parameters: parameters + - tags: tags + - stack_name: stack_name + - environment: environment + - template_url: template_url + - template: template + - timeout_mins: timeout_mins + - tenant_id: tenant_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-create-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: id + - links: links + - stack: stack + + + + + + + + + +Adopt stack +=========== + +.. rest_method:: POST /v1/{tenant_id}/stacks + +Creates a stack from existing resources. + +Error response codes:201,500,409,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - files: files + - disable_rollback: disable_rollback + - parameters: parameters + - stack_name: stack_name + - adopt_stack_data: adopt_stack_data + - environment: environment + - timeout_mins: timeout_mins + - tenant_id: tenant_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-adopt-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: id + - links: links + - stack: stack + + + + + + + + + +Find stack +========== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name} + +Finds the canonical URL for a stack. + +Also works with verbs other than GET , so that you can perform PUT +and DELETE operations on a current stack. Set your client to follow +redirects. When redirecting, the request method should not change +as defined in RFC2626. However, in many clients the default +behavior is to change the method to GET when you receive a ``302`` +response code because this behavior is ubiquitous in web browsers. + +Error response codes:302,404,500,401,400, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + + + + + + + + + + +Snapshot stack +============== + +.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots + +Takes a snapshot of all resources in a stack. All snapshots are deleted when the stack is deleted. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - name: name + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + +Request Example +--------------- + +.. literalinclude:: samples/stack-snapshot-request.json + :language: javascript + + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - name: name + - status_reason: status_reason + - creation_time: creation_time + - data: data + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-snapshot-response.json + :language: javascript + + + + +List snapshots +============== + +.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots + +Lists snapshots for a stack. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - stack_name: stack_name + - tenant_id: tenant_id + - stack_id: stack_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - status: status + - name: name + - status_reason: status_reason + - creation_time: creation_time + - snapshots: snapshots + - data: data + - id: id + + + +Response Example +---------------- + +.. literalinclude:: samples/stack-snapshots-list-response.json + :language: javascript + + + diff --git a/tox.ini b/tox.ini index 5ccef4a9fd..4e01b56e33 100644 --- a/tox.ini +++ b/tox.ini @@ -54,6 +54,24 @@ deps = -r{toxinidir}/requirements.txt sphinxcontrib-httpdomain commands = python setup.py build_sphinx +[testenv:api-ref] +# This environment is called from CI scripts to test and publish +# the API Ref to developer.openstack.org. +# +# NOTE(sdague): this target does not use constraints because +# upstream infra does not yet support it. Once that's fixed, we can +# drop the install_command. +# +# we do not used -W here because we are doing some slightly tricky +# things to build a single page document, and as such, we are ok +# ignoring the duplicate stanzas warning. +whitelist_externals = bash + rm +install_command = pip install -U --force-reinstall {opts} {packages} +commands = + rm -rf api-ref/build + sphinx-build -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html + [testenv:genconfig] commands = oslo-config-generator --config-file=config-generator.conf