From cb4075048f6b4551b65b581633dc67b9ed5e6167 Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Fri, 18 Jul 2014 17:25:02 +0200 Subject: [PATCH] Includes a basic HOT template guide The 2 RST files are copied from the heat developer documentation without any change and are just a starting point. This patch requires this change in the openstack-doc-tools: https://review.openstack.org/#/c/108034/ Change-Id: I03511655c86ead880cadfa68b43bb2b90d3f7c06 Implements: blueprint heat-templates --- .gitignore | 1 + doc/hot-guide/Makefile | 182 +++++++ doc/hot-guide/pom.xml | 81 +++ doc/hot-guide/source/conf.py | 256 +++++++++ doc/hot-guide/source/hot_guide.rst | 230 ++++++++ doc/hot-guide/source/hot_spec.rst | 834 +++++++++++++++++++++++++++++ doc/hot-guide/source/index.rst | 8 + test-requirements.txt | 2 + 8 files changed, 1594 insertions(+) create mode 100644 doc/hot-guide/Makefile create mode 100644 doc/hot-guide/pom.xml create mode 100644 doc/hot-guide/source/conf.py create mode 100644 doc/hot-guide/source/hot_guide.rst create mode 100644 doc/hot-guide/source/hot_spec.rst create mode 100644 doc/hot-guide/source/index.rst diff --git a/.gitignore b/.gitignore index b15c15c4f8..10db7d3920 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ target/ /publish-docs/ /generated/ +build/ /build-*.log.gz # Ignore Vagrant Related Files diff --git a/doc/hot-guide/Makefile b/doc/hot-guide/Makefile new file mode 100644 index 0000000000..98daf30162 --- /dev/null +++ b/doc/hot-guide/Makefile @@ -0,0 +1,182 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/HOTTemplatesGuide.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/HOTTemplatesGuide.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/HOTTemplatesGuide" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/HOTTemplatesGuide" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The xml files are in $(BUILDDIR)/xml." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/hot-guide/pom.xml b/doc/hot-guide/pom.xml new file mode 100644 index 0000000000..fe83b8f5bd --- /dev/null +++ b/doc/hot-guide/pom.xml @@ -0,0 +1,81 @@ + + + + org.openstack.docs + parent-pom + 1.0.0-SNAPSHOT + ../pom.xml + + 4.0.0 + openstack-hot-guide + jar + OpenStack HOT templates guide + + + local + 0 + + + + + + + + com.rackspace.cloud.api + clouddocs-maven-plugin + + + + generate-webhelp + + generate-webhelp + + generate-sources + + + 0 + os-hot-guide + 1 + UA-17511903-1 + + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + chapter toc + section toc + part toc + preface toc + qandadiv toc + qandaset toc + reference toc,title + set toc,title + + + 0 + 0 + 1 + 1 + 0 + hot-guide + hot-guide + + + + + + enduser + true + . + + build/docbook/index.xml + + openstack + http://docs.openstack.org/hot-guide/content + + + + + diff --git a/doc/hot-guide/source/conf.py b/doc/hot-guide/source/conf.py new file mode 100644 index 0000000000..6b2f72426f --- /dev/null +++ b/doc/hot-guide/source/conf.py @@ -0,0 +1,256 @@ +# HOT Templates Guide documentation build configuration file, created by +# sphinx-quickstart on Fri Jul 18 15:27:11 2014. +# +# 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 sys +import os + +# 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('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['oslosphinx'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'HOT guide' +copyright = u'2014, OpenStack Doc Team' + +# 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. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# 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' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# 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 = True + +# 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' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# html_theme = 'default' + +# 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# 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' + +# 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_domain_indices = 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, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = 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 = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'HOTguidedoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'HOTguide.tex', u'HOT guide', + u'OpenStack Doc Team', '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 + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'hotguide', u'HOT Guide', + [u'OpenStack Doc Team'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'HOTguide', u'HOT guide', + u'OpenStack Doc Team', 'HOTguide', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/doc/hot-guide/source/hot_guide.rst b/doc/hot-guide/source/hot_guide.rst new file mode 100644 index 0000000000..2c2816223b --- /dev/null +++ b/doc/hot-guide/source/hot_guide.rst @@ -0,0 +1,230 @@ +.. + 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. + +.. _hot_guide: + +======================================= +Heat Orchestration Template (HOT) Guide +======================================= + +HOT is a new template format meant to replace the Heat CloudFormation-compatible +format (CFN) as the native format supported by the Heat over time. +This guide is targeted towards template authors and explains how to write +HOT templates based on examples. A detailed specification of HOT can be found +at :ref:`hot_spec`. + +------ +Status +------ + +HOT support is still under development and needs more work to provide access to +all functionality currently available via the CFN compatible template interface. +This guide will be updated periodically whenever new features get implemented +for HOT. + +---------------------------------- +Writing a hello world HOT template +---------------------------------- + +This section gives an introduction on how to write HOT templates, starting from +very basic steps and then going into more and more detail by means of examples. + +A most basic template +--------------------- +The most basic template you can think of may contain only a single resource +definition using only predefined properties (along with the mandatory Heat +template version tag). For example, the template below could be used to simply +deploy a single compute instance. + +:: + + heat_template_version: 2013-05-23 + + description: Simple template to deploy a single compute instance + + resources: + my_instance: + type: OS::Nova::Server + properties: + key_name: my_key + image: F18-x86_64-cfntools + flavor: m1.small + +Each HOT template has to include the *heat_template_version* key with value +'2013-05-23' (the current version of HOT). While the *description* is optional, +it is good practice to include some useful text that describes what users can do +with the template. In case you want to provide a longer description that does +not fit on a single line, you can provide multi-line text in YAML, for example: + +:: + + description: > + This is how you can provide a longer description + of your template that goes over several lines. + +The *resources* section is required and must contain at least one resource +definition. In the example above, a compute instance is defined with fixed +values for the 'key_name', 'image' and 'flavor' parameters. + +Note that all those elements, i.e. a key-pair with the given name, the image and +the flavor have to exist in the OpenStack environment where the template is +used. Typically a template is made more easily reusable, though, by defining a +set of *input parameters* instead of hard-coding such values. + + +Template input parameters +------------------------- +Input parameters defined in the *parameters* section of a HOT template (see also +:ref:`hot_spec_parameters`) allow users to customize a template during +deployment. For example, this allows for providing custom key-pair names or +image IDs to be used for a deployment. +From a template author's perspective, this helps to make a template more easily +reusable by avoiding hardcoded assumptions. + +Sticking to the example used above, it makes sense to allow users to provide +their custom key-pairs, provide their own image, and to select a flavor for the +compute instance. This can be achieved by extending the initial template as +follows: + +:: + + heat_template_version: 2013-05-23 + + description: Simple template to deploy a single compute instance + + parameters: + key_name: + type: string + label: Key Name + description: Name of key-pair to be used for compute instance + image_id: + type: string + label: Image ID + description: Image to be used for compute instance + instance_type: + type: string + label: Instance Type + description: Type of instance (flavor) to be used + + resources: + my_instance: + type: OS::Nova::Server + properties: + key_name: { get_param: key_name } + image: { get_param: image_id } + flavor: { get_param: instance_type } + +In the example above, three input parameters have been defined that have to be +provided by the user upon deployment. The fixed values for the respective +resource properties have been replaced by references to the corresponding +input parameters by means of the *get_param* function (see also +:ref:`hot_spec_intrinsic_functions`). + +You can also define default values for input parameters which will be used in +case the user does not provide the respective parameter during deployment. For +example, the following definition for the *instance_type* parameter would select +the 'm1.small' flavor unless specified otherwise by the user. + +:: + + parameters: + instance_type: + type: string + label: Instance Type + description: Type of instance (flavor) to be used + default: m1.small + +Another option that can be specified for a parameter is to hide its value when +users request information about a stack deployed from a template. This is +achieved by the *hidden* attribute and useful, for example when requesting +passwords as user input: + +:: + + parameters: + database_password: + type: string + label: Database Password + description: Password to be used for database + hidden: true + + +Restricting user input +~~~~~~~~~~~~~~~~~~~~~~ +In some cases you might want to restrict the values of input parameters that +users can supply. For example, you might know that the software running in a +compute instance needs a certain amount of resources so you might want to +restrict the *instance_type* parameter introduced above. Parameters in HOT +templates can be restricted by adding a *constraints* section (see also +:ref:`hot_spec_parameters_constraints`). +For example, the following would allow only three values to be provided as input +for the *instance_type* parameter: + +:: + + parameters: + instance_type: + type: string + label: Instance Type + description: Type of instance (flavor) to be used + constraints: + - allow_values: [ m1.medium, m1.large, m1.xlarge ] + description: Value must be one of m1.medium, m1.large or m1.xlarge. + +The *constraints* section allows for defining a list of constraints that must +all be fulfilled by user input. For example, the following list of constraints +could be used to clearly specify format requirements on a password to be +provided by users: + +:: + + parameters: + database_password: + type: string + label: Database Password + description: Password to be used for database + hidden: true + constraints: + - length: { min: 6, max: 8 } + description: Password length must be between 6 and 8 characters. + - allowed_pattern: "[a-zA-Z0-9]+" + description: Password must consist of characters and numbers only. + - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*" + description: Password must start with an uppercase character. + +Note that you can define multiple constraints of the same type. Especially in +the case of allowed patterns this not only allows for keeping regular +expressions simple and maintainable, but also for keeping error messages to be +presented to users precise. + + +Providing template outputs +-------------------------- +In addition to template customization through input parameters, you will +typically want to provide outputs to users, which can be done in the +*outputs* section of a template (see also :ref:`hot_spec_outputs`). +For example, the IP address by which the instance defined in the example +above can be accessed should be provided to users. Otherwise, users would have +to look it up themselves. The definition for providing the IP address of the +compute instance as an output is shown in the following snippet: + +:: + + outputs: + instance_ip: + description: The IP address of the deployed instance + value: { get_attr: [my_instance, first_address] } + +Output values are typically resolved using intrinsic function such as +the *get_attr* function in the example above (see also +:ref:`hot_spec_intrinsic_functions`). diff --git a/doc/hot-guide/source/hot_spec.rst b/doc/hot-guide/source/hot_spec.rst new file mode 100644 index 0000000000..a5ce5acbc6 --- /dev/null +++ b/doc/hot-guide/source/hot_spec.rst @@ -0,0 +1,834 @@ +.. + 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. + +.. _hot_spec: + +=============================================== +Heat Orchestration Template (HOT) Specification +=============================================== + +HOT is a new template format meant to replace the Heat CloudFormation-compatible +format (CFN) as the native format supported by the Heat over time. +This specification explains in detail all elements of the HOT template format. +An example driven guide to writing HOT templates can be found +at :ref:`hot_guide`. + +------ +Status +------ + +HOT is considered reliable, supported, and standardized as of our +Icehouse (April 2014) release. The Heat core team may make improvements +to the standard, which very likely would be backward compatible. The template +format is also versioned. In our Juno release, Heat will support multiple +different versions of the HOT specification if there is a need driven by the +introduction of new features. + + +------------------ +Template Structure +------------------ + +HOT templates are defined in YAML and follow the structure outlined below. + +:: + + heat_template_version: 2013-05-23 + + description: + # a description of the template + + parameter_groups: + # a declaration of input parameter groups and order + + parameters: + # declaration of input parameters + + resources: + # declaration of template resources + + outputs: + # declaration of output parameters + +heat_template_version + This key with value *2013-05-23* (or a later date) indicates that the YAML + document is a HOT template of the specified version. + +description + This *optional* key allows for giving a description of the template, or the + workload that can be deployed using the template. + +parameter_groups + This section allows for specifying how the input parameters should be + grouped and the order to provide the parameters in. This section is + *optional* and can be omitted when necessary. + +parameters + This section allows for specifying input parameters that have to be provided + when instantiating the template. The section is *optional* and can be + omitted when no input is required. + +resources + This section contains the declaration of the single resources of the + template. This section with at least one resource should be defined in any + HOT template, or the template would not really do anything when being + instantiated. + +outputs + This section allows for specifying output parameters available to users once + the template has been instantiated. This section is *optional* and can be + omitted when no output values are required. + + +.. _hot_spec_parameter_groups: + +------------------------ +Parameter Groups Section +------------------------ + +The *parameter_groups* section allows for specifying how the input parameters +should be grouped and the order to provide the parameters in. These groups are +typically used to describe expected behavior for downstream user interfaces. + +These groups are specified in a list with each group containing a list of +associated parameters. The lists are used to denote the expected order of the +parameters. Each parameter should be associated to a specific group only once +using the parameter name to bind it to a defined parameter in the parameters +section. + +:: + + parameter_groups: + - label: + description: + parameters: + - + - + +label + A human-readable label that defines the associated group of parameters. + +description + This attribute allows for giving a human-readable description of the + parameter group. + +parameters + A list of parameters associated with this parameter group. + +param name + The name of the parameter that is defined in the associated parameters + section. + + +.. _hot_spec_parameters: + +------------------ +Parameters Section +------------------ + +The *parameters* section allows for specifying input parameters that have to be +provided when instantiating the template. Such parameters are typically used to +customize each deployment (e.g. by setting custom user names or passwords) or +for binding to environment-specifics like certain images. + +Each parameter is specified in a separated nested block with the name of the +parameters defined in the first line and additional attributes such as type or +default value defined as nested elements. + +:: + + parameters: + : + type: + label: + description: + default: + hidden: + constraints: + + +param name + The name of the parameter is defined at the top of each parameter block. + +type + This attribute specifies the type of parameter. Currently supported types + are *string*, *number*, *comma_delimited_list*, *json*, or *boolean*. + +label + This *optional* attribute allows for giving a human readable name of the + parameter. + +description + This *optional* attribute allows for giving a human readable description of + the parameter. + +default + This *optional* attribute allows for defining a default value for the + parameters which will be used in case the parameter is not specified by the + user during deployment. + +hidden + This *optional* attribute allows for specifying whether the parameters + should be hidden when showing information about a stack created from the + template at runtime (e.g. for hiding passwords that were specified as + parameters). If not specified, the default value 'false' will be used. + +constraints + This *optional* block allows for specifying additional constraints on the + parameter, such as minimum or maximum values for numeric parameters. + +The following example shows a minimalistic definition of two parameters. Note +that the description and label are actually optional, but is good practice to +provide a useful description and label for each parameter. + +:: + + parameters: + user_name: + type: string + label: User Name + description: User name to be configured for the application + port_number: + type: number + label: Port Number + description: Port number to be configured for the web server + + +.. _hot_spec_parameters_constraints: + +Parameter Constraints +--------------------- + +The *constraints* block of a parameter definition allows for defining additional +validation constraints that apply to the value of the parameter. At +instantiation time of the template, user provided parameter values are validated +against those constraints to make sure the provided values match expectations of +the template author. +Constraints are defined in the form of a bulleted list according to the +following syntax: + +:: + + constraints: + - : + description: + +constraint type + The constraint type specifies the kind of constraint defined in the current + bulleted list item. The set of currently supported constraints is given + below. + +constraint definition + This value defines the actual constraint, depending on the constraint type. + The concrete syntax for each constraint type is given below. + +description + This *optional* attribute allows for specifying a concrete description of + the current constraint. This text will be presented to the user, for + example, when the provided input value for a parameter violates the + constraint. If omitted, a default validation message will be presented to + the user. + +The following example show the definition of a string parameter with two +constraints. Note that while the descriptions for each constraint are optional, +it is good practice to provide concrete descriptions so useful messages can be +presented to the user at deployment time. + +:: + + parameters: + user_name: + type: string + label: User Name + description: User name to be configured for the application + constraints: + - length: { min: 6, max: 8 } + description: User name must be between 6 and 8 characters + - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*" + description: User name must start with an uppercase character + +The following sections list the supported types of parameter constraints, along +with the concrete syntax for each type. + +length +~~~~~~ +The *length* constraint applies to parameters of type *string* and allows for +defining a lower and upper limit for the length of the string value. The syntax +for the length constraint is: + +:: + + length: { min: , max: } + +It is possible to define a length constraint with only a lower limit or an +upper limit. However, at least one of *min* or *max* must be specified. + +range +~~~~~ +The *range* constraint applies to parameters of type *number* and allows for +defining a lower and upper limit for the numeric value of the parameter. The +syntax of the range constraint is: + +:: + + range: { min: , max: } + +It is possible to define a range constraint with only a lower limit or an +upper limit. However, at least one of *min* or *max* must be specified. +The minimum or maximum boundaries are included in the range. For example, the +following range constraint would allow for all numeric values between 0 and 10. + +:: + + range: { min: 0, max: 10 } + + +allowed_values +~~~~~~~~~~~~~~ +The *allowed_values* constraint applies to parameters of type string or number +and allows for specifying a set of possible values for a parameter. At +deployment time, the user provided value for the respective parameter must +match one of the elements of the specified list. The syntax of the +allowed_values constraint is: + +:: + + allowed_values: [ , , ... ] + +Alternatively, the YAML bulleted list notation can be used: + +:: + + allowed_values: + - + - + - ... + +For example: + +:: + + parameters: + instance_type: + type: string + label: Instance Type + description: Instance type for compute instances + constraints: + - allowed_values: + - m1.small + - m1.medium + - m1.large + +allowed_pattern +~~~~~~~~~~~~~~~ +The *allowed_pattern* constraint applies to parameters of type string and allows +for specifying a regular expression against which a user provided parameter +value must evaluate at deployment. +The syntax of the allowed_pattern constraint is: + +:: + + allowed_pattern: + +For example: + +:: + + parameters: + user_name: + type: string + label: User Name + description: User name to be configured for the application + constraints: + - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*" + description: User name must start with an uppercase character + + +custom_constraint +~~~~~~~~~~~~~~~~~ +The *custom_constraint* constraint adds an extra step of validation, generally +to check that the specified resource exists in the backend. Custom constraints +get implemented by plug-ins and can provide any kind of advanced constraint +validation logic. + +The syntax of the custom_constraint constraint is: + +:: + + custom_constraint: + +The *name* specifies the concrete type of custom constraint. It corresponds to +the name under which the respective validation plugin has been registered with +the Heat engine. + +For example: + +:: + + parameters: + key_name + type: string + description: SSH key pair + constraints: + - custom_constraint: nova.keypair + +.. _hot_spec_pseudo_parameters + +Pseudo Parameters +----------------- + +In addition to parameters defined by a template author, Heat also creates two +parameters for every stack that allow referential access to the stack's name +and identifier. These parameters are named ``OS::stack_name`` for the stack +name and ``OS::stack_id`` for the stack identifier. These values are accessible +via the `get_param`_ intrinsic function just like user-defined parameters. + +.. _hot_spec_resources: + +----------------- +Resources Section +----------------- + +In the *resources* section, the templates for actual resources that will make up +a stack deployed from the HOT template (e.g. compute instances, networks, +storage volumes) are defined. +Each resource is defined as a separate block in the resources section according +to the syntax below. + +:: + + resources: + : + type: + properties: + : + metadata: + + depends_on: + update_policy: + deletion_policy: + +resource ID + A resource block is headed by the resource ID, which must be unique within + the resource section of a template. +type + This attribute specifies the type of resource, such as OS::Nova::Server. +properties + This *optional* section contains a list of resource specific properties. + The property value can be provided in place, or can be provided via a + function (see :ref:`hot_spec_intrinsic_functions`). +metadata + This *optional* section contains resource type specific metadata. +depends_on + This *optional* attribute allows for specifying dependencies of the current + resource on one or more other resources. Please refer to section + :ref:`hot_spec_resources_dependencies` for details. +update_policy: + This *optional* attribute allows for specifying an update policy for the + resource in the form of a nested dictionary (name-value pairs). Whether + update policies are supported and what the exact semantics are depends on + the type of the current resource. +deletion_policy: + This *optional* attribute allows for specifying a deletion policy for the + resource (one of the values Delete, Retain or Snapshot). Which type of + deletion policy is supported depends on the type of the current resource. + + +Depending on the type of resource, the resource block might include more +resource specific data. Basically all resource types that can be used in +CFN templates can also be used in HOT templates, adapted to the YAML structure +as outlined above. +Below is an example of a simple compute resource definition with some fixed +property values. + +:: + + resources: + my_instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: F18-x86_64-cfntools + + +.. _hot_spec_resources_dependencies: + +Resource Dependencies +--------------------- + +By means of the *depends_on* attribute within a resource section it is possible +to define a dependency between a resource and one or more other resources. If +a resource depends on just one other resource, the ID of the other resource is +specified as value of the *depends_on* attribute as shown in the following +example. + +:: + + resources: + server1: + type: OS::Nova::Server + depends_on: server2 + + server2: + type: OS::Nova::Server + +If a resource depends on more than one other resource, the value of the +*depends_on* attribute is specified as a list of resource IDs as shown in the +following example: + +:: + + resources: + server1: + type: OS::Nova::Server + depends_on: [ server2, server3 ] + + server2: + type: OS::Nova::Server + + server3: + type: OS::Nova::Server + + +.. _hot_spec_outputs: + +--------------- +Outputs Section +--------------- + +In the *outputs* section, any output parameters that should be available to the +user can be defined. Typically, this would be, for example, parameters such as +IP addresses of deployed instances, or URLs of web applications deployed as part +of a stack. + +Each output parameter is defined as a separate block within the outputs section +according to the following syntax: + +:: + + outputs: + : + description: + value: + +parameter name + An output parameter block is headed by the output parameter name, which must + be unique within the outputs section of a template. +description + This element gives a short description of the output parameter. +parameter value + This element specifies the value of the output parameter. Typically, this + will be resolved by means of a function, e.g. by getting an attribute value + of one of the stack's resources (see also + :ref:`hot_spec_intrinsic_functions`). + +The example below shows, how the IP address of a compute resource can be defined +as an output parameter. + +:: + + outputs: + instance_ip: + description: IP address of the deployed compute instance + value: { get_attr: [my_instance, first_address] } + + +.. _hot_spec_intrinsic_functions: + +------------------- +Intrinsic Functions +------------------- +HOT provides a set of intrinsic functions that can be used inside HOT templates +to perform specific tasks, such as getting the value of a resource attribute at +runtime. A definition of all intrinsic functions available in HOT is given +below. + + +get_attr +-------- +The *get_attr* function allows referencing an attribute of a resource. At +runtime, it will be resolved to the value of an attribute of a resource instance +created from the respective resource definition of the template. +The syntax of the get_attr function is as follows: + +:: + + get_attr: + - + - + - (optional) + - (optional) + - ... + +resource ID + This parameter specifies the resource for which the attributes shall be + resolved. This resource must be defined within the *resources* section of + the template (see also :ref:`hot_spec_resources`). +attribute name + The attribute name is required as it specifies the attribute + to be resolved. If the attribute returns a complex data structure + such as a list or a map, then subsequent keys or indexes can be specified + which navigate the data structure to return the desired value. + +Some examples of how to use the get_attr function are shown below: + +:: + + resources: + my_instance: + type: OS::Nova::Server + # ... + + outputs: + instance_ip: + description: IP address of the deployed compute instance + value: { get_attr: [my_instance, first_address] } + instance_private_ip: + description: Private IP address of the deployed compute instance + value: { get_attr: [my_instance, networks, private, 0] } + +In this example, if the networks attribute contained the following data: + +:: + + {"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"], + "private": ["10.0.0.1"]} + +then the value of the get_attr function would resolve to "10.0.0.1". + + +get_file +------------ +The *get_file* function allows string content to be substituted into the +template. It is generally used as a file inclusion mechanism for files +containing non-heat scripts or configuration files. +The syntax of the get_file function is as follows: + +:: + + get_file: + +The *content key* will be used to look up the files dictionary that is +provided in the REST API call. The *heat* client command from +python-heatclient is *get_file* aware and will populate the *files* with +the actual content of fetched paths and URLs. The *heat* client command +supports relative paths and will transform these to absolute URLs which +will be used as the *content key* in the files dictionary. + +Note: The argument to *get_file* should be a static path or URL and not +rely on intrinsic functions like *get_param*. In general, the *heat* client +does not process intrinsic functions (they are only processed by the heat +server). + +The example below demonstrates *get_file* usage with both relative and +absolute URLs. + +:: + + resources: + my_instance: + type: OS::Nova::Server + properties: + # general properties ... + user_data: + get_file: my_instance_user_data.sh + my_other_instance: + type: OS::Nova::Server + properties: + # general properties ... + user_data: + get_file: http://example.com/my_other_instance_user_data.sh + +If this template was launched from a local file this would result in +a *files* dictionary containing entries with keys +*file:///path/to/my_instance_user_data.sh* and +*http://example.com/my_other_instance_user_data.sh*. + + +get_param +--------- +The *get_param* function allows for referencing an input parameter of a template +from anywhere within a template. At runtime, it will be resolved to the value +provided for this input parameter. The syntax of the get_param function is as +follows: + +:: + + get_param: + - + - (optional) + - (optional) + - ... + +parameter name + The parameter name is required as it specifies the parameter + to be resolved. If the parameter returns a complex data structure + such as a list or a map, then subsequent keys or indexes can be specified + which navigate the data structure to return the desired value. + +A sample use of this function in context of a resource definition +is shown below. + +:: + + parameters: + instance_type: + type: string + label: Instance Type + description: Instance type to be used. + server_data: + type: json + + resources: + my_instance: + type: OS::Nova::Server + properties: + flavor: { get_param: instance_type} + metadata: { get_param: [ server_data, metadata ] } + key_name: { get_param: [ server_data, keys, 0 ] } + + +In this example, if the instance_type/server_data parameters contained +the following data: + +:: + + {"instance_type": "m1.tiny", + {"server_data": {"metadata": {"foo": "bar"}, + "keys": ["a_key","other_key"]}}} + +then the value of the property 'flavor' would resolve to "m1.tiny", 'metadata' +would resolve to {"foo": "bar"} and 'key_name' would resolve to "a_key". + +get_resource +------------ +The *get_resource* function allows for referencing another resource within the +same template. At runtime, it will be resolved to reference ID of the resource, +which is resource type specific. For example, a reference to a floating IP +resource will return the respective IP address at runtime. +The syntax of the get_resource function is as follows: + +:: + + get_resource: + +The *resource ID* of the referenced resources as used in the current template is +given as single parameter to the get_resource function. + + +list_join +-------- +The *list_join* function joins a list of strings with the given delimiter. +The syntax of the list_join function is as follows: + +:: + + list_join: + - + - + +A sample use of this function with a simple list is shown below. + +:: + + list_join: [', ', ['one', 'two', 'and three']] + +This would resolve to "one, two, and three". + + +resource_facade +--------------- +The *resource_facade* function allows a provider template to retrieve data +about its resource facade in the parent template. (A provider template is used to provide a custom definition of a resource - the facade - in the form of a Heat template. The resource's properties are passed to the provider template as its parameters, but other resource data can be included using this function.) +The syntax of the *resource_facade* function is as follows:: + + resource_facade: + +The *data type* can be `metadata`, `deletion_policy` or `update_policy`. + + +str_replace +----------- +The *str_replace* function allows for dynamically constructing strings by +providing a template string with placeholders and a list of mappings to assign +values to those placeholders at runtime. The placeholders are replaced with +mapping values wherever a mapping key exactly matches a placeholder. +The syntax of the str_replace function is as follows: + +:: + + str_replace: + template: