openstack/openstack-manuals
Code Issues Proposed changes

Includes a basic HOT template guide

Browse Source 
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
This commit is contained in:
Gauvain Pocentek 2014-07-18 17:25:02 +02:00
parent eb749ef0db
commit cb4075048f
8 changed files with 1594 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -6,6 +6,7 @@
target/
/publish-docs/
/generated/
build/
/build-*.log.gz
# Ignore Vagrant Related Files

182
doc/hot-guide/Makefile Normal file
View File

@ -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 <target>' where <target> 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."

81
doc/hot-guide/pom.xml Normal file
View File

@ -0,0 +1,81 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>org.openstack.docs</groupId>
<artifactId>parent-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>openstack-hot-guide</artifactId>
<packaging>jar</packaging>
<name>OpenStack HOT templates guide</name>
<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name>local</release.path.name>
<comments.enabled>0</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<!-- version is set in ../pom.xml file -->
<executions>
<execution>
<id>generate-webhelp</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<enableDisqus>0</enableDisqus>
<disqusShortname>os-hot-guide</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<generateToc>
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
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>0</sectionAutolabel>
<formalProcedures>0</formalProcedures>
<tocSectionDepth>1</tocSectionDepth>
<tocChapterDepth>1</tocChapterDepth>
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
<webhelpDirname>hot-guide</webhelpDirname>
<pdfFilenameBase>hot-guide</pdfFilenameBase>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<profileAudience>enduser</profileAudience>
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>.</sourceDirectory>
<includes>
build/docbook/index.xml
</includes>
<branding>openstack</branding>
<canonicalUrlBase>http://docs.openstack.org/hot-guide/content</canonicalUrlBase>
</configuration>
</plugin>
</plugins>
</build>
</project>

256
doc/hot-guide/source/conf.py Normal file
View File

@ -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
# "<project> v<release> 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 <link> 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

230
doc/hot-guide/source/hot_guide.rst Normal file
View File

@ -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`).

834
doc/hot-guide/source/hot_spec.rst Normal file
View File

@ -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: <human-readable label of parameter group>
description: <description of the parameter group>
parameters:
- <param name>
- <param name>
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:
<param name>:
type: <string | number | json | comma_delimited_list | boolean>
label: <human-readable name of the parameter>
description: <description of the parameter>
default: <default value for parameter>
hidden: <true | false>
constraints:
<parameter 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:
- <constraint type>: <constraint definition>
description: <constraint 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: <lower limit>, max: <upper limit> }
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: <lower limit>, max: <upper limit> }
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: [ <value>, <value>, ... ]
Alternatively, the YAML bulleted list notation can be used:
::
allowed_values:
- <value>
- <value>
- ...
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: <regular expression>
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: <name>
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:
<resource ID>:
type: <resource type>
properties:
<property name>: <property value>
metadata:
<resource specific metadata>
depends_on: <resource ID or list of ID>
update_policy: <update policy>
deletion_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:
<parameter name>:
description: <description>
value: <parameter 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:
- <resource ID>
- <attribute name>
- <key/index 1> (optional)
- <key/index 2> (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: <content key>
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:
- <parameter name>
- <key/index 1> (optional)
- <key/index 2> (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: <resource ID>
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:
- <delimiter>
- <list to 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: <data type>
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: <template string>
params: <parameter mappings>
template
The *template* argument defines the template string that contains
placeholders which will be substituted at runtime.
params
The *params* argument provides parameter mappings in the form of a
dictionary, which will be used for placeholder substitution in the template
string at runtime. Within parameter mappings one can make use of other
functions (e.g. get_attr to use resource attribute values) for template
substitution.
The example below shows a simple use of the str_replace function in the outputs
section of a template to build a URL for logging into a deployed application.
::
resources:
my_instance:
type: OS::Nova::Server
# general metadata and properties ...
outputs:
Login_URL:
description: The URL to log into the deployed application
value:
str_replace:
template: http://host/MyApplication
params:
host: { get_attr: [ my_instance, first_address ] }
The str_replace function can also be used for constructing bigger chunks of text
like scripts for initializing compute instances as shown in the example below:
::
parameters:
DBRootPassword:
type: string
label: Database Password
description: Root password for MySQL
hidden: true
resources:
my_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
str_replace:
template: |
#!/bin/bash
echo "Hello world"
echo "Setting MySQL root password"
mysqladmin -u root password $db_rootpassword
# do more things ...
params:
$db_rootpassword: { get_param: DBRootPassword }
In the example above, one can imagine that MySQL is being configured on a
compute instance and the root password is going to be set based on a user
provided parameter. The script for doing this is provided as userdata to the
compute instance, leveraging the str_replace function.

8
doc/hot-guide/source/index.rst Normal file
View File

@ -0,0 +1,8 @@
HOT guide
=========
.. toctree::
:maxdepth: 2
hot_guide
hot_spec

2
test-requirements.txt
View File

@ -1 +1,3 @@
openstack-doc-tools>=0.17
sphinx>=1.1.2,!=1.2.0,<1.3
oslosphinx