heat-6.1.2/0000775000567000056700000000000013077401020013573 5ustar jenkinsjenkins00000000000000heat-6.1.2/heat_upgradetests/0000775000567000056700000000000013077401020017306 5ustar jenkinsjenkins00000000000000heat-6.1.2/heat_upgradetests/pre_test_hook.sh0000775000567000056700000000000013077400531022506 0ustar jenkinsjenkins00000000000000heat-6.1.2/heat_upgradetests/post_test_hook.sh0000775000567000056700000000000013077400531022705 0ustar jenkinsjenkins00000000000000heat-6.1.2/uninstall.sh0000775000567000056700000000075113077400531016154 0ustar jenkinsjenkins00000000000000#!/bin/bash if [ $EUID -ne 0 ]; then echo "This script must be run as root." >&2 exit fi type -P pip-python &> /dev/null && have_pip_python=1 || have_pip_python=0 if [ $have_pip_python -eq 1 ]; then pip-python uninstall -y heat exit fi type -P pip &> /dev/null && have_pip=1 || have_pip=0 if [ $have_pip -eq 1 ]; then pip uninstall -y heat exit fi echo "pip-python not found. install package (probably python-pip) or run 'easy_install pip', then rerun $0" >&2; heat-6.1.2/babel.cfg0000664000567000056700000000002013077400531015317 0ustar jenkinsjenkins00000000000000[python: **.py] heat-6.1.2/doc/0000775000567000056700000000000013077401020014340 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/README.rst0000664000567000056700000000135513077400531016041 0ustar jenkinsjenkins00000000000000=========================== Building the developer docs =========================== For user and admin docs, go to the directory `doc/docbkx`. Dependencies ============ You'll need to install python *Sphinx* package and *oslosphinx* package: :: sudo pip install sphinx oslosphinx If you are using the virtualenv you'll need to install them in the virtualenv. Get Help ======== Just type make to get help: :: make It will list available build targets. Build Doc ========= To build the man pages: :: make man To build the developer documentation as HTML: :: make html Type *make* for more formats. Test Doc ======== If you modify doc files, you can type: :: make doctest to check whether the format has problem. heat-6.1.2/doc/.gitignore0000664000567000056700000000001713077400531016334 0ustar jenkinsjenkins00000000000000target/ build/ heat-6.1.2/doc/docbkx/0000775000567000056700000000000013077401020015612 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/README.rst0000664000567000056700000000100213077400531017300 0ustar jenkinsjenkins00000000000000================================ Building the user and admin docs ================================ This documentation should eventually end up in the OpenStack documentation repositories `api-site` and `openstack-manuals`. Dependencies ============ on Ubuntu: sudo apt-get install maven on Fedora Core: sudo yum install maven Use `mvn` ========= Build the REST API reference manual: cd api-ref mvn clean generate-sources Build the heat admin guide: cd heat-admin mvn clean generate-sources heat-6.1.2/doc/docbkx/api-ref/0000775000567000056700000000000013077401020017135 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/api-ref/src/0000775000567000056700000000000013077401020017724 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/api-ref/src/wadls/0000775000567000056700000000000013077401020021036 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/api-ref/src/wadls/heat-api/0000775000567000056700000000000013077401020022526 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/api-ref/src/wadls/heat-api/src/0000775000567000056700000000000013077401020023315 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/api-ref/src/wadls/heat-api/src/README.rst0000664000567000056700000000053613077400531025016 0ustar jenkinsjenkins00000000000000========= HEAT wadl ========= The original heat wadl (heat-api-1.0.wadl) and the samples have now been deleted from this repository. The wadl has been renamed and migrated to the following repo location along with the samples: https://git.openstack.org/cgit/openstack/api-site/tree/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl heat-6.1.2/doc/docbkx/api-ref/src/docbkx/0000775000567000056700000000000013077401020021176 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/api-ref/src/docbkx/api-ref.xml0000664000567000056700000005771713077400531023272 0ustar jenkinsjenkins00000000000000 GET'> PUT'> POST'> DELETE'> ]> OpenStack Orchestration API v1 Reference OpenStack LLC 2012 2013 OpenStack LLC API v1 OpenStack Orchestration 2013-10-03 Copyright details are filled in by the template. This document is intended for software developers interested in developing applications using the OpenStack Orchestration Application Programming Interface (API). 2013-10-03 Initial review. Overview OpenStack &Deployment; is a service to deploy and manage multiple composite cloud applications on OpenStack clouds. Interactions with OpenStack &Deployment; occur programmatically via the OpenStack &Deployment; API as described in this document. Reviewer: Can you provide me with a high-level Orchestration architecture diagram that I can add to this section? We welcome feedback, comments, and bug reports at https://bugs.launchpad.net/heat.
Intended Audience This Reference is intended to assist support teams, DevOps Engineers, and software developers who want to manage cloud applications with non-trivial architectures that leverage multiple OpenStack services. To use the information provided here, you should first have a general understanding of the &Deployment; service. You should also be familiar with: Other OpenStack services applicable to your cloud application architecture (Nova, Cinder, Neutron, and so forth) RESTful web services JSON and/or YAML data serialization formats
Document Change History This version of the Reference replaces and obsoletes all previous versions. The most recent changes are described in the table below:
Additional Resources You can find information for developing templates in the Heat Orchestration Template (HOT) Specification at http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec. You can find example templates at https://github.com/heat-ci/heat-prod-templates/tree/master/example. For information about OpenStack services, refer to http://docs.openstack.org.
Concepts To use &Deployment; effectively, you should understand several key concepts:
Stack A stack is a group of resources (servers, load balancers, databases, and so forth) combined to fulfill a useful purpose. A stack is a set of resources that can be deployed. A stack contains a template and generates resources to run the application framework or component specified.
Resource A resource is a template artifact that represents some component of your desired architecture (a Nova server, a group of scaled servers, a Cinder volume, some configuration management system, and so forth).
Template An &Deployment; template is a portable file, written in a user-readable language, that describes how a set of resources should be assembled and what software should be installed in order to produce a working deployment. The template specifies what resources should be used, what attributes can be set, and other parameters that are critical to the successful, repeatable automation of a specific application deployment.
General API Information The &Deployment; API is implemented using a RESTful web service interface. Like other OpenStack services, the &Deployment; Service shares a common token-based authentication system that allows seamless access between products and services.
Authentication The &Deployment; Service supports standard Keystone authentication. For more information, refer to the OpenStack Identity Service API v2.0 Reference. Please contact your provider for additional details on how to authenticate against this API.
Contract Version The contract version denotes the data model and behavior that the API supports. The current contract version is v1. The requested contract version is included in all request URLs. Different contract versions of the API may be available at any given time and are not guaranteed to be compatible with one another. Example Request URL (contract version in <emphasis role="strong" >bold</emphasis>) https://openstack.example.com/v1/1234 This document pertains to contract version 1.
Request/Response Types The &Deployment; API supports both the JSON and YAML data serialization formats. The request format is specified using the Content-Type header and is required for calls that have a request body. The response format can be specified in requests either by using the Accept header or by adding a .yaml or .json extension to the request URI. Note that it is possible for a response to be serialized using a format different from the request. If no response format is specified, JSON is the default. If conflicting formats are specified using both an Accept header and a query extension, the query extension takes precedence.
Response Formats
Format Accept Header Query Extension Default
JSON application/json .json Yes
YAML application/yaml .yaml No
Reviewer: need new examples below: one for "Request with Headers: JSON" and one for "Request with Headers: YAML". In the request example below, notice that Content-Type is set to application/json, but application/yaml is requested via the Accept header: Therefore a YAML response format is returned:
Date/Time Format The &Deployment; Service uses an ISO-8601 compliant date format for the display and consumption of date/time values. The system timezone is in UTC. MySQL converts TIMESTAMP values from the current time zone to UTC for storage, and back from UTC to the current time zone for retrieval. This does not occur for other types, such as DATETIME. &Deployment; Service Date/Time Format yyyy-MM-dd'T'HH:mm:ssZ See the table below for a description of the date/time format codes. May 19th, 2011 at 8:07:08 AM, GMT-5 would have the following format: 2011-05-19T08:07:08-05:00
Explanation of Date/Time Format Codes
Code Description
yyyy Four digit year
MM Two digit month
dd Two digit day of month
T Separator for date/time
HH Two digit hour of day (00-23)
mm Two digit minutes of hour
ss Two digit seconds of the minute
Z RFC-822 timezone
Faults The &Deployment; Service returns the following error codes: Error Code Description 400 Bad Request Invalid parameter values, un-parsable data, or missing required values. 404 Not Found The stack or resource cannot be found. 409 Conflict Invalid action is requested for the current stack status; more than one object exists for the specified non-unique identifier. 500 Internal Server Error Reverting the previously failed action encountered an error, an operation failed on one or more resources, an unexpected error occurred. Reviewer: Need new orchestration examples to replace the fault response examples below. The following two instanceFault examples show errors when the server has erred or cannot perform the requested operation: The error code (code) is returned in the body of the response for convenience. The message element returns a human-readable message that is appropriate for display to the end user. The details element is optional and may contain information that is useful for tracking down an error, such as a stack trace. The details element may or may not be appropriate for display to an end user, depending on the role and experience of the end user. The fault's root element (for example, instanceFault) may change depending on the type of error. The following two badRequest examples show errors when the volume size is invalid: The next two examples show itemNotFound errors:
Stack Status Stacks and resources have a state and a status as described in the lists that follow: State: INIT – (Resources only) The resource has not been provisioned. CREATE – The stack/resource is new. UPDATE – The stack/resource is changed. DELETE – The stack/resource is deleted. ROLLBACK – A previously failed change is being reverted. SUSPEND – (Stacks only) The stack is suspended. RESUME – (Stacks only) The stack is resumed. Status: IN-PROGRESS – The operation is in progress. COMPLETE – The operation is compete. FAILED – The operation failed. So, if you create a new stack and something goes wrong, your stack would be CREATE FAILED. One or more resources of that stack may be in the following states: INIT COMPLETE CREATE FAILED CREATE COMPLETE
API Operations This section describes the Orchestration API operations. Reviewer: please give me a list of section titles to use for dividing up the API calls into related sections. Reviewer: please give me the Error Response Codes for each of the API calls. Glossary resource A resource is a template artifact that represents some component of your desired architecture (a Nova server, a group of scaled servers, a Cinder volume, some configuration management system, and so forth). stack A stack is a group of resources (servers, load balancers, databases, and so forth) combined to fulfill a useful purpose. A stack is a set of resources that can be deployed. A stack contains a template and generates resources to run the application framework or component specified. template An &Deployment; template is a portable file, written in a user-readable language, that describes how a set of resources should be assembled and what software should be installed in order to produce a working deployment. The template specifies what resources should be used, what attributes can be set, and other parameters that are critical to the successful, repeatable automation of a specific application deployment.
heat-6.1.2/doc/docbkx/api-ref/pom.xml0000664000567000056700000001011313077400531020454 0ustar jenkinsjenkins00000000000000 4.0.0 org.openstack.identity docs 1.0 jar OpenStack API Page Project Rackspace Research Repositories true rackspace-research Rackspace Research Repository http://maven.research.rackspacecloud.com/content/groups/public/ rackspace-research Rackspace Research Repository http://maven.research.rackspacecloud.com/content/groups/public/ always UTF-8 1.12.2 com.rackspace.cloud.api clouddocs-maven-plugin ${doctools.version} g1 generate-webhelp generate-sources false 1 UA-17511903-1 true src/docbkx api-ref.xml reviewer openstack 2 true heat-6.1.2/doc/docbkx/heat-admin/0000775000567000056700000000000013077401020017621 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/docbkx/heat-admin/ch_using.xml0000664000567000056700000000267113077400531022156 0ustar jenkinsjenkins00000000000000 GET'> PUT'> POST'> DELETE'> '> '> ]> Using Heat TODO heat-6.1.2/doc/docbkx/heat-admin/pom.xml0000664000567000056700000001627613077400531021160 0ustar jenkinsjenkins00000000000000 4.0.0 org.openstack.docs openstack-guide 1.0.0-SNAPSHOT jar OpenStack Guides local 1 Rackspace Research Repositories true rackspace-research Rackspace Research Repository http://maven.research.rackspacecloud.com/content/groups/public/ rackspace-research Rackspace Research Repository http://maven.research.rackspacecloud.com/content/groups/public/ target/docbkx/pdf **/*.fo com.rackspace.cloud.api clouddocs-maven-plugin 1.12.2 goal1 generate-pdf generate-sources false 0 0 goal2 generate-webhelp generate-sources ${comments.enabled} 1 os-heat-guides 1 UA-17511903-1 appendix toc,title article/appendix nop article toc,title book title,figure,table,example,equation chapter toc,title part toc,title preface toc,title qandadiv toc qandaset toc reference toc,title set toc,title 0 0 true . bk-heat-admin-guide.xml http://docs.openstack.org/${release.path.name}/heat-admin/content/ reviewer openstack heat-6.1.2/doc/docbkx/heat-admin/app_core.xml0000664000567000056700000000074713077400531022151 0ustar jenkinsjenkins00000000000000 ]> Core Configuration File Options TODO heat-6.1.2/doc/docbkx/heat-admin/ch_preface.xml0000664000567000056700000000475013077400531022436 0ustar jenkinsjenkins00000000000000 GET'> PUT'> POST'> DELETE'> '> '> powered by OpenStack'> powered by OpenStack'> ]> Preface
Intended Audience TODO
Document Change History The most recent changes are described in the table below:
Resources TODO
heat-6.1.2/doc/docbkx/heat-admin/bk-heat-admin-guide.xml0000664000567000056700000000440613077400531024051 0ustar jenkinsjenkins00000000000000 ]> Heat Administration Guide 2012 OpenStack Grizzly (2013.1) Heat 2012-12-14 Copyright details are filled in by the template. This document is intended for administrators interested in running the Heat Service. 2012-12-14 First edition of this document. heat-6.1.2/doc/docbkx/heat-admin/ch_install.xml0000664000567000056700000000106613077400531022474 0ustar jenkinsjenkins00000000000000 ]> Heat Installation This chapter describes how to install the Heat Service and get it up and running. heat-6.1.2/doc/docbkx/heat-admin/ch_overview.xml0000664000567000056700000000422413077400531022673 0ustar jenkinsjenkins00000000000000 GET'> PUT'> POST'> DELETE'> '> '> powered by OpenStack'> powered by OpenStack'> ]> Overview This chapter describes the high-level concepts and components of a Heat deployment. heat-6.1.2/doc/docbkx/heat-admin/ch_limitations.xml0000664000567000056700000000270013077400531023356 0ustar jenkinsjenkins00000000000000 GET'> PUT'> POST'> DELETE'> '> '> ]> Limitations TODO heat-6.1.2/doc/Makefile0000664000567000056700000001317113077400531016011 0ustar jenkinsjenkins00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build # 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 " xml to make Docutils-native XML files" @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 " 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 " 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/Heat.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Heat.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/Heat" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Heat" @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." 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." heat-6.1.2/doc/source/0000775000567000056700000000000013077401020015640 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/templates/0000775000567000056700000000000013077401020017636 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/templates/index.rst0000664000567000056700000000155413077400531021512 0ustar jenkinsjenkins00000000000000.. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. This page documents the templates at https://git.openstack.org/cgit/openstack/heat-templates/ Example HOT Templates ===================== .. toctree:: :maxdepth: 1 hot/hello_world Example CFN Templates ===================== .. toctree:: :maxdepth: 1 cfn/WordPress_Single_Instance heat-6.1.2/doc/source/templates/cfn/0000775000567000056700000000000013077401020020404 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/templates/cfn/WordPress_Single_Instance.rst0000664000567000056700000000341513077400531026224 0ustar jenkinsjenkins00000000000000.. 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. AWS Wordpress Single Instance Template -------------------------------------- https://git.openstack.org/cgit/openstack/heat-templates/tree/cfn/F18/WordPress_Single_Instance.template Description ----------- AWS CloudFormation Sample Template WordPress_Single_Instance: WordPress is web software you can use to create a beautiful website or blog. This template installs a single-instance WordPress deployment using a local MySQL database to store the data. Parameters ---------- *KeyName* :mod:`(required)` *type* *string* *description* Name of an existing EC2 KeyPair to enable SSH access to the instance *InstanceType* :mod:`(optional)` *type* *string* *description* The EC2 instance type *DBName* :mod:`(optional)` *type* *string* *description* The WordPress database name *DBUsernameName* :mod:`(optional)` *type* *string* *description* The WordPress database admin account username *DBPassword* :mod:`(optional)` *type* *string* *description* The WordPress database admin account password *DBRootPassword* :mod:`(optional)` *type* *string* *description* Root password for MySQL *LinuxDistribution* :mod:`(optional)` *type* *string* *description* Linux distribution of choice heat-6.1.2/doc/source/templates/hot/0000775000567000056700000000000013077401020020430 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/templates/hot/hello_world.rst0000664000567000056700000000260313077400531023503 0ustar jenkinsjenkins00000000000000.. 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. Hello World HOT Template ------------------------ https://git.openstack.org/cgit/openstack/heat-templates/tree/hot/hello_world.yaml Description ----------- Hello world HOT template that just defines a single compute instance. Contains just base features to verify base HOT support. Parameters ---------- *key_name* :mod:`(required)` *type* *string* *description* Name of an existing key pair to use for the instance *flavor* :mod:`(optional)` *type* *string* *description* Flavor for the instance to be created *image* :mod:`(required)` *type* *string* *description* Image *ID* or image name to use for the instance *admin_pass* :mod:`(required)` *type* *string* *description* The admin password for the instance *db_port* :mod:`(optional)` *type* *number* *description* The database port number heat-6.1.2/doc/source/conf.py0000664000567000056700000002540313077400534017154 0ustar jenkinsjenkins00000000000000# -*- coding: utf-8 -*- # # Licensed under the Apache License, Version 2.0 (the "License"); you may # not use this file except in compliance with the License. You may obtain # a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. # # Heat documentation build configuration file, created by # sphinx-quickstart on Thu Dec 13 11:23:35 2012. # # 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 glob import os import subprocess import sys import tempfile from oslo_config import cfg BASE_DIR = os.path.dirname(os.path.abspath(__file__)) ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) CONTRIB_DIR = os.path.join(ROOT, 'contrib') PLUGIN_DIRS = glob.glob(os.path.join(CONTRIB_DIR, '*')) ENV_DIR = os.path.join(ROOT, "etc", "heat", "environment.d") TEMP_ENV_DIR = tempfile.mkdtemp() for f in glob.glob(os.path.join(ENV_DIR, "*.yaml")): with open(f, "r") as fin: name = os.path.split(f)[-1] with open(os.path.join(TEMP_ENV_DIR, name), "w") as fout: fout.write(fin.read().replace("file:///", "file://%s/" % ROOT)) sys.path.insert(0, ROOT) sys.path.insert(0, BASE_DIR) cfg.CONF.import_opt('plugin_dirs', 'heat.common.config') cfg.CONF.set_override(name='plugin_dirs', override=PLUGIN_DIRS) cfg.CONF.import_opt('environment_dir', 'heat.common.config') cfg.CONF.set_override(name='environment_dir', override=TEMP_ENV_DIR) # This is required for ReadTheDocs.org, but isn't a bad idea anyway. os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings' # 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 = ['sphinx.ext.autodoc', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinx.ext.doctest', 'oslosphinx', 'ext.resources', 'ext.tablefromtext', 'stevedore.sphinxext'] todo_include_todos = True # Add any paths that contain templates here, relative to this directory. if os.getenv('HUDSON_PUBLISH_DOCS'): templates_path = ['_ga', '_templates'] else: 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'Heat' copyright = u'2012,2013 Heat Developers' # 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 = [] primary_domain = 'py' nitpicky = 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_path = ['.'] # html_theme = '_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { "nosidebar": "false" } # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". # html_title = None # A shorter title for the navigation bar. Default is the same as html_title. # html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. # html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. # html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". # html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. # html_last_updated_fmt = '%b %d, %Y' git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", "-n1"] html_last_updated_fmt = subprocess.Popen( git_cmd, stdout=subprocess.PIPE).communicate()[0] # 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 = 'Heatdoc' # -- 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]) latex_documents = [ ('index', 'Heat.tex', u'Heat Documentation', u'Heat Developers', '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 = [ ('man/heat-api', 'heat-api', u'REST API service to the heat project.', [u'Heat Developers'], 1), ('man/heat-api-cfn', 'heat-api-cfn', u'CloudFormation compatible API service to the heat project.', [u'Heat Developers'], 1), ('man/heat-api-cloudwatch', 'heat-api-cloudwatch', u'CloudWatch alike API service to the heat project', [u'Heat Developers'], 1), ('man/heat-db-setup', 'heat-db-setup', u'Command line utility to setup the Heat database', [u'Heat Developers'], 1), ('man/heat-engine', 'heat-engine', u'Service which performs the actions from the API calls made by the user', [u'Heat Developers'], 1), ('man/heat-keystone-setup', 'heat-keystone-setup', u'Script which sets up keystone for usage by Heat', [u'Heat Developers'], 1), ('man/heat-keystone-setup-domain', 'heat-keystone-setup-domain', u'Script which sets up a keystone domain for heat users and projects', [u'Heat Developers'], 1), ('man/heat-manage', 'heat-manage', u'Script which helps manage specific database operations', [u'Heat Developers'], 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', 'Heat', u'Heat Documentation', u'Heat Developers', 'Heat', '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' heat-6.1.2/doc/source/getting_started/0000775000567000056700000000000013077401020021027 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/getting_started/standalone.rst0000664000567000056700000000607113077400531023723 0ustar jenkinsjenkins00000000000000.. 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. How to get heat to work with a remote OpenStack. ================================================ Say you have a remote/public install of OpenStack and you want to use a local install of heat to talk to it. This can be handy when developing, as the remote OpenStack can be kept stable and is not effected by changes made to the development machine. So lets say you have 2 machines: * “rock” ip == 192.168.1.88 (used for base OpenStack services) * “hack” ip == 192.168.1.77 (used for heat development) Install your OpenStack as normal on “rock”. In this example "hack" is used as the devstack to install heat on. The localrc looked like this:: HEAT_STANDALONE=True KEYSTONE_AUTH_HOST=192.168.1.88 KEYSTONE_AUTH_PORT=35357 KEYSTONE_AUTH_PROTOCOL=http KEYSTONE_SERVICE_HOST=$KEYSTONE_AUTH_HOST KEYSTONE_SERVICE_PORT=$KEYSTONE_AUTH_PORT KEYSTONE_SERVICE_PROTOCOL=$KEYSTONE_AUTH_PROTOCOL MY_PASSWORD=abetterpasswordthanthis DATABASE_PASSWORD=$MY_PASSWORD RABBIT_PASSWORD=$MY_PASSWORD disable_all_services # Alternative RPC backends are zeromq and rabbit ENABLED_SERVICES=qpid enable_service mysql heat h-api h-api-cfn h-api-cw h-eng Then run your ./stack.sh as normal. You then need a special environment (not devstack/openrc) to make this work. go to your “rock” machine and get the tenant_id that you want to work with:: keystone tenant-list +----------------------------------+--------------------+---------+ | id | name | enabled | +----------------------------------+--------------------+---------+ | 6943e3ebad0d465387d05d73f8e0b3fc | admin | True | | b12482712e354dd3b9f64ce608ba20f3 | alt_demo | True | | bf03bf32e3884d489004ac995ff7a61c | demo | True | | c23ceb3bf5dd4f9692488855de99137b | invisible_to_admin | True | | c328c1f3b945487d859ed2f53dcf0fe4 | service | True | +----------------------------------+--------------------+---------+ Let's say you want “demo”. Now make a file to store your new environment (heat.env). :: export HEAT_URL=http://192.168.1.77:8004/v1/bf03bf32e3884d489004ac995ff7a61c export OS_NO_CLIENT_AUTH=True export OS_USERNAME=admin export OS_TENANT_NAME=demo export OS_PASSWORD=abetterpasswordthanthis export OS_AUTH_URL=http://192.168.1.88:35357/v2.0/ Now you use this like:: . heat.env heat stack-list Note: remember to open up firewall ports on “rock” so that you can access the OpenStack services. heat-6.1.2/doc/source/getting_started/jeos_building.rst0000664000567000056700000000745213077400534024417 0ustar jenkinsjenkins00000000000000.. 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. Building JEOS images for use with Heat ====================================== Heat's full functionality can only be used when launching cloud images that have the heat-cfntools_ package installed. This document describes some options for creating a heat-cfntools enabled image for yourself. .. _heat-cfntools: https://git.openstack.org/cgit/openstack/heat-cfntools Building an image with diskimage-builder ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diskimage-builder_ is a tool for customizing cloud images. tripleo-image-elements_ is a collection of diskimage-builder elements related to the TripleO_ project. It includes an element for heat-cfntools which can be used to create heat-enabled images. .. _diskimage-builder: https://git.openstack.org/cgit/openstack/diskimage-builder .. _tripleo-image-elements: https://git.openstack.org/cgit/openstack/tripleo-image-elements .. _TripleO: https://wiki.openstack.org/wiki/TripleO Install the tool (preferably in a virtualenv) and fetch the elements:: pip install git+https://git.openstack.org/openstack/diskimage-builder git clone https://git.openstack.org/openstack/tripleo-image-elements To create a heat-cfntools enabled image with the current release of Fedora x86_64:: export ELEMENTS_PATH=tripleo-image-elements/elements disk-image-create vm fedora heat-cfntools -a amd64 -o fedora-heat-cfntools The image may then be pushed to glance, e.g:: source ~/.openstack/keystonerc glance image-create --name fedora-heat-cfntools --is-public true --disk-format qcow2 --container-format bare < fedora-heat-cfntools.qcow2 To create a heat-cfntools enabled image with the current release of Ubuntu i386:: export ELEMENTS_PATH=tripleo-image-elements/elements disk-image-create vm ubuntu heat-cfntools -a i386 -o ubuntu-heat-cfntools If you are creating your own images you should consider creating golden images which contain all the packages required for the stacks that you launch. You can do this by writing your own diskimage-builder elements and invoking those elements in the call to disk-image-create. This means that the resulting heat templates only need to modify configuration files. This will speed stack launch time and reduce the risk of a transient package download failure causing the stack launch to fail. To create an image that contains hooks needed for SoftwareConfig and SoftwareDeployment, you can follow the steps bellow to build a fedora based image:: pip install git+https://git.openstack.org/openstack/diskimage-builder git clone https://git.openstack.org/openstack/tripleo-image-elements git clone https://git.openstack.org/openstack/heat-templates export ELEMENTS_PATH=tripleo-image-elements/elements:heat-templates/hot/software-config/elements disk-image-create vm \ fedora selinux-permissive \ heat-config \ os-collect-config \ os-refresh-config \ os-apply-config \ heat-config-cfn-init \ heat-config-puppet \ heat-config-script \ -o fedora-software-config.qcow2 The image may then be pushed to glance, e.g:: source ~/.openstack/keystonerc glance image-create --name=fedora-software-config --is-public=true --disk-format=qcow2 --container-format=bare < fedora-software-config.qcow2 heat-6.1.2/doc/source/getting_started/on_devstack.rst0000664000567000056700000000637513077400534024105 0ustar jenkinsjenkins00000000000000.. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Heat and DevStack ================= Heat is fully integrated into DevStack. This is a convenient way to try out or develop heat alongside the current development state of all the other OpenStack projects. Heat on DevStack works on both Ubuntu and Fedora. These instructions assume you already have a working DevStack installation which can launch basic instances. Configure DevStack to enable Heat --------------------------------- Heat is configured by default on devstack for Icehouse and Juno releases. Newer versions of OpenStack require enabling heat services in devstack `local.conf`. Add the following to `[[local|localrc]]` section of `local.conf`:: [[local|localrc]] #Enable heat services enable_service h-eng h-api h-api-cfn h-api-cw It would also be useful to automatically download and register a VM image that Heat can launch. To do that add the following to your devstack `localrc`:: IMAGE_URL_SITE="http://download.fedoraproject.org" IMAGE_URL_PATH="/pub/fedora/linux/releases/21/Cloud/Images/x86_64/" IMAGE_URL_FILE="Fedora-Cloud-Base-20141203-21.x86_64.qcow2" IMAGE_URLS+=","$IMAGE_URL_SITE$IMAGE_URL_PATH$IMAGE_URL_FILE URLs for any cloud image may be specified, but fedora images from F20 contain the heat-cfntools package which is required for some heat functionality. That is all the configuration that is required. When you run `./stack.sh` the Heat processes will be launched in `screen` with the labels prefixed with `h-`. Configure DevStack to enable Ceilometer (if using Alarms) --------------------------------------------------------- To use Ceilometer Alarms you need to enable Ceilometer in devstack. Adding the following lines to your `localrc` file will enable the ceilometer services:: CEILOMETER_BACKEND=mongodb enable_plugin ceilometer https://git.openstack.org/openstack/ceilometer Configure DevStack to enable OSprofiler --------------------------------------- Add the profiler notifier to your Ceilometer to your config:: CEILOMETER_NOTIFICATION_TOPICS=notifications,profiler Enable the profiler in /etc/heat/heat.conf:: $ echo -e "[profiler]\nprofiler_enabled = True\n"\ "trace_sqlalchemy = True\n"\ >> /etc/heat/heat.conf Change the default hmac_key in /etc/heat/api-paste.ini:: $ sed -i "s/hmac_keys =.*/hmac_keys = SECRET_KEY/" /etc/heat/api-paste.ini Run any command with --profile SECRET_KEY:: $ heat --profile SECRET_KEY stack-list # it will print Get pretty HTML with traces:: $ osprofiler trace show --html Note that osprofiler should be run with the admin user name & tenant. Create a stack -------------- Now that you have a working Heat environment you can go to :ref:`create-a-stack`. heat-6.1.2/doc/source/getting_started/index.rst0000664000567000056700000000134713077400531022703 0ustar jenkinsjenkins00000000000000.. 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. Getting Started Guides ====================== .. toctree:: :maxdepth: 2 on_devstack on_fedora on_ubuntu on_other jeos_building standalone heat-6.1.2/doc/source/getting_started/on_other.rst0000664000567000056700000000206613077400531023410 0ustar jenkinsjenkins00000000000000.. 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. Installing OpenStack on other distributions =========================================== - There is a `Debian packaging team for OpenStack`_. - There are instructions for `installing OpenStack on Ubuntu`_. - Various other distributions may have packaging teams or getting started guides available. .. _Debian packaging team for OpenStack: http://wiki.openstack.org/Packaging/Debian .. _installing OpenStack on Ubuntu: http://docs.openstack.org/bexar/openstack-compute/admin/content/ch03s02.html heat-6.1.2/doc/source/getting_started/on_fedora.rst0000664000567000056700000000250313077400534023526 0ustar jenkinsjenkins00000000000000.. 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. Installing OpenStack and Heat on RHEL/Fedora/CentOS --------------------------------------------------- Go to the `OpenStack Documentation `_ for the latest version of the Installation Guide for Red Hat Enterprise Linux, CentOS and Fedora which includes a chapter on installing the Orchestration module (Heat). There are instructions for `installing the RDO OpenStack distribution `_ on Fedora and CentOS. If installing with packstack, you can install heat by specifying ``--os-heat-install=y`` in your packstack invocation, or setting ``CONFIG_HEAT_INSTALL=y`` in your answers file. If installing with `RDO-Manager `_ Heat will be installed by default. heat-6.1.2/doc/source/getting_started/on_ubuntu.rst0000664000567000056700000000170313077400531023606 0ustar jenkinsjenkins00000000000000.. 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. Installing Heat on Ubuntu ------------------------- Heat is packaged for Debian, and Ubuntu (from 13.10) Go to the `OpenStack Documentation `_ for the latest version of the Installation Guide for Ubuntu which includes a chapter on installing the Orchestration module (Heat). There is a `Juju Charm for Heat ` available. heat-6.1.2/doc/source/getting_started/create_a_stack.rst0000664000567000056700000000720613077400534024527 0ustar jenkinsjenkins00000000000000.. 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. .. _create-a-stack: Creating your first stack ========================= Confirming you can access a Heat endpoint ----------------------------------------- Before any Heat commands can be run, your cloud credentials need to be sourced:: $ source openrc You can confirm that Heat is available with this command:: $ heat stack-list This should return an empty line Preparing to create a stack --------------------------- Your cloud will have different flavors and images available for launching instances, you can discover what is available by running:: $ openstack flavor list $ openstack image list To allow you to SSH into instances launched by Heat, a keypair will be generated:: $ openstack keypair create heat_key > heat_key.priv $ chmod 600 heat_key.priv Launching a stack ----------------- Now lets launch a stack, using an example template from the heat-templates repository:: $ heat stack-create -u http://git.openstack.org/cgit/openstack/heat-templates/plain/hot/F20/WordPress_Native.yaml -P key_name=heat_key -P image_id=my-fedora-image -P instance_type=m1.small teststack Which will respond:: +--------------------------------------+-----------+--------------------+----------------------+ | ID | Name | Status | Created | +--------------------------------------+-----------+--------------------+----------------------+ | (uuid) | teststack | CREATE_IN_PROGRESS | (timestamp) | +--------------------------------------+-----------+--------------------+----------------------+ .. note:: Link on Heat template presented in command above should reference on RAW template. In case if it be a "html" page with template, Heat will return an error. List stacks ~~~~~~~~~~~ List the stacks in your tenant:: $ heat stack-list List stack events ~~~~~~~~~~~~~~~~~ List the events related to a particular stack:: $ heat event-list teststack Describe the wordpress stack ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Show detailed state of a stack:: $ heat stack-show teststack Note: After a few seconds, the stack_status should change from ``IN_PROGRESS`` to ``CREATE_COMPLETE``. Verify instance creation ~~~~~~~~~~~~~~~~~~~~~~~~ Because the software takes some time to install from the repository, it may be a few minutes before the Wordpress instance is in a running state. Point a web browser at the location given by the ``WebsiteURL`` output as shown by ``heat output-show``:: $ WebsiteURL=$(heat output-show --format raw teststack WebsiteURL) $ curl $WebsiteURL Delete the instance when done ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note: The list operation will show no running stack.:: $ heat stack-delete teststack $ heat stack-list You can explore other heat commands by referring to the `Heat chapter `_ of the `OpenStack Command-Line Interface Reference `_ then read the :ref:`template-guide` and start authoring your own templates. heat-6.1.2/doc/source/contributing/0000775000567000056700000000000013077401020020347 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/contributing/blueprints.rst0000664000567000056700000001030413077400534023277 0ustar jenkinsjenkins00000000000000Blueprints and Specs ==================== The Heat team uses the `heat-specs `_ repository for its specification reviews. Detailed information can be found `here `_. Please note that we use a `template `_ for spec submissions. It is not required to fill out all sections in the template. Spec Notes ---------- There are occasions when a spec is approved and the code does not land in the cycle it was targeted for. For these cases, the workflow to get the spec into the next release is as below: * Anyone can propose a patch to heat-specs which moves a spec from the previous release backlog into the new release directory. The specs which are moved in this way can be fast-tracked into the next release. Please note that it is required to re-propose the spec for the new release and it'll be evaluated based on the resources available and cycle priorities. Heat Spec Lite -------------- Lite specs are small feature requests tracked as Launchpad bugs, with status 'Wishlist' and tagged with 'spec-lite' tag. These allow for submission and review of these feature requests before code is submitted. These can be used for small features that don’t warrant a detailed spec to be proposed, evaluated, and worked on. The team evaluates these requests as it evaluates specs. Once a `spec-lite` bug has been approved/triaged as a Request for Enhancement(RFE), it’ll be targeted for a release. The workflow for the life of a spec-lite in Launchpad is as follows: * File a bug with a small summary of what the requested change is and tag it as `spec-lite`. * The bug is triaged and importance changed to `Wishlist`. * The bug is evaluated and marked as `Triaged` to announce approval or to `Won't fix` to announce rejection or `Invalid` to request a full spec. * The bug is moved to `In Progress` once the code is up and ready to review. * The bug is moved to `Fix Committed` once the patch lands. In summary: +--------------+-----------------------------------------------------------------------------+ |State | Meaning | +==============+=============================================================================+ |New | This is where spec-lite starts, as filed by the community. | +--------------+-----------------------------------------------------------------------------+ |Triaged | Drivers - Move to this state to mean, "you can start working on it" | +--------------+-----------------------------------------------------------------------------+ |Won't Fix | Drivers - Move to this state to reject a lite-spec. | +--------------+-----------------------------------------------------------------------------+ |Invalid | Drivers - Move to this state to request a full spec for this request | +--------------+-----------------------------------------------------------------------------+ The drivers team will discuss the following bug reports in IRC meetings: * `heat RFE's `_ * `python-heatclient RFE's `_ Lite spec Submission Guidelines ------------------------------- When a bug is submitted, there are two fields that must be filled: ‘summary’ and ‘further information’. The ‘summary’ must be brief enough to fit in one line. The ‘further information’ section must be a description of what you would like to see implemented in heat. The description should provide enough details for a knowledgeable developer to understand what is the existing problem and what’s the proposed solution. Add `spec-lite` tag to the bug. Lite spec from existing bugs ---------------------------- If there's an already existing bug that describes a small feature suitable for a spec-lite, add a `spec-lite' tag to the bug. There is no need to create a new bug. The comments and history of the existing bug are important for it's review. heat-6.1.2/doc/source/contributing/index.rst0000664000567000056700000000067713077400531022230 0ustar jenkinsjenkins00000000000000Heat Contribution Guidelines ============================ In the Contributions Guide, you will find documented policies for developing with heat. This includes the processes we use for blueprints and specs, bugs, contributor onboarding, core reviewer memberships, and other procedural items. Policies -------- .. toctree:: :maxdepth: 3 blueprints .. bugs contributor-onboarding core-reviewers gate-failure-triage code-reviews heat-6.1.2/doc/source/index.rst0000664000567000056700000000623013077400534017513 0ustar jenkinsjenkins00000000000000.. 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. ================================== Welcome to the Heat documentation! ================================== Heat is a service to orchestrate composite cloud applications using a declarative template format through an OpenStack-native REST API. Heat's purpose and vision ========================= * Heat provides a template based orchestration for describing a cloud application by executing appropriate :term:`OpenStack` API calls to generate running cloud applications. * A Heat template describes the infrastructure for a cloud application in text files which are readable and writable by humans, and can be managed by version control tools. * Templates specify the relationships between resources (e.g. this volume is connected to this server). This enables Heat to call out to the OpenStack APIs to create all of your infrastructure in the correct order to completely launch your application. * The software integrates other components of OpenStack. The templates allow creation of most OpenStack resource types (such as instances, floating ips, volumes, security groups, users, etc), as well as some more advanced functionality such as instance high availability, instance autoscaling, and nested stacks. * Heat primarily manages infrastructure, but the templates integrate well with software configuration management tools such as Puppet and Ansible. * Operators can customise the capabilities of Heat by installing plugins. This documentation offers information aimed at end-users, operators and developers of Heat. Using Heat ========== .. toctree:: :maxdepth: 1 getting_started/create_a_stack template_guide/index templates/index glossary Operating Heat ============== .. toctree:: :maxdepth: 1 getting_started/on_fedora getting_started/on_ubuntu operating_guides/scale_deployment man/index Developing Heat =============== .. toctree:: :maxdepth: 1 contributing/index getting_started/on_devstack developing_guides/architecture developing_guides/pluginguide developing_guides/schedulerhints developing_guides/gmr developing_guides/supportstatus developing_guides/rally_on_gates API Documentation ======================== - `Heat REST API Reference (OpenStack API Complete Reference - Orchestration)`_ .. _`Heat REST API Reference (OpenStack API Complete Reference - Orchestration)`: http://api.openstack.org/api-ref-orchestration-v1.html Code Documentation ================== .. toctree:: :maxdepth: 1 api/autoindex Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` heat-6.1.2/doc/source/operating_guides/0000775000567000056700000000000013077401020021170 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/operating_guides/scale_deployment.rst0000664000567000056700000002664313077400531025272 0ustar jenkinsjenkins00000000000000.. 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. ==================== Scaling a Deployment ==================== When deploying in an environment where a large number of incoming requests need to be handled, the API and engine services can be overloaded. In those scenarios, in order to increase the system performance, it can be helpful to run multiple load-balanced APIs and engines. This guide details how to scale out the REST API, the CFN API, and the engine, also known as the *heat-api*, *heat-api-cfn*, and *heat-engine* services, respectively. .. _scale_deployment_assumptions: Assumptions =========== This guide, using a devstack installation of OpenStack, assumes that: 1. You have configured devstack from `Single Machine Installation Guide `_; 2. You have set up heat on devstack, as defined at `heat and DevStack `_; 3. You have installed `HAProxy `_ on the devstack server. Architecture ============ This section shows the basic heat architecture, the load balancing mechanism used and the target scaled out architecture. Basic Architecture ------------------ The heat architecture is as defined at `heat architecture `_ and shown in the diagram below, where we have a CLI that sends HTTP requests to the REST and CFN APIs, which in turn make calls using AMQP to the heat-engine. :: |- [REST API] -| [CLI] -- -- -- -- [ENGINE] |- [CFN API] -| Load Balancing -------------- As there is a need to use a load balancer mechanism between the multiple APIs and the CLI, a proxy has to be deployed. Because the heat CLI and APIs communicate by exchanging HTTP requests and responses, a `HAProxy `_ HTTP load balancer server will be deployed between them. This way, the proxy will take the CLIs requests to the APIs and act on their behalf. Once the proxy receives a response, it will be redirected to the caller CLI. A round-robin distribution of messages from the AMQP queue will act as the load balancer for multiple engines. Check that your AMQP service is configured to distribute messages round-robin (RabbitMQ does this by default). Target Architecture ------------------- A scaled out heat architecture is represented in the diagram below: :: |- [REST-API] -| |- ... -| |- [REST-API] -| |- [ENGINE] -| [CLI] -- -- [PROXY] -- -- -- |- ... -| |- [API-CFN] -| |- [ENGINE] -| |- ... -| |- [API-CFN] -| Thus, a request sent from the CLI looks like: 1. CLI contacts the proxy; 2. The HAProxy server, acting as a load balancer, redirects the call to an API instance; 3. The API server sends messages to the AMQP queue, and the engines pick up messages in round-robin fashion. Deploying Multiple APIs ======================= In order to run a heat component separately, you have to execute one of the python scripts located at the *bin* directory of your heat repository. These scripts take as argument a configuration file. When using devstack, the configuration file is located at */etc/heat/heat.conf*. For instance, to start new REST and CFN API services, you must run: :: python bin/heat-api --config-file=/etc/heat/heat.conf python bin/heat-api-cfn --config-file=/etc/heat/heat.conf Each API service must have a unique address to listen. This address have to be defined in the configuration file. For REST and CFN APIs, modify the *[heat_api]* and *[heat_api_cfn]* blocks, respectively. :: [heat_api] bind_port = {API_PORT} bind_host = {API_HOST} ... [heat_api_cfn] bind_port = {API_CFN_PORT} bind_host = {API_CFN_HOST} If you wish to run multiple API processes on the same machine, you must create multiple copies of the heat.conf file, each containing a unique port number. In addition, if you want to run some API services in different machines than the devstack server, you have to update the loopback addresses found at the *sql_connection* and *rabbit_host* properties to the devstack server's IP, which must be reachable from the remote machine. Deploying Multiple Engines ========================== All engines must be configured to use the same AMQP service. Ensure that all of the *rabbit_*\* and *kombu_*\* configuration options in the *[DEFAULT]* section of */etc/heat/heat.conf* match across each machine that will be running an engine. By using the same AMQP configuration, each engine will subscribe to the same AMQP *engine* queue and pick up work in round-robin fashion with the other engines. One or more engines can be deployed per host. Depending on the host's CPU architecture, it may be beneficial to deploy several engines on a single machine. To start multiple engines on the same machine, simply start multiple *heat-engine* processes: :: python bin/heat-engine --config-file=/etc/heat/heat.conf & python bin/heat-engine --config-file=/etc/heat/heat.conf & Deploying the Proxy =================== In order to simplify the deployment of the HAProxy server, we will replace the REST and CFN APIs deployed when installing devstack by the HAProxy server. This way, there is no need to update, on the CLI, the addresses where it should look for the APIs. In this case, when it makes a call to any API, it will find the proxy, acting on their behalf. Note that the addresses that the HAProxy will be listening to are the pairs *API_HOST:API-PORT* and *API_CFN_HOST:API_CFN_PORT*, found at the *[heat_api]* and *[heat_api_cfn]* blocks on the devstack server's configuration file. In addition, the original *heat-api* and *heat-api-cfn* processes running in these ports have to be killed, because these addresses must be free to be used by the proxy. To deploy the HAProxy server on the devstack server, run *haproxy -f apis-proxy.conf*, where this configuration file looks like: :: global daemon maxconn 4000 defaults log global maxconn 8000 option redispatch retries 3 timeout http-request 10s timeout queue 1m timeout connect 10s timeout client 1m timeout server 1m timeout check 10s listen rest_api_proxy # The values required below are the original ones that were in # /etc/heat/heat.conf on the devstack server. bind {API_HOST}:{API_PORT} balance source option tcpka option httpchk # The values required below are the different addresses supplied when # running the REST API instances. server SERVER_1 {HOST_1}:{PORT_1} ... server SERVER_N {HOST_N}:{PORT_N} listen cfn_api_proxy # The values required below are the original ones that were in # /etc/heat/heat.conf on the devstack server. bind {API_CFN_HOST}:{API_CFN_PORT} balance source option tcpka option httpchk # The values required below are the different addresses supplied when # running the CFN API instances. server SERVER_1 {HOST_1}:{PORT_1} ... server SERVER_N {HOST_N}:{PORT_N} Sample ====== This section aims to clarify some aspects of the scaling out solution, as well as to show more details of the configuration by describing a concrete sample. Architecture ------------ This section shows a basic OpenStack architecture and the target one that will be used for testing of the scaled-out heat services. Basic Architecture ^^^^^^^^^^^^^^^^^^ For this sample, consider that: 1. We have an architecture composed by 3 machines configured in a LAN, with the addresses A: 10.0.0.1; B: 10.0.0.2; and C: 10.0.0.3; 2. The OpenStack devstack installation, including the heat module, has been done in the machine A, as shown in the :ref:`scale_deployment_assumptions` section. Target Architecture ^^^^^^^^^^^^^^^^^^^ At this moment, everything is running in a single devstack server. The next subsections show how to deploy a scaling out heat architecture by: 1. Running one REST and one CFN API on the machines B and C; 2. Setting up the HAProxy server on the machine A. Running the API and Engine Services ----------------------------------- For each machine, B and C, you must do the following steps: 1. Clone the heat repository https://git.openstack.org/cgit/openstack/heat, run: :: git clone https://git.openstack.org/openstack/heat 2. Create a local copy of the configuration file */etc/heat/heat.conf* from the machine A; 3. Make required changes on the configuration file; 4. Enter the heat local repository and run: :: python bin/heat-api --config-file=/etc/heat/heat.conf python bin/heat-api-cfn --config-file=/etc/heat/heat.conf 5. Start as many *heat-engine* processes as you want running on that machine: :: python bin/heat-engine --config-file=/etc/heat/heat.conf & python bin/heat-engine --config-file=/etc/heat/heat.conf & ... Changes On Configuration ^^^^^^^^^^^^^^^^^^^^^^^^ The original file from A looks like: :: [DEFAULT] ... sql_connection = mysql+pymysql://root:admin@127.0.0.1/heat?charset=utf8 rabbit_host = localhost ... [heat_api] bind_port = 8004 bind_host = 10.0.0.1 ... [heat_api_cfn] bind_port = 8000 bind_host = 10.0.0.1 After the changes for B, it looks like: :: [DEFAULT] ... sql_connection = mysql+pymysql://root:admin@10.0.0.1/heat?charset=utf8 rabbit_host = 10.0.0.1 ... [heat_api] bind_port = 8004 bind_host = 10.0.0.2 ... [heat_api_cfn] bind_port = 8000 bind_host = 10.0.0.2 Setting Up HAProxy ------------------ On the machine A, kill the *heat-api* and *heat-api-cfn* processes by running *pkill heat-api* and *pkill heat-api-cfn*. After, run *haproxy -f apis-proxy.conf* with the following configuration: :: global daemon maxconn 4000 defaults log global maxconn 8000 option redispatch retries 3 timeout http-request 10s timeout queue 1m timeout connect 10s timeout client 1m timeout server 1m timeout check 10s listen rest_api_proxy bind 10.0.0.1:8004 balance source option tcpka option httpchk server rest-server-1 10.0.0.2:8004 server rest-server-2 10.0.0.3:8004 listen cfn_api_proxy bind 10.0.0.1:8000 balance source option tcpka option httpchk server cfn-server-1 10.0.0.2:8000 server cfn-server-2 10.0.0.3:8000 heat-6.1.2/doc/source/sourcecode/0000775000567000056700000000000013077401020017773 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/sourcecode/.gitignore0000664000567000056700000000000613077400531021765 0ustar jenkinsjenkins00000000000000*.rst heat-6.1.2/doc/source/glossary.rst0000664000567000056700000001511513077400534020251 0ustar jenkinsjenkins00000000000000.. 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. ========== Glossary ========== .. glossary:: :sorted: API server HTTP REST API service for heat. CFN An abbreviated form of "AWS CloudFormation". Constraint Defines valid input :term:`parameters` for a :term:`template`. Dependency When a :term:`resource` must wait for another resource to finish creation before being created itself. Heat adds an implicit dependency when a resource references another resource or one of its :term:`attributes `. An explicit dependency can also be created by the user in the template definition. Environment Used to affect the run-time behavior of the template. Provides a way to override the default resource implementation and parameters passed to Heat. See :ref:`Environments`. Heat Orchestration Template A particular :term:`template` format that is native to Heat. Heat Orchestration Templates are expressed in YAML and are not backwards-compatible with CloudFormation templates. HOT An acronym for ":term:`Heat Orchestration Template`". Input parameters See :term:`Parameters`. Metadata May refer to :term:`Resource Metadata`, :term:`Nova Instance metadata`, or the :term:`Metadata service`. Metadata service A Compute service that enables virtual machine instances to retrieve instance-specific data. See `Metadata service (OpenStack Cloud Admin Guide)`_. .. _Metadata service (OpenStack Cloud Admin Guide): http://docs.openstack.org/admin-guide-cloud/compute-networking-nova.html#metadata-service Multi-region A feature of Heat that supports deployment to multiple regions. Nested resource A :term:`resource` instantiated as part of a :term:`nested stack`. Nested stack A :term:`template` referenced by URL inside of another template. Used to reduce redundant resource definitions and group complex architectures into logical groups. Nova Instance metadata User-provided *key:value* pairs associated with a Compute Instance. See `Instance specific data (OpenStack Operations Guide)`_. .. _Instance specific data (OpenStack Operations Guide): http://docs.openstack.org/openstack-ops/content/instances.html#instance_specific_data OpenStack Open source software for building private and public clouds. Orchestrate Arrange or direct the elements of a situation to produce a desired effect. Outputs A top-level block in a :term:`template` that defines what data will be returned by a stack after instantiation. Parameters A top-level block in a :term:`template` that defines what data can be passed to customise a template when it is used to create or update a :term:`stack`. Provider resource A :term:`resource` implemented by a :term:`provider template`. The parent resource's properties become the :term:`nested stack's ` parameters. See `What are "Providers"? (OpenStack Wiki)`_. .. _`What are "Providers"? (OpenStack Wiki)`: https://wiki.openstack.org/wiki/Heat/Providers#What_are_.22Providers.22.3F Provider template Allows user-definable :term:`resource providers ` to be specified via :term:`nested stacks `. The nested stack's :term:`outputs` become the parent stack's :term:`attributes `. Resource An element of OpenStack infrastructure instantiated from a particular :term:`resource provider`. See also :term:`Nested resource`. Resource attribute Data that can be obtained from a :term:`resource`, e.g. a server's public IP or name. Usually passed to another resource's :term:`properties ` or added to the stack's :term:`outputs`. Resource group A :term:`resource provider` that creates one or more identically configured :term:`resources ` or :term:`nested resources `. Resource Metadata A :term:`resource property` that contains CFN-style template metadata. See `AWS::CloudFormation::Init (AWS CloudFormation User Guide)`_ .. _AWS::CloudFormation::Init (AWS CloudFormation User Guide): http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html Resource plugin Python code that understands how to instantiate and manage a :term:`resource`. See `Heat Resource Plugins (OpenStack wiki)`_. .. _Heat Resource Plugins (OpenStack wiki): https://wiki.openstack.org/wiki/Heat/Plugins#Heat_Resource_Plugins Resource property Data utilized for the instantiation of a :term:`resource`. Can be defined statically in a :term:`template` or passed in as :term:`input parameters `. Resource provider The implementation of a particular resource type. May be a :term:`Resource plugin` or a :term:`Provider template`. Stack A collection of instantiated :term:`resources ` that are defined in a single :term:`template`. Stack resource A :term:`resource provider` that allows the management of a :term:`nested stack` as a :term:`resource` in a parent stack. Template An orchestration document that details everything needed to carry out an :term:`orchestration `. Template resource See :term:`Provider resource`. User data A :term:`resource property` that contains a user-provided data blob. User data gets passed to `cloud-init`_ to automatically configure instances at boot time. See also `User data (OpenStack End User Guide)`_. .. _User data (OpenStack End User Guide): http://docs.openstack.org/user-guide/cli_provide_user_data_to_instances.html .. _cloud-init: https://help.ubuntu.com/community/CloudInit Wait condition A :term:`resource provider` that provides a way to communicate data or events from servers back to the orchestration engine. Most commonly used to pause the creation of the :term:`stack` while the server is being configured. heat-6.1.2/doc/source/ext/0000775000567000056700000000000013077401020016440 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/ext/tablefromtext.py0000664000567000056700000000707313077400534021712 0ustar jenkinsjenkins00000000000000# # 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. # -*- coding: utf-8 -*- import os import re from docutils import nodes from docutils.parsers.rst import directives from docutils.parsers.rst.directives.tables import Table class TableFromText(Table): """Take input from a file and create a simple table. Example: .. table_from_text:: ../setup.cfg :header: Name,Plug-in :regex: (.*)=(.*) :start-after: heat.constraints = :end-before: heat.stack_lifecycle_plugins = :sort: file: input file relative to source directory header: comma separated list of column titles regex: regular expression to parse the source line into columns start-after: string to look for to start column data end-before: string to look for to end column data sort: flag for sorting column data """ required_arguments = 1 option_spec = { 'header': directives.unchanged_required, 'regex': directives.unchanged_required, 'start-after': directives.unchanged_required, 'end-before': directives.unchanged_required, 'sort': directives.flag } def run(self): header = self.options.get('header').split(',') lines = self._get_lines() regex = self.options.get('regex') max_cols = len(header) table = nodes.table() tgroup = nodes.tgroup(max_cols) table += tgroup col_widths = self.get_column_widths(max_cols) tgroup.extend(nodes.colspec(colwidth=col_width) for col_width in col_widths) thead = nodes.thead() tgroup += thead thead += self.create_table_row(header) tbody = nodes.tbody() tgroup += tbody for row in lines: matched = re.search(regex, row) if matched: tbody += self.create_table_row(matched.groups()) return [table] def create_table_row(self, row_cells): row = nodes.row() for cell in row_cells: entry = nodes.entry() row += entry entry += nodes.paragraph(text=cell.strip()) return row def _get_lines(self): env = self.state.document.settings.env sourcefile = os.path.join(env.srcdir, self.arguments[0]) startafter = self.options.get('start-after') endbefore = self.options.get('end-before') lines = [line.strip() for line in open(sourcefile)] if startafter is not None or endbefore is not None: includeline = not startafter result = [] for line in lines: if not includeline and startafter and startafter in line: includeline = True elif includeline and endbefore and endbefore in line: includeline = False break elif includeline: result.append(line) lines = result if 'sort' in self.options: lines = sorted(lines) return lines def setup(app): app.add_directive('table_from_text', TableFromText) heat-6.1.2/doc/source/ext/__init__.py0000664000567000056700000000000013077400531020545 0ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/ext/resources.py0000664000567000056700000003553413077400534021047 0ustar jenkinsjenkins00000000000000# # 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. # -*- coding: utf-8 -*- from functools import cmp_to_key import pydoc from docutils import core from docutils import nodes import six from sphinx.util import compat from heat.common.i18n import _ from heat.engine import attributes from heat.engine import plugin_manager from heat.engine import properties from heat.engine import support _CODE_NAMES = {'2013.1': 'Grizzly', '2013.2': 'Havana', '2014.1': 'Icehouse', '2014.2': 'Juno', '2015.1': 'Kilo', '5.0.0': 'Liberty', '6.0.0': 'Mitaka'} all_resources = {} class integratedrespages(nodes.General, nodes.Element): pass class unsupportedrespages(nodes.General, nodes.Element): pass class contribresourcepages(nodes.General, nodes.Element): pass class ResourcePages(compat.Directive): has_content = False required_arguments = 0 optional_arguments = 1 final_argument_whitespace = False option_spec = {} def path(self): return None def statuses(self): return support.SUPPORT_STATUSES def run(self): prefix = self.arguments and self.arguments.pop() or None content = [] for resource_type, resource_classes in _filter_resources( prefix, self.path(), self.statuses()): for resource_class in resource_classes: self.resource_type = resource_type self.resource_class = resource_class section = self._section(content, resource_type, '%s') self.props_schemata = properties.schemata( self.resource_class.properties_schema) self.attrs_schemata = attributes.schemata( self.resource_class.attributes_schema) # NOTE(prazumovsky): Adding base_attributes_schema dict to # Resource class should means adding new attributes from this # dict to documentation of each resource, else there is no # chance to learn about base attributes. self.attrs_schemata.update( self.resource_class.base_attributes_schema) self.update_policy_schemata = properties.schemata( self.resource_class.update_policy_schema) self._status_str(resource_class.support_status, section) cls_doc = pydoc.getdoc(resource_class) if cls_doc: # allow for rst in the class comments cls_nodes = core.publish_doctree(cls_doc).children section.extend(cls_nodes) self.contribute_properties(section) self.contribute_attributes(section) self.contribute_update_policy(section) self.contribute_hot_syntax(section) return content def _version_str(self, version): if version in _CODE_NAMES: return _("%(version)s (%(code)s)") % {'version': version, 'code': _CODE_NAMES[version]} else: return version def _status_str(self, support_status, section): while support_status is not None: sstatus = support_status.to_dict() if sstatus['status'] is support.SUPPORTED: msg = _('Available') else: msg = sstatus['status'] if sstatus['version'] is not None: msg = _('%(msg)s since %(version)s') % { 'msg': msg, 'version': self._version_str(sstatus['version'])} if sstatus['message'] is not None: msg = _('%(msg)s - %(status_msg)s') % { 'msg': msg, 'status_msg': sstatus['message']} if not (sstatus['status'] == support.SUPPORTED and sstatus['version'] is None): para = nodes.paragraph('', msg) note = nodes.note('', para) section.append(note) support_status = support_status.previous_status def _section(self, parent, title, id_pattern): id = id_pattern % self.resource_type section = nodes.section(ids=[id]) parent.append(section) title = nodes.title('', title) section.append(title) return section def _prop_syntax_example(self, prop): if not prop: return 'Value' if prop.type == properties.Schema.LIST: def schema(i): return prop.schema[i] if prop.schema else None sub_type = [self._prop_syntax_example(schema(i)) for i in range(2)] return '[%s, %s, ...]' % tuple(sub_type) elif prop.type == properties.Schema.MAP: def sub_props(): for sub_key, sub_value in prop.schema.items(): if sub_value.implemented: yield '"%s": %s' % ( sub_key, self._prop_syntax_example(sub_value)) return '{%s}' % (', '.join(sub_props()) if prop.schema else '...') else: return prop.type def contribute_hot_syntax(self, parent): section = self._section(parent, _('HOT Syntax'), '%s-hot') props = [] for prop_key in sorted(six.iterkeys(self.props_schemata)): prop = self.props_schemata[prop_key] if (prop.implemented and prop.support_status.status == support.SUPPORTED): props.append('%s: %s' % (prop_key, self._prop_syntax_example(prop))) props_str = '' if props: props_str = '''\n properties: %s''' % ('\n '.join(props)) template = '''heat_template_version: 2015-04-30 ... resources: ... the_resource: type: %s%s''' % (self.resource_type, props_str) block = nodes.literal_block(template, template, language="yaml") section.append(block) @staticmethod def cmp_prop(x, y): x_key, x_prop = x y_key, y_prop = y if x_prop.support_status.status == y_prop.support_status.status: return (x_key > y_key) - (x_key < y_key) x_status = x_prop.support_status.status y_status = y_prop.support_status.status if x_status == support.SUPPORTED: return -1 if x_status == support.DEPRECATED: return 1 return (x_status > y_status) - (x_status < y_status) def contribute_property(self, parent, prop_key, prop, upd_para=None, id_pattern_prefix=None): if not id_pattern_prefix: id_pattern_prefix = '%s-prop' id_pattern = id_pattern_prefix + '-' + prop_key definition = self._section(parent, prop_key, id_pattern) self._status_str(prop.support_status, definition) if not prop.implemented: para = nodes.paragraph('', _('Not implemented.')) note = nodes.note('', para) definition.append(note) return if prop.description: para = nodes.paragraph('', prop.description) definition.append(para) type = nodes.paragraph('', _('%s value expected.') % prop.type) definition.append(type) if upd_para is not None: definition.append(upd_para) else: if prop.update_allowed: upd_para = nodes.paragraph( '', _('Can be updated without replacement.')) definition.append(upd_para) elif prop.immutable: upd_para = nodes.paragraph('', _('Updates are not supported. ' 'Resource update will fail on' ' any attempt to update this ' 'property.')) definition.append(upd_para) else: upd_para = nodes.paragraph('', _('Updates cause replacement.')) definition.append(upd_para) if prop.default is not None: para = nodes.paragraph('', _('Defaults to "%s".') % prop.default) definition.append(para) for constraint in prop.constraints: para = nodes.paragraph('', str(constraint)) definition.append(para) sub_schema = None if prop.schema and prop.type == properties.Schema.MAP: para = nodes.paragraph() emph = nodes.emphasis('', _('Map properties:')) para.append(emph) definition.append(para) sub_schema = prop.schema elif prop.schema and prop.type == properties.Schema.LIST: para = nodes.paragraph() emph = nodes.emphasis('', _('List contents:')) para.append(emph) definition.append(para) sub_schema = prop.schema if sub_schema: for _key, _prop in sorted(sub_schema.items(), key=cmp_to_key(self.cmp_prop)): if _prop.support_status.status != support.HIDDEN: indent = nodes.block_quote() definition.append(indent) self.contribute_property( indent, _key, _prop, upd_para, id_pattern) def contribute_properties(self, parent): if not self.props_schemata: return props = dict((k, v) for k, v in self.props_schemata.items() if v.support_status.status != support.HIDDEN) required_props = dict((k, v) for k, v in props.items() if v.required) if required_props: section = self._section( parent, _('Required Properties'), '%s-props-req') for prop_key, prop in sorted(required_props.items(), key=cmp_to_key(self.cmp_prop)): self.contribute_property(section, prop_key, prop) optional_props = dict((k, v) for k, v in props.items() if not v.required) if optional_props: section = self._section( parent, _('Optional Properties'), '%s-props-opt') for prop_key, prop in sorted(optional_props.items(), key=cmp_to_key(self.cmp_prop)): self.contribute_property(section, prop_key, prop) def contribute_attributes(self, parent): if not self.attrs_schemata: return section = self._section(parent, _('Attributes'), '%s-attrs') for prop_key, prop in sorted(self.attrs_schemata.items()): if prop.support_status.status != support.HIDDEN: description = prop.description attr_section = self._section( section, prop_key, '%s-attr-' + prop_key) self._status_str(prop.support_status, attr_section) if description: def_para = nodes.paragraph('', description) attr_section.append(def_para) def contribute_update_policy(self, parent): if not self.update_policy_schemata: return section = self._section(parent, _('update_policy'), '%s-updpolicy') for _key, _prop in sorted(self.update_policy_schemata.items(), key=cmp_to_key(self.cmp_prop)): self.contribute_property(section, _key, _prop) class IntegrateResourcePages(ResourcePages): def path(self): return 'heat.engine.resources' def statuses(self): return [support.SUPPORTED] class UnsupportedResourcePages(ResourcePages): def path(self): return 'heat.engine.resources' def statuses(self): return [s for s in support.SUPPORT_STATUSES if s != support.SUPPORTED] class ContribResourcePages(ResourcePages): def path(self): return 'heat.engine.plugins' def _filter_resources(prefix=None, path=None, statuses=None): def not_hidden_match(cls): return cls.support_status.status != support.HIDDEN def prefix_match(name): return prefix is None or name.startswith(prefix) def path_match(cls): return path is None or cls.__module__.startswith(path) def status_match(cls): return cls.support_status.status in statuses statuses = statuses or [] filtered_resources = {} for name in sorted(six.iterkeys(all_resources)): if prefix_match(name): for cls in all_resources.get(name): if (path_match(cls) and status_match(cls) and not_hidden_match(cls)): if filtered_resources.get(name) is not None: filtered_resources[name].append(cls) else: filtered_resources[name] = [cls] return sorted(six.iteritems(filtered_resources)) def _load_all_resources(): manager = plugin_manager.PluginManager('heat.engine.resources') resource_mapping = plugin_manager.PluginMapping('resource') res_plugin_mappings = resource_mapping.load_all(manager) for mapping in res_plugin_mappings: name, cls = mapping if all_resources.get(name) is not None: all_resources[name].append(cls) else: all_resources[name] = [cls] def link_resource(app, env, node, contnode): reftarget = node.attributes['reftarget'] for resource_name in all_resources: if resource_name.lower() == reftarget.lower(): refnode = nodes.reference('', '', internal=True) refnode['reftitle'] = resource_name if resource_name.startswith('AWS'): source = 'template_guide/cfn' else: source = 'template_guide/openstack' uri = app.builder.get_relative_uri( node.attributes['refdoc'], source) refnode['refuri'] = '%s#%s' % (uri, resource_name) refnode.append(contnode) return refnode def setup(app): _load_all_resources() app.add_node(integratedrespages) app.add_directive('integratedrespages', IntegrateResourcePages) app.add_node(unsupportedrespages) app.add_directive('unsupportedrespages', UnsupportedResourcePages) app.add_node(contribresourcepages) app.add_directive('contribrespages', ContribResourcePages) app.connect('missing-reference', link_resource) heat-6.1.2/doc/source/api/0000775000567000056700000000000013077401020016411 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/api/index.rst0000664000567000056700000000014713077400531020262 0ustar jenkinsjenkins00000000000000=================== Source Code Index =================== .. toctree:: :maxdepth: 1 autoindex heat-6.1.2/doc/source/template_guide/0000775000567000056700000000000013077401020020630 5ustar jenkinsjenkins00000000000000heat-6.1.2/doc/source/template_guide/unsupported.rst0000664000567000056700000000135513077400531023764 0ustar jenkinsjenkins00000000000000.. 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. Unsupported Heat Resource Types =============================== .. rubric:: These resources are enabled, but are not officially supported. .. unsupportedrespages:: heat-6.1.2/doc/source/template_guide/cfn.rst0000664000567000056700000000126613077400531022143 0ustar jenkinsjenkins00000000000000.. 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. CloudFormation Compatible Resource Types ---------------------------------------- .. integratedrespages:: AWS:: heat-6.1.2/doc/source/template_guide/software_deployment.rst0000664000567000056700000006474613077400534025506 0ustar jenkinsjenkins00000000000000.. highlight: yaml :linenothreshold: 5 .. _software_deployment: ====================== Software configuration ====================== There are a variety of options to configure the software which runs on the servers in your stack. These can be broadly divided into the following: * Custom image building * User-data boot scripts and cloud-init * Software deployment resources This section will describe each of these options and provide examples for using them together in your stacks. Image building ~~~~~~~~~~~~~~ The first opportunity to influence what software is configured on your servers is by booting them with a custom-built image. There are a number of reasons you might want to do this, including: * **Boot speed** - since the required software is already on the image there is no need to download and install anything at boot time. * **Boot reliability** - software downloads can fail for a number of reasons including transient network failures and inconsistent software repositories. * **Test verification** - custom built images can be verified in test environments before being promoted to production. * **Configuration dependencies** - post-boot configuration may depend on agents already being installed and enabled A number of tools are available for building custom images, including: * diskimage-builder_ image building tools for OpenStack * imagefactory_ builds images for a variety of operating system/cloud combinations Examples in this guide which require custom images will use diskimage-builder_. User-data boot scripts and cloud-init ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When booting a server it is possible to specify the contents of the user-data to be passed to that server. This user-data is made available either from configured config-drive or from the `Metadata service`_. How this user-data is consumed depends on the image being booted, but the most commonly used tool for default cloud images is Cloud-init_. Whether the image is using Cloud-init_ or not, it should be possible to specify a shell script in the ``user_data`` property and have it be executed by the server during boot: .. code-block:: yaml :linenos: resources: the_server: type: OS::Nova::Server properties: # flavor, image etc user_data: | #!/bin/bash echo "Running boot script" # ... .. note:: Debugging these scripts it is often useful to view the boot log using :code:`nova console-log ` to view the progress of boot script execution. Often there is a need to set variable values based on parameters or resources in the stack. This can be done with the :code:`str_replace` intrinsic function: .. code-block:: yaml :linenos: parameters: foo: default: bar resources: the_server: type: OS::Nova::Server properties: # flavor, image etc user_data: str_replace: template: | #!/bin/bash echo "Running boot script with $FOO" # ... params: $FOO: {get_param: foo} .. warning:: If a stack-update is performed and there are any changes at all to the content of user_data then the server will be replaced (deleted and recreated) so that the modified boot configuration can be run on a new server. When these scripts grow it can become difficult to maintain them inside the template, so the ``get_file`` intrinsic function can be used to maintain the script in a separate file: .. code-block:: yaml :linenos: parameters: foo: default: bar resources: the_server: type: OS::Nova::Server properties: # flavor, image etc user_data: str_replace: template: {get_file: the_server_boot.sh} params: $FOO: {get_param: foo} .. note:: ``str_replace`` can replace any strings, not just strings starting with ``$``. However doing this for the above example is useful because the script file can be executed for testing by passing in environment variables. Choosing the user_data_format ----------------------------- The :ref:`OS::Nova::Server` ``user_data_format`` property determines how the ``user_data`` should be formatted for the server. For the default value ``HEAT_CFNTOOLS``, the ``user_data`` is bundled as part of the heat-cfntools cloud-init boot configuration data. While ``HEAT_CFNTOOLS`` is the default for ``user_data_format``, it is considered legacy and ``RAW`` or ``SOFTWARE_CONFIG`` will generally be more appropriate. For ``RAW`` the user_data is passed to Nova unmodified. For a Cloud-init_ enabled image, the following are both valid ``RAW`` user-data: .. code-block:: yaml :linenos: resources: server_with_boot_script: type: OS::Nova::Server properties: # flavor, image etc user_data_format: RAW user_data: | #!/bin/bash echo "Running boot script" # ... server_with_cloud_config: type: OS::Nova::Server properties: # flavor, image etc user_data_format: RAW user_data: | #cloud-config final_message: "The system is finally up, after $UPTIME seconds" For ``SOFTWARE_CONFIG`` ``user_data`` is bundled as part of the software config data, and metadata is derived from any associated `Software deployment resources`_. Signals and wait conditions --------------------------- Often it is necessary to pause further creation of stack resources until the boot configuration script has notified that it has reached a certain state. This is usually either to notify that a service is now active, or to pass out some generated data which is needed by another resource. The resources :ref:`OS::Heat::WaitCondition` and :ref:`OS::Heat::SwiftSignal` both perform this function using different techniques and tradeoffs. :ref:`OS::Heat::WaitCondition` is implemented as a call to the `Orchestration API`_ resource signal. The token is created using credentials for a user account which is scoped only to the wait condition handle resource. This user is created when the handle is created, and is associated to a project which belongs to the stack, in an identity domain which is dedicated to the orchestration service. Sending the signal is a simple HTTP request, as with this example using curl_: .. code-block:: sh curl -i -X POST -H 'X-Auth-Token: ' \ -H 'Content-Type: application/json' -H 'Accept: application/json' \ '' --data-binary '' The JSON containing the signal data is expected to be of the following format: .. code-block:: json { "status": "SUCCESS", "reason": "The reason which will appear in the 'heat event-list' output", "data": "Data to be used elsewhere in the template via get_attr", "id": "Optional unique ID of signal" } All of these values are optional, and if not specified will be set to the following defaults: .. code-block:: json { "status": "SUCCESS", "reason": "Signal received", "data": null, "id": "" } If ``status`` is set to ``FAILURE`` then the resource (and the stack) will go into a ``FAILED`` state using the ``reason`` as failure reason. The following template example uses the convenience attribute ``curl_cli`` which builds a curl command with a valid token: .. code-block:: yaml :linenos: resources: wait_condition: type: OS::Heat::WaitCondition properties: handle: {get_resource: wait_handle} # Note, count of 5 vs 6 is due to duplicate signal ID 5 sent below count: 5 timeout: 300 wait_handle: type: OS::Heat::WaitConditionHandle the_server: type: OS::Nova::Server properties: # flavor, image etc user_data_format: RAW user_data: str_replace: template: | #!/bin/sh # Below are some examples of the various ways signals # can be sent to the Handle resource # Simple success signal wc_notify --data-binary '{"status": "SUCCESS"}' # Or you optionally can specify any of the additional fields wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal2"}' wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal3", "data": "data3"}' wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal4", "id": "id4", "data": "data4"}' # If you require control of the ID, you can pass it. # The ID should be unique, unless you intend for duplicate # signals to overwrite each other. The following two calls # do the exact same thing, and will be treated as one signal # (You can prove this by changing count above to 7) wc_notify --data-binary '{"status": "SUCCESS", "id": "id5"}' wc_notify --data-binary '{"status": "SUCCESS", "id": "id5"}' # Example of sending a failure signal, optionally # reason, id, and data can be specified as above # wc_notify --data-binary '{"status": "FAILURE"}' params: wc_notify: { get_attr: [wait_handle, curl_cli] } outputs: wc_data: value: { get_attr: [wait_condition, data] } # this would return the following json # {"1": null, "2": null, "3": "data3", "id4": "data4", "id5": null} wc_data_4: value: { 'Fn::Select': ['id4', { get_attr: [wait_condition, data] }] } # this would return "data4" .. :ref:`OS::Heat::SwiftSignal` is implemented by creating an Object Storage API temporary URL which is populated with signal data with an HTTP PUT. The orchestration service will poll this object until the signal data is available. Object versioning is used to store multiple signals. Sending the signal is a simple HTTP request, as with this example using curl_: .. code-block:: sh curl -i -X PUT '' --data-binary '' The above template example only needs to have the ``type`` changed to the swift signal resources: .. code-block:: yaml :linenos: resources: signal: type: OS::Heat::SwiftSignal properties: handle: {get_resource: wait_handle} timeout: 300 signal_handle: type: OS::Heat::SwiftSignalHandle # ... The decision to use :ref:`OS::Heat::WaitCondition` or :ref:`OS::Heat::SwiftSignal` will depend on a few factors: * :ref:`OS::Heat::SwiftSignal` depends on the availability of an Object Storage API * :ref:`OS::Heat::WaitCondition` depends on whether the orchestration service has been configured with a dedicated stack domain (which may depend on the availability of an Identity V3 API). * The preference to protect signal URLs with token authentication or a secret webhook URL. Software config resources ------------------------- Boot configuration scripts can also be managed as their own resources. This allows configuration to be defined once and run on multiple server resources. These software-config resources are stored and retrieved via dedicated calls to the `Orchestration API`_. It is not possible to modify the contents of an existing software-config resource, so a stack-update which changes any existing software-config resource will result in API calls to create a new config and delete the old one. The resource :ref:`OS::Heat::SoftwareConfig` is used for storing configs represented by text scripts, for example: .. code-block:: yaml :linenos: resources: boot_script: type: OS::Heat::SoftwareConfig properties: group: ungrouped config: | #!/bin/bash echo "Running boot script" # ... server_with_boot_script: type: OS::Nova::Server properties: # flavor, image etc user_data_format: RAW user_data: {get_resource: boot_script} The resource :ref:`OS::Heat::CloudConfig` allows Cloud-init_ cloud-config to be represented as template YAML rather than a block string. This allows intrinsic functions to be included when building the cloud-config. This also ensures that the cloud-config is valid YAML, although no further checks for valid cloud-config are done. .. code-block:: yaml :linenos: parameters: file_content: type: string description: The contents of the file /tmp/file resources: boot_config: type: OS::Heat::CloudConfig properties: cloud_config: write_files: - path: /tmp/file content: {get_param: file_content} server_with_cloud_config: type: OS::Nova::Server properties: # flavor, image etc user_data_format: RAW user_data: {get_resource: boot_config} The resource :ref:`OS::Heat::MultipartMime` allows multiple :ref:`OS::Heat::SoftwareConfig` and :ref:`OS::Heat::CloudConfig` resources to be combined into a single Cloud-init_ multi-part message: .. code-block:: yaml :linenos: parameters: file_content: type: string description: The contents of the file /tmp/file other_config: type: string description: The ID of a software-config resource created elsewhere resources: boot_config: type: OS::Heat::CloudConfig properties: cloud_config: write_files: - path: /tmp/file content: {get_param: file_content} boot_script: type: OS::Heat::SoftwareConfig properties: group: ungrouped config: | #!/bin/bash echo "Running boot script" # ... server_init: type: OS::Heat::MultipartMime properties: parts: - config: {get_resource: boot_config} - config: {get_resource: boot_script} - config: {get_param: other_config} server: type: OS::Nova::Server properties: # flavor, image etc user_data_format: RAW user_data: {get_resource: server_init} Software deployment resources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are many situations where it is not desirable to replace the server whenever there is a configuration change. The :ref:`OS::Heat::SoftwareDeployment` resource allows any number of software configurations to be added or removed from a server throughout its life-cycle. Building custom image for software deployments ---------------------------------------------- :ref:`OS::Heat::SoftwareConfig` resources are used to store software configuration, and a :ref:`OS::Heat::SoftwareDeployment` resource is used to associate a config resource with one server. The ``group`` attribute on :ref:`OS::Heat::SoftwareConfig` specifies what tool will consume the config content. :ref:`OS::Heat::SoftwareConfig` has the ability to define a schema of ``inputs`` and which the configuration script supports. Inputs are mapped to whatever concept the configuration tool has for assigning variables/parameters. Likewise, ``outputs`` are mapped to the tool's capability to export structured data after configuration execution. For tools which do not support this, outputs can always be written to a known file path for the hook to read. The :ref:`OS::Heat::SoftwareDeployment` resource allows values to be assigned to the config inputs, and the resource remains in an ``IN_PROGRESS`` state until the server signals to heat what (if any) output values were generated by the config script. Custom image script ------------------- Each of the following examples requires that the servers be booted with a custom image. The following script uses diskimage-builder to create an image required in later examples: .. code-block:: sh :linenos: # Clone the required repositories. Some of these are also available # via pypi or as distro packages. git clone https://git.openstack.org/openstack/diskimage-builder.git git clone https://git.openstack.org/openstack/tripleo-image-elements.git git clone https://git.openstack.org/openstack/heat-templates.git # Required by diskimage-builder to discover element collections export ELEMENTS_PATH=tripleo-image-elements/elements:heat-templates/hot/software-config/elements # The base operating system element(s) provided by the diskimage-builder # elements collection. Other values which may work include: # centos7, debian, opensuse, rhel, rhel7, or ubuntu export BASE_ELEMENTS="fedora selinux-permissive" # Install and configure the os-collect-config agent to poll the heat service # for configuration changes to execute export AGENT_ELEMENTS="os-collect-config os-refresh-config os-apply-config" # heat-config installs an os-refresh-config script which will invoke the # appropriate hook to perform configuration. The element heat-config-script # installs a hook to perform configuration with shell scripts export DEPLOYMENT_BASE_ELEMENTS="heat-config heat-config-script" # Install a hook for any other chosen configuration tool(s). # Elements which install hooks include: # heat-config-cfn-init, heat-config-puppet, or heat-config-salt export DEPLOYMENT_TOOL="" # The name of the qcow2 image to create, and the name of the image # uploaded to the OpenStack image registry. export IMAGE_NAME=fedora-software-config # Create the image diskimage-builder/bin/disk-image-create vm $BASE_ELEMENTS $AGENT_ELEMENTS \ $DEPLOYMENT_BASE_ELEMENTS $DEPLOYMENT_TOOL -o $IMAGE_NAME.qcow2 # Upload the image, assuming valid credentials are already sourced glance image-create --disk-format qcow2 --container-format bare \ --name $IMAGE_NAME < $IMAGE_NAME.qcow2 Configuring with scripts ------------------------ The `Custom image script`_ already includes the ``heat-config-script`` element so the built image will already have the ability to configure using shell scripts. Config inputs are mapped to shell environment variables. The script can communicate outputs to heat by writing to the :file:`$heat_outputs_path.{output name}` file. See the following example for a script which expects inputs ``foo``, ``bar`` and generates an output ``result``. .. code-block:: yaml :linenos: resources: config: type: OS::Heat::SoftwareConfig properties: group: script inputs: - name: foo - name: bar outputs: - name: result config: | #!/bin/sh -x echo "Writing to /tmp/$bar" echo $foo > /tmp/$bar echo -n "The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action" > $heat_outputs_path.result echo "Written to /tmp/$bar" echo "Output to stderr" 1>&2 deployment: type: OS::Heat::SoftwareDeployment properties: config: get_resource: config server: get_resource: server input_values: foo: fooooo bar: baaaaa server: type: OS::Nova::Server properties: # flavor, image etc user_data_format: SOFTWARE_CONFIG outputs: result: value: get_attr: [deployment, result] stdout: value: get_attr: [deployment, deploy_stdout] stderr: value: get_attr: [deployment, deploy_stderr] status_code: value: get_attr: [deployment, deploy_status_code] .. note:: A config resource can be associated with multiple deployment resources, and each deployment can specify the same or different values for the ``server`` and ``input_values`` properties. As can be seen in the ``outputs`` section of the above template, the ``result`` config output value is available as an attribute on the ``deployment`` resource. Likewise the captured stdout, stderr and status_code are also available as attributes. Configuring with os-apply-config -------------------------------- The agent toolchain of ``os-collect-config``, ``os-refresh-config`` and ``os-apply-config`` can actually be used on their own to inject heat stack configuration data into a server running a custom image. The custom image needs to have the following to use this approach: * All software dependencies installed * os-refresh-config_ scripts to be executed on configuration changes * os-apply-config_ templates to transform the heat-provided config data into service configuration files The projects tripleo-image-elements_ and tripleo-heat-templates_ demonstrate this approach. Configuring with cfn-init ------------------------- Likely the only reason to use the ``cfn-init`` hook is to migrate templates which contain `AWS::CloudFormation::Init`_ metadata without needing a complete rewrite of the config metadata. It is included here as it introduces a number of new concepts. To use the ``cfn-init`` tool the ``heat-config-cfn-init`` element is required to be on the built image, so `Custom image script`_ needs to be modified with the following: .. code-block:: sh export DEPLOYMENT_TOOL="heat-config-cfn-init" Configuration data which used to be included in the ``AWS::CloudFormation::Init`` section of resource metadata is instead moved to the ``config`` property of the config resource, as in the following example: .. code-block:: yaml :linenos: resources: config: type: OS::Heat::StructuredConfig properties: group: cfn-init inputs: - name: bar config: config: files: /tmp/foo: content: get_input: bar mode: '000644' deployment: type: OS::Heat::StructuredDeployment properties: name: 10_deployment signal_transport: NO_SIGNAL config: get_resource: config server: get_resource: server input_values: bar: baaaaa other_deployment: type: OS::Heat::StructuredDeployment properties: name: 20_other_deployment signal_transport: NO_SIGNAL config: get_resource: config server: get_resource: server input_values: bar: barmy server: type: OS::Nova::Server properties: image: {get_param: image} flavor: {get_param: flavor} key_name: {get_param: key_name} user_data_format: SOFTWARE_CONFIG There are a number of things to note about this template example: * :ref:`OS::Heat::StructuredConfig` is like :ref:`OS::Heat::SoftwareConfig` except that the ``config`` property contains structured YAML instead of text script. This is useful for a number of other configuration tools including ansible, salt and os-apply-config. * ``cfn-init`` has no concept of inputs, so ``{get_input: bar}`` acts as a placeholder which gets replaced with the :ref:`OS::Heat::StructuredDeployment` ``input_values`` value when the deployment resource is created. * ``cfn-init`` has no concept of outputs, so specifying ``signal_transport: NO_SIGNAL`` will mean that the deployment resource will immediately go into the ``CREATED`` state instead of waiting for a completed signal from the server. * The template has 2 deployment resources deploying the same config with different ``input_values``. The order these are deployed in on the server is determined by sorting the values of the ``name`` property for each resource (10_deployment, 20_other_deployment) Configuring with puppet ----------------------- The puppet_ hook makes it possible to write configuration as puppet manifests which are deployed and run in a masterless environment. To specify configuration as puppet manifests the ``heat-config-puppet`` element is required to be on the built image, so `Custom image script`_ needs to be modified with the following: .. code-block:: sh export DEPLOYMENT_TOOL="heat-config-puppet" .. code-block:: yaml :linenos: resources: config: type: OS::Heat::SoftwareConfig properties: group: puppet inputs: - name: foo - name: bar outputs: - name: result config: get_file: example-puppet-manifest.pp deployment: type: OS::Heat::SoftwareDeployment properties: config: get_resource: config server: get_resource: server input_values: foo: fooooo bar: baaaaa server: type: OS::Nova::Server properties: image: {get_param: image} flavor: {get_param: flavor} key_name: {get_param: key_name} user_data_format: SOFTWARE_CONFIG outputs: result: value: get_attr: [deployment, result] stdout: value: get_attr: [deployment, deploy_stdout] This demonstrates the use of the ``get_file`` function, which will attach the contents of the file ``example-puppet-manifest.pp``, containing: .. code-block:: puppet :linenos: file { 'barfile': ensure => file, mode => '0644', path => '/tmp/$::bar', content => '$::foo', } file { 'output_result': ensure => file, path => '$::heat_outputs_path.result', mode => '0644', content => 'The file /tmp/$::bar contains $::foo', } .. _`AWS::CloudFormation::Init`: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html .. _diskimage-builder: https://git.openstack.org/cgit/openstack/diskimage-builder .. _imagefactory: http://imgfac.org/ .. _`Metadata service`: http://docs.openstack.org/admin-guide-cloud/compute-networking-nova.html#metadata-service .. _Cloud-init: http://cloudinit.readthedocs.org/en/latest/ .. _curl: http://curl.haxx.se/ .. _`Orchestration API`: http://developer.openstack.org/api-ref-orchestration-v1.html .. _os-refresh-config: https://git.openstack.org/cgit/openstack/os-refresh-config .. _os-apply-config: https://git.openstack.org/cgit/openstack/os-apply-config .. _tripleo-heat-templates: https://git.openstack.org/cgit/openstack/tripleo-heat-templates .. _tripleo-image-elements: https://git.openstack.org/cgit/openstack/tripleo-image-elements .. _puppet: http://puppetlabs.com/ heat-6.1.2/doc/source/template_guide/index.rst0000664000567000056700000000155513077400531022505 0ustar jenkinsjenkins00000000000000.. 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. .. _template-guide: Template Guide ============== .. toctree:: :maxdepth: 2 hot_guide hello_world hot_spec basic_resources software_deployment environment composition openstack cfn unsupported contrib functions .. existing_templates .. advanced_topics heat-6.1.2/doc/source/template_guide/advanced_topics.rst0000664000567000056700000000044513077400531024521 0ustar jenkinsjenkins00000000000000:orphan: .. _advanced_topics: =============== Advanced topics =============== Networking ~~~~~~~~~~ Load balancer ------------- TODO Firewall -------- TODO VPN --- TODO Auto scaling ~~~~~~~~~~~~ Alarming -------- TODO Up scaling and down scaling --------------------------- TODO heat-6.1.2/doc/source/template_guide/contrib.rst0000664000567000056700000000346313077400531023036 0ustar jenkinsjenkins00000000000000.. 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. Contributed Heat Resource Types =============================== .. rubric:: These resources are not enabled by default. .. contribrespages:: OS:: Rackspace Cloud Resource Types ------------------------------ .. rubric:: These resources are not enabled by default. The resources in this module are for using Heat with the Rackspace Cloud. These resources either allow using Rackspace services that don't have equivalent services in OpenStack or account for differences between a generic OpenStack deployment and the Rackspace Cloud. Rackspace resources depend on the dev branch of `pyrax `_ to work properly. More information about them can be found in the `RACKSPACE_README `_. .. contribrespages:: Rackspace:: DockerInc Resource ------------------ .. rubric:: This resource is not enabled by default. This plugin enables the use of Docker containers in a Heat template and requires the `docker-py `_ package. You can find more information in the `DOCKER_README `_. .. contribrespages:: DockerInc:: heat-6.1.2/doc/source/template_guide/hot_guide.rst0000664000567000056700000002107513077400534023347 0ustar jenkinsjenkins00000000000000.. 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. .. code-block:: yaml heat_template_version: 2015-04-30 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 a valid version of HOT, e.g. 2015-10-15 (see :ref:`hot_spec_template_version` for a list of all versions). 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: .. code-block:: yaml 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: .. code-block:: yaml heat_template_version: 2015-04-30 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. .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml parameters: instance_type: type: string label: Instance Type description: Type of instance (flavor) to be used constraints: - allowed_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: .. code-block:: yaml 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: .. code-block:: yaml 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`). heat-6.1.2/doc/source/template_guide/functions.rst0000664000567000056700000001526213077400534023411 0ustar jenkinsjenkins00000000000000.. 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. =================================== CloudFormation Compatible Functions =================================== There are a number of functions that you can use to help you write CloudFormation compatible templates. While most CloudFormation functions are supported in HOT version '2013-05-23', *Fn::Select* is the only CloudFormation function supported in HOT templates since version '2014-10-16' which is introduced in Juno. All of these functions (except *Ref*) start with *Fn::*. --- Ref --- Returns the value of the named parameter or resource. Parameters ~~~~~~~~~~ name : String The name of the resource or parameter. Usage ~~~~~ .. code-block:: yaml {Ref: my_server} Returns the nova instance ID. For example, ``d8093de0-850f-4513-b202-7979de6c0d55``. ---------- Fn::Base64 ---------- This is a placeholder for a function to convert an input string to Base64. This function in Heat actually performs no conversion. It is included for the benefit of CFN templates that convert UserData to Base64. Heat only accepts UserData in plain text. Parameters ~~~~~~~~~~ value : String The string to convert. Usage ~~~~~ .. code-block:: yaml {"Fn::Base64": "convert this string please."} Returns the original input string. ------------- Fn::FindInMap ------------- Returns the value corresponding to keys into a two-level map declared in the Mappings section. Parameters ~~~~~~~~~~ map_name : String The logical name of a mapping declared in the Mappings section that contains the keys and values. top_level_key : String The top-level key name. It's value is a list of key-value pairs. second_level_key : String The second-level key name, which is set to one of the keys from the list assigned to top_level_key. Usage ~~~~~ .. code-block:: yaml Mapping: MyContacts: jone: {phone: 337, email: a@b.com} jim: {phone: 908, email: g@b.com} {"Fn::FindInMap": ["MyContacts", "jim", "phone" ] } Returns ``908``. ---------- Fn::GetAtt ---------- Returns an attribute of a resource within the template. Parameters ~~~~~~~~~~ resource : String The name of the resource. attribute : String The name of the attribute. Usage ~~~~~ .. code-block:: yaml {Fn::GetAtt: [my_server, PublicIp]} Returns an IP address such as ``10.0.0.2``. ---------- Fn::GetAZs ---------- Returns the Availability Zones within the given region. *Note: AZ's and regions are not fully implemented in Heat.* Parameters ~~~~~~~~~~ region : String The name of the region. Usage ~~~~~ .. code-block:: yaml {Fn::GetAZs: ""} Returns the list provided by ``nova availability-zone-list``. -------- Fn::Join -------- Like python join, it joins a list of strings with the given delimiter. Parameters ~~~~~~~~~~ delimiter : String The string to join the list with. list : list The list to join. Usage ~~~~~ .. code-block:: yaml {Fn::Join: [",", ["beer", "wine", "more beer"]]} Returns ``beer, wine, more beer``. ---------- Fn::Select ---------- Select an item from a list. *Heat extension: Select an item from a map* Parameters ~~~~~~~~~~ selector : string or integer The number of item in the list or the name of the item in the map. collection : map or list The collection to select the item from. Usage ~~~~~ For a list lookup: .. code-block:: yaml { "Fn::Select" : [ "2", [ "apples", "grapes", "mangoes" ] ] } Returns ``mangoes``. For a map lookup: .. code-block:: yaml { "Fn::Select" : [ "red", {"red": "a", "flu": "b"} ] } Returns ``a``. --------- Fn::Split --------- This is the reverse of Join. Convert a string into a list based on the delimiter. Parameters ~~~~~~~~~~ delimiter : string Matching string to split on. string : String The string to split. Usage ~~~~~ .. code-block:: yaml { "Fn::Split" : [ ",", "str1,str2,str3,str4"]} Returns ``{["str1", "str2", "str3", "str4"]}``. ----------- Fn::Replace ----------- Find and replace one string with another. Parameters ~~~~~~~~~~ substitutions : map A map of substitutions. string: String The string to do the substitutions in. Usage ~~~~~ .. code-block:: yaml {"Fn::Replace": [ {'$var1': 'foo', '%var2%': 'bar'}, '$var1 is %var2%' ]} Returns ``"foo is bar"``. ------------------ Fn::ResourceFacade ------------------ When writing a Template Resource: - user writes a template that will fill in for a resource (the resource is the facade). - when they are writing their template they need to access the metadata from the facade. Parameters ~~~~~~~~~~ attribute_name : String One of ``Metadata``, ``DeletionPolicy`` or ``UpdatePolicy``. Usage ~~~~~ .. code-block:: yaml {'Fn::ResourceFacade': 'Metadata'} {'Fn::ResourceFacade': 'DeletionPolicy'} {'Fn::ResourceFacade': 'UpdatePolicy'} Example ~~~~~~~ Here is a top level template ``top.yaml`` .. code-block:: yaml resources: my_server: type: OS::Nova::Server metadata: key: value some: more stuff Here is a resource template ``my_actual_server.yaml`` .. code-block:: yaml resources: _actual_server_: type: OS::Nova::Server metadata: {'Fn::ResourceFacade': Metadata} The environment file ``env.yaml`` .. code-block:: yaml resource_registry: resources: my_server: "OS::Nova::Server": my_actual_server.yaml To use it :: $ heat stack-create -f top.yaml -e env.yaml What happened is the metadata in ``top.yaml`` (key: value, some: more stuff) gets passed into the resource template via the `Fn::ResourceFacade`_ function. ------------------- Fn::MemberListToMap ------------------- Convert an AWS style member list into a map. Parameters ~~~~~~~~~~ key name: string The name of the key (normally "Name" or "Key"). value name: string The name of the value (normally "Value"). list: A list of strings The string to convert. Usage ~~~~~ .. code-block:: yaml {'Fn::MemberListToMap': ['Name', 'Value', ['.member.0.Name=key', '.member.0.Value=door', '.member.1.Name=colour', '.member.1.Value=green']]} Returns ``{'key': 'door', 'colour': 'green'}``. heat-6.1.2/doc/source/template_guide/openstack.rst0000664000567000056700000000122613077400531023360 0ustar jenkinsjenkins00000000000000.. 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. OpenStack Resource Types ------------------------ .. integratedrespages:: OS:: heat-6.1.2/doc/source/template_guide/basic_resources.rst0000664000567000056700000003262313077400534024554 0ustar jenkinsjenkins00000000000000.. highlight: yaml :linenothreshold: 5 .. _basic_resources: ========= Instances ========= .. For consistency let's define a few values to use in the samples: * image name: ubuntu-trusty-x86_64 * shared/provider network name: "public" * tenant network and subnet names: "private" and "private-subnet" Manage instances ~~~~~~~~~~~~~~~~ Create an instance ------------------ Use the :ref:`OS::Nova::Server` resource to create a Compute instance. The ``flavor`` property is the only mandatory one, but you need to define a boot source using one of the ``image`` or ``block_device_mapping`` properties. You also need to define the ``networks`` property to indicate to which networks your instance must connect if multiple networks are available in your tenant. The following example creates a simple instance, booted from an image, and connecting to the ``private`` network: .. code-block:: yaml :linenos: resources: instance: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 networks: - network: private Connect an instance to a network -------------------------------- Use the ``networks`` property of an :ref:`OS::Nova::Server` resource to define which networks an instance should connect to. Define each network as a YAML map, containing one of the following keys: ``port`` The ID of an existing Networking port. You usually create this port in the same template using an :ref:`OS::Neutron::Port` resource. You will be able to associate a floating IP to this port, and the port to your Compute instance. ``network`` The name or ID of an existing network. You don't need to create an :ref:`OS::Neutron::Port` resource if you use this property. But you will not be able to use neutron floating IP association for this instance because there will be no specified port for server. The following example demonstrates the use of the ``port`` and ``network`` properties: .. code-block:: yaml :linenos: resources: instance_port: type: OS::Neutron::Port properties: network: private fixed_ips: - subnet_id: "private-subnet" instance1: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 networks: - port: { get_resource: instance_port } instance2: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 networks: - network: private Create and associate security groups to an instance --------------------------------------------------- Use the :ref:`OS::Neutron::SecurityGroup` resource to create security groups. Define the ``security_groups`` property of the :ref:`OS::Neutron::Port` resource to associate security groups to a port, then associate the port to an instance. The following example creates a security group allowing inbound connections on ports 80 and 443 (web server) and associates this security group to an instance port: .. code-block:: yaml :linenos: resources: web_secgroup: type: OS::Neutron::SecurityGroup properties: rules: - protocol: tcp remote_ip_prefix: 0.0.0.0/0 port_range_min: 80 port_range_max: 80 - protocol: tcp remote_ip_prefix: 0.0.0.0/0 port_range_min: 443 port_range_max: 443 instance_port: type: OS::Neutron::Port properties: network: private security_groups: - default - { get_resource: web_secgroup } fixed_ips: - subnet_id: private-subnet instance: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 networks: - port: { get_resource: instance_port } Create and associate a floating IP to an instance ------------------------------------------------- You can use two sets of resources to create and associate floating IPs to instances. OS::Nova resources ++++++++++++++++++ Use the :ref:`OS::Nova::FloatingIP` resource to create a floating IP, and the :ref:`OS::Nova::FloatingIPAssociation` resource to associate the floating IP to an instance. The following example creates an instance and a floating IP, and associate the floating IP to the instance: .. code-block:: yaml :linenos: resources: floating_ip: type: OS::Nova::FloatingIP properties: pool: public inst1: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 networks: - network: private association: type: OS::Nova::FloatingIPAssociation properties: floating_ip: { get_resource: floating_ip } server_id: { get_resource: inst1 } OS::Neutron resources +++++++++++++++++++++ .. note:: The Networking service (neutron) must be enabled on your OpenStack deployment to use these resources. Use the :ref:`OS::Neutron::FloatingIP` resource to create a floating IP, and the :ref:`OS::Neutron::FloatingIPAssociation` resource to associate the floating IP to a port: .. code-block:: yaml :linenos: parameters: net: description: name of network used to launch instance. type: string default: private resources: inst1: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 networks: - network: {get_param: net} floating_ip: type: OS::Neutron::FloatingIP properties: floating_network: public association: type: OS::Neutron::FloatingIPAssociation properties: floatingip_id: { get_resource: floating_ip } port_id: {get_attr: [inst1, addresses, {get_param: net}, 0, port]} You can also create an OS::Neutron::Port and associate that with the server and the floating IP. However the approach mentioned above will work better with stack updates. .. code-block:: yaml :linenos: resources: instance_port: type: OS::Neutron::Port properties: network: private fixed_ips: - subnet_id: "private-subnet" floating_ip: type: OS::Neutron::FloatingIP properties: floating_network: public association: type: OS::Neutron::FloatingIPAssociation properties: floatingip_id: { get_resource: floating_ip } port_id: { get_resource: instance_port } Enable remote access to an instance ----------------------------------- The ``key_name`` attribute of the :ref:`OS::Nova::Server` resource defines the key pair to use to enable SSH remote access: .. code-block:: yaml :linenos: resources: my_instance: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 key_name: my_key .. note:: For more information about key pairs, see `Configure access and security for instances `_. Create a key pair ----------------- You can create new key pairs with the :ref:`OS::Nova::KeyPair` resource. Key pairs can be imported or created during the stack creation. If the ``public_key`` property is not specified, the Orchestration module creates a new key pair. If the ``save_private_key`` property is set to ``true``, the ``private_key`` attribute of the resource holds the private key. The following example creates a new key pair and uses it as authentication key for an instance: .. code-block:: yaml :linenos: resources: my_key: type: OS::Nova::KeyPair properties: save_private_key: true name: my_key my_instance: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 key_name: { get_resource: my_key } outputs: private_key: description: Private key value: { get_attr: [ my_key, private_key ] } Manage networks ~~~~~~~~~~~~~~~ Create a network and a subnet ----------------------------- .. note:: The Networking service (neutron) must be enabled on your OpenStack deployment to create and manage networks and subnets. Networks and subnets cannot be created if your deployment uses legacy networking (nova-network). Use the :ref:`OS::Neutron::Net` resource to create a network, and the :ref:`OS::Neutron::Subnet` resource to provide a subnet for this network: .. code-block:: yaml :linenos: resources: new_net: type: OS::Neutron::Net new_subnet: type: OS::Neutron::Subnet properties: network_id: { get_resource: new_net } cidr: "10.8.1.0/24" dns_nameservers: [ "8.8.8.8", "8.8.4.4" ] ip_version: 4 Create and manage a router -------------------------- Use the :ref:`OS::Neutron::Router` resource to create a router. You can define its gateway with the ``external_gateway_info`` property: .. code-block:: yaml :linenos: resources: router1: type: OS::Neutron::Router properties: external_gateway_info: { network: public } You can connect subnets to routers with the :ref:`OS::Neutron::RouterInterface` resource: .. code-block:: yaml :linenos: resources: subnet1_interface: type: OS::Neutron::RouterInterface properties: router_id: { get_resource: router1 } subnet: private-subnet Complete network example ------------------------ The following example creates a network stack: * A network and an associated subnet. * A router with an external gateway. * An interface to the new subnet for the new router. In this example, the ``public`` network is an existing shared network: .. code-block:: yaml :linenos: resources: internal_net: type: OS::Neutron::Net internal_subnet: type: OS::Neutron::Subnet properties: network_id: { get_resource: internal_net } cidr: "10.8.1.0/24" dns_nameservers: [ "8.8.8.8", "8.8.4.4" ] ip_version: 4 internal_router: type: OS::Neutron::Router properties: external_gateway_info: { network: public } internal_interface: type: OS::Neutron::RouterInterface properties: router_id: { get_resource: internal_router } subnet: { get_resource: internal_subnet } Manage volumes ~~~~~~~~~~~~~~ Create a volume --------------- Use the :ref:`OS::Cinder::Volume` resource to create a new Block Storage volume. For example: .. code-block:: yaml :linenos: resources: my_new_volume: type: OS::Cinder::Volume properties: size: 10 The volumes that you create are empty by default. Use the ``image`` property to create a bootable volume from an existing image: .. code-block:: yaml :linenos: resources: my_new_bootable_volume: type: OS::Cinder::Volume properties: size: 10 image: ubuntu-trusty-x86_64 You can also create new volumes from another volume, a volume snapshot, or a volume backup. Use the ``source_volid``, ``snapshot_id`` or ``backup_id`` properties to create a new volume from an existing source. For example, to create a new volume from a backup: .. code-block:: yaml :linenos: resources: another_volume: type: OS::Cinder::Volume properties: backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868 In this example the ``size`` property is not defined because the Block Storage service uses the size of the backup to define the size of the new volume. Attach a volume to an instance ------------------------------ Use the :ref:`OS::Cinder::VolumeAttachment` resource to attach a volume to an instance. The following example creates a volume and an instance, and attaches the volume to the instance: .. code-block:: yaml :linenos: resources: new_volume: type: OS::Cinder::Volume properties: size: 1 new_instance: type: OS::Nova::Server properties: flavor: m1.small image: ubuntu-trusty-x86_64 volume_attachment: type: OS::Cinder::VolumeAttachment properties: volume_id: { get_resource: new_volume } instance_uuid: { get_resource: new_instance } Boot an instance from a volume ------------------------------ Use the ``block_device_mapping`` property of the :ref:`OS::Nova::Server` resource to define a volume used to boot the instance. This property is a list of volumes to attach to the instance before its boot. The following example creates a bootable volume from an image, and uses it to boot an instance: .. code-block:: yaml :linenos: resources: bootable_volume: type: OS::Cinder::Volume properties: size: 10 image: ubuntu-trusty-x86_64 instance: type: OS::Nova::Server properties: flavor: m1.small networks: - network: private block_device_mapping: - device_name: vda volume_id: { get_resource: bootable_volume } delete_on_termination: false .. TODO A few elements that probably belong here: - OS::Swift::Container - OS::Trove::Instance heat-6.1.2/doc/source/template_guide/environment.rst0000664000567000056700000002005713077400534023743 0ustar jenkinsjenkins00000000000000.. highlight: yaml :linenothreshold: 5 .. 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. .. _environments: ============ Environments ============ The environment affects the runtime behavior of a template. It provides a way to override the resource implementations and a mechanism to place parameters that the service needs. To fully understand the runtime behavior you have to consider what plug-ins are installed on the cloud you're using. Environment file format ~~~~~~~~~~~~~~~~~~~~~~~ The environment is a yaml text file that contains two main sections: ``parameters`` A list of key/value pairs. ``resource_registry`` Definition of custom resources. Use the :option:`-e` option of the :command:`heat stack-create` command to create a stack using the environment defined in such a file. You can also provide environment parameters as a list of key/value pairs using the :option:`-P` option of the :command:`heat stack-create` command. In the following example the environment is read from the :file:`my_env.yaml` file and an extra parameter is provided using the :option:`-P` option:: $ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml Global and effective environments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The environment used for a stack is the combination of the environment you use with the template for the stack, and a global environment that is determined by your cloud operator. An entry in the user environment takes precedence over the global environment. OpenStack includes a default global environment, but your cloud operator can add additional environment entries. The cloud operator can add to the global environment by putting environment files in a configurable directory wherever the Orchestration engine runs. The configuration variable is named ``environment_dir`` and is found in the ``[DEFAULT]`` section of :file:`/etc/heat/heat.conf`. The default for that directory is :file:`/etc/heat/environment.d`. Its contents are combined in whatever order the shell delivers them when the service starts up, which is the time when these files are read. If the :file:`my_env.yaml` file from the example above had been put in the ``environment_dir`` then the user's command line could be this:: heat stack-create my_stack -P "some_parm=bla" -f my_tmpl.yaml Usage examples ~~~~~~~~~~~~~~ Define values for template arguments ------------------------------------ You can define values for the template arguments in the ``parameters`` section of an environment file:: parameters: KeyName: heat_key InstanceType: m1.micro ImageId: F18-x86_64-cfntools Define defaults to parameters -------------------------------- You can define default values for all template arguments in the ``parameter_defaults`` section of an environment file. These defaults are passed into all template resources:: parameter_defaults: KeyName: heat_key Mapping resources ----------------- You can map one resource to another in the ``resource_registry`` section of an environment file. The resource you provide in this manner must have an identifier, and must reference either another resource's ID or the URL of an existing template file. The following example maps a new ``OS::Networking::FloatingIP`` resource to an existing ``OS::Nova::FloatingIP`` resource:: resource_registry: "OS::Networking::FloatingIP": "OS::Nova::FloatingIP" You can use wildcards to map multiple resources, for example to map all ``OS::Neutron`` resources to ``OS::Network``:: resource_registry: "OS::Network*": "OS::Neutron*" Override a resource with a custom resource ------------------------------------------ To create or override a resource with a custom resource, create a template file to define this resource, and provide the URL to the template file in the environment file:: resource_registry: "AWS::EC2::Instance": file:///path/to/my_instance.yaml The supported URL schemes are ``file``, ``http`` and ``https``. .. note:: The template file extension must be ``.yaml`` or ``.template``, or it will not be treated as a custom template resource. You can limit the usage of a custom resource to a specific resource of the template:: resource_registry: resources: my_db_server: "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml Pause stack creation, update or deletion on a given resource ------------------------------------------------------------ If you want to debug your stack as it's being created, updated or deleted, or if you want to run it in phases, you can set ``pre-create``, ``pre-update``, ``pre-delete``, ``post-create``, ``post-update`` and ``post-delete`` hooks in the ``resources`` section of ``resource_registry``. To set a hook, add either ``hooks: $hook_name`` (for example ``hooks: pre-update``) to the resource's dictionary. You can also use a list (``hooks: [pre-create, pre-update]``) to stop on several actions. You can combine hooks with other ``resources`` properties such as provider templates or type mapping:: resource_registry: resources: my_server: "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml hooks: pre-create nested_stack: nested_resource: hooks: pre-update another_resource: hooks: [pre-create, pre-update] When heat encounters a resource that has a hook, it pauses the resource action until the hook clears. Any resources that depend on the paused action wait as well. Non-dependent resources are created in parallel unless they have their own hooks. It is possible to perform a wild card match using an asterisk (`*`) in the resource name. For example, the following entry pauses while creating ``app_server`` and ``database_server``, but not ``server`` or ``app_network``:: resource_registry: resources: "*_server": hooks: pre-create Clear hooks by signaling the resource with ``{unset_hook: $hook_name}`` (for example ``{unset_hook: pre-update}``). Retrieving events ----------------- By default events are stored in the database and can be retrieved via the API. Using the environment, you can register an endpoint which will receive events produced by your stack, so that you don't have to poll Heat. You can specify endpoints using the ``event_sinks`` property:: event_sinks: - type: zaqar-queue target: myqueue ttl: 1200 Restrict update or replace of a given resource ----------------------------------------------- If you want to restrict update or replace of a resource when your stack is being updated, you can set ``restricted_actions`` in the ``resources`` section of ``resource_registry``. To restrict update or replace, add ``restricted_actions: update`` or ``restricted_actions: replace`` to the resource dictionary. You can also use ``[update, replace]`` to restrict both actions. You can combine restrcited actions with other ``resources`` properties such as provider templates or type mapping or hooks:: resource_registry: resources: my_server: "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml restricted_actions: replace hooks: pre-create nested_stack: nested_resource: restricted_actions: update another_resource: restricted_actions: [update, replace] It is possible to perform a wild card match using an asterisk (`*`) in the resource name. For example, the following entry restricts replace for ``app_server`` and ``database_server``, but not ``server`` or ``app_network``:: resource_registry: resources: "*_server": restricted_actions: replace heat-6.1.2/doc/source/template_guide/composition.rst0000664000567000056700000001163213077400534023741 0ustar jenkinsjenkins00000000000000.. highlight: yaml :linenothreshold: 5 .. 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. .. _composition: ==================== Template composition ==================== When writing complex templates you are encouraged to break up your template into separate smaller templates. These can then be brought together using template resources. This is a mechanism to define a resource using a template, thus composing one logical stack with multiple templates. Template resources provide a feature similar to the :ref:`AWS::CloudFormation::Stack` resource, but also provide a way to: * Define new resource types and build your own resource library. * Override the default behavior of existing resource types. To achieve this: * The Orchestration client gets the associated template files and passes them along in the ``files`` section of the ``POST stacks/`` API request. * The environment in the Orchestration engine manages the mapping of resource type to template creation. * The Orchestration engine translates template parameters into resource properties. The following examples illustrate how you can use a custom template to define new types of resources. These examples use a custom template stored in a :file:`my_nova.yaml` file .. code-block:: yaml heat_template_version: 2015-04-30 parameters: key_name: type: string description: Name of a KeyPair resources: server: type: OS::Nova::Server properties: key_name: {get_param: key_name} flavor: m1.small image: ubuntu-trusty-x86_64 Use the template filename as type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following template defines the :file:`my_nova.yaml` file as value for the ``type`` property of a resource .. code-block:: yaml heat_template_version: 2015-04-30 resources: my_server: type: my_nova.yaml properties: key_name: my_key The ``key_name`` argument of the ``my_nova.yaml`` template gets its value from the ``key_name`` property of the new template. .. note:: The above reference to :file:`my_nova.yaml` assumes it is in the same directory. You can use any of the following forms: * Relative path (:file:`my_nova.yaml`) * Absolute path (:file:`file:///home/user/templates/my_nova.yaml`) * Http URL (``http://example.com/templates/my_nova.yaml``) * Https URL (``https://example.com/templates/my_nova.yaml``) To create the stack run:: $ heat stack-create -f main.yaml stack1 Define a new resource type ~~~~~~~~~~~~~~~~~~~~~~~~~~ You can associate a name to the :file:`my_nova.yaml` template in an environment file. If the name is already known by the Orchestration module then your new resource will override the default one. In the following example a new ``OS::Nova::Server`` resource overrides the default resource of the same name. An :file:`env.yaml` environment file holds the definition of the new resource .. code-block:: yaml resource_registry: "OS::Nova::Server": my_nova.yaml .. note:: See :ref:`environments` for more detail about environment files. You can now use the new ``OS::Nova::Server`` in your new template .. code-block:: yaml heat_template_version: 2015-04-30 resources: my_server: type: OS::Nova::Server properties: key_name: my_key To create the stack run:: $ heat stack-create -f main.yaml -e env.yaml example-two Get access to nested attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are implicit attributes of a template resource. Accessing nested attributes requires ``heat_template_version`` 2014-10-16 or higher. These are accessible as follows .. code-block:: yaml heat_template_version: 2015-04-30 resources: my_server: type: my_nova.yaml outputs: test_out: value: {get_attr: my_server, resource.server, first_address} Making your template resource more "transparent" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: Available since 2015.1 (Kilo). If you wish to be able to return the ID of one of the inner resources instead of the nested stack's identifier, you can add the special reserved output ``OS::stack_id`` to your template resource .. code-block:: yaml heat_template_version: 2015-04-30 resources: server: type: OS::Nova::Server outputs: OS::stack_id: value: {get_resource: server} Now when you use ``get_resource`` from the outer template heat will use the nova server id and not the template resource identifier. heat-6.1.2/doc/source/template_guide/hot_spec.rst0000664000567000056700000011240213077400534023177 0ustar jenkinsjenkins00000000000000.. highlight: yaml :linenothreshold: 5 .. 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. Since Juno release, Heat supports multiple different versions of the HOT specification. Template structure ~~~~~~~~~~~~~~~~~~ HOT templates are defined in YAML and follow the structure outlined below. .. code-block:: yaml heat_template_version: 2015-04-30 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_template_version: Heat template version ~~~~~~~~~~~~~~~~~~~~~ The value of ``heat_template_version`` tells Heat not only the format of the template but also features that will be validated and supported. For example, Heat currently supports the following values for the ``heat_template_version`` key: 2013-05-23 ---------- The key with value ``2013-05-23`` indicates that the YAML document is a HOT template and it may contain features implemented until the Icehouse release. This version supports the following functions (some are back ported to this version):: get_attr get_file get_param get_resource list_join resource_facade str_replace Fn::Base64 Fn::GetAZs Fn::Join Fn::MemberListToMap Fn::Replace Fn::ResourceFacade Fn::Select Fn::Split Ref 2014-10-16 ---------- The key with value ``2014-10-16`` indicates that the YAML document is a HOT template and it may contain features added and/or removed up until the Juno release. This version removes most CFN functions that were supported in the Icehouse release, i.e. the ``2013-05-23`` version. So the supported functions now are:: get_attr get_file get_param get_resource list_join resource_facade str_replace Fn::Select 2015-04-30 ---------- The key with value ``2015-04-30`` indicates that the YAML document is a HOT template and it may contain features added and/or removed up until the Kilo release. This version adds the ``repeat`` function. So the complete list of supported functions is:: get_attr get_file get_param get_resource list_join repeat digest resource_facade str_replace Fn::Select 2015-10-15 ---------- The key with value ``2015-10-15`` indicates that the YAML document is a HOT template and it may contain features added and/or removed up until the Liberty release. This version removes the *Fn::Select* function, path based ``get_attr``/``get_param`` references should be used instead. Moreover ``get_attr`` since this version returns dict of all attributes for the given resource excluding *show* attribute, if there's no specified, e.g. :code:`{ get_attr: []}`. This version also adds the str_split function and support for passing multiple lists to the existing list_join function. The complete list of supported functions is:: get_attr get_file get_param get_resource list_join repeat digest resource_facade str_replace str_split 2016-04-08 ---------- The key with value ``2016-04-08`` indicates that the YAML document is a HOT template and it may contain features added and/or removed up until the Mitaka release. This version also adds the map_merge function which can be used to merge the contents of maps. The complete list of supported functions is:: digest get_attr get_file get_param get_resource list_join map_merge repeat resource_facade str_replace str_split .. _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. .. code-block:: yaml 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. .. code-block:: yaml parameters: : type: label: description: default: hidden: constraints: param name The name of the parameter. type The type of the parameter. Supported types are ``string``, ``number``, ``comma_delimited_list``, ``json`` and ``boolean``. This attribute is required. label A human readable name for the parameter. This attribute is optional. description A human readable description for the parameter. This attribute is optional. default A default value for the parameter. This value is used if the user doesn't specify his own value during deployment. This attribute is optional. hidden Defines whether the parameters should be hidden when a user requests information about a stack created from the template. This attribute can be used to hide passwords specified as parameters. This attribute is optional and defaults to ``false``. constraints A list of constraints to apply. The constraints are validated by the Orchestration engine when a user deploys a stack. The stack creation fails if the parameter value doesn't comply to the constraints. This attribute is optional. The table below describes all currently supported types with examples: +----------------------+-------------------------------+------------------+ | Type | Description | Examples | +======================+===============================+==================+ | string | A literal string. | "String param" | +----------------------+-------------------------------+------------------+ | number | An integer or float. | "2"; "0.2" | +----------------------+-------------------------------+------------------+ | comma_delimited_list | An array of literal strings | ["one", "two"]; | | | that are separated by commas. | "one, two"; | | | The total number of strings | Note: "one, two" | | | should be one more than the | returns | | | total number of commas. | ["one", " two"] | +----------------------+-------------------------------+------------------+ | json | A JSON-formatted map or list. | {"key": "value"} | +----------------------+-------------------------------+------------------+ | boolean | Boolean type value, which can | "on"; "n" | | | be equal "t", "true", "on", | | | | "y", "yes", or "1" for true | | | | value and "f", "false", | | | | "off", "n", "no", or "0" for | | | | false value. | | +----------------------+-------------------------------+------------------+ The following example shows a minimalistic definition of two parameters .. code-block:: yaml 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 .. note:: The description and the label are optional, but defining these attributes is good practice to provide useful information about the role of the parameter to the user. .. _hot_spec_parameters_constraints: Parameter Constraints --------------------- The ``constraints`` block of a parameter definition defines additional validation constraints that apply to the value of the parameter. The parameter values provided by a user are validated against the constraints at instantiation time. The constraints are defined as a list with the following syntax .. code-block:: yaml constraints: - : description: constraint type Type of constraint to apply. The set of currently supported constraints is given below. constraint definition The actual constraint, depending on the constraint type. The concrete syntax for each constraint type is given below. description A description of the constraint. The text is presented to the user when the value he defines violates the constraint. If omitted, a default validation message is presented to the user. This attribute is optional. The following example shows 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 to present useful messages to the user at deployment time. .. code-block:: yaml 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 .. note:: 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. 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``. It defines a lower and upper limit for the length of the string value. The syntax of the ``length`` constraint is .. code-block:: yaml 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``. It defines a lower and upper limit for the numeric value of the parameter. The syntax of the ``range`` constraint is .. code-block:: yaml 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 and maximum boundaries are included in the range. For example, the following range constraint would allow for all numeric values between 0 and 10 .. code-block:: yaml range: { min: 0, max: 10 } allowed_values ++++++++++++++ The ``allowed_values`` constraint applies to parameters of type ``string`` or ``number``. It specifies 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 list. The syntax of the ``allowed_values`` constraint is .. code-block:: yaml allowed_values: [ , , ... ] Alternatively, the following YAML list notation can be used .. code-block:: yaml allowed_values: - - - ... For example .. code-block:: yaml 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``. It specifies a regular expression against which a user-provided parameter value must evaluate at deployment. The syntax of the ``allowed_pattern`` constraint is .. code-block:: yaml allowed_pattern: For example .. code-block:: yaml 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 .. code-block:: yaml custom_constraint: The ``name`` attribute specifies the concrete type of custom constraint. It corresponds to the name under which the respective validation plugin has been registered in the Orchestration engine. For example .. code-block:: yaml parameters: key_name type: string description: SSH key pair constraints: - custom_constraint: nova.keypair The following section lists the custom constraints and the plug-ins that support them. .. table_from_text:: ../../setup.cfg :header: Name,Plug-in :regex: (.*)=(.*) :start-after: heat.constraints = :end-before: heat.stack_lifecycle_plugins = :sort: .. _hot_spec_pseudo_parameters: Pseudo parameters ----------------- In addition to parameters defined by a template author, Heat also creates three parameters for every stack that allow referential access to the stack's name, stack's identifier and project's identifier. These parameters are named ``OS::stack_name`` for the stack name, ``OS::stack_id`` for the stack identifier and ``OS::project_id`` for the project identifier. These values are accessible via the `get_param`_ intrinsic function, just like user-defined parameters. .. note:: ``OS::project_id`` is available since 2015.1 (Kilo). .. _hot_spec_resources: Resources section ~~~~~~~~~~~~~~~~~ The ``resources`` section defines actual resources that make up a stack deployed from the HOT template (for instance compute instances, networks, storage volumes). Each resource is defined as a separate block in the ``resources`` section with the following syntax .. code-block:: yaml resources: : type: properties: : metadata: depends_on: update_policy: deletion_policy: resource ID A resource ID which must be unique within the ``resources`` section of the template. type The resource type, such as ``OS::Nova::Server`` or ``OS::Neutron::Port``. This attribute is required. properties A list of resource-specific properties. The property value can be provided in place, or via a function (see :ref:`hot_spec_intrinsic_functions`). This section is optional. metadata Resource-specific metadata. This section is optional. depends_on Dependencies of the resource on one or more resources of the template. See :ref:`hot_spec_resources_dependencies` for details. This attribute is optional. update_policy Update policy for the resource, in the form of a nested dictionary. Whether update policies are supported and what the exact semantics are depends on the type of the current resource. This attribute is optional. deletion_policy Deletion policy for the resource. Which type of deletion policy is supported depends on the type of the current resource. This attribute is optional. Depending on the type of resource, the resource block might include more resource specific data. 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. The following example demonstrates the definition of a simple compute resource with some fixed property values .. code-block:: yaml resources: my_instance: type: OS::Nova::Server properties: flavor: m1.small image: F18-x86_64-cfntools .. _hot_spec_resources_dependencies: Resource dependencies --------------------- The ``depends_on`` attribute of a resource defines a dependency between this 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 string of the ``depends_on`` attribute, as shown in the following example .. code-block:: yaml resources: server1: type: OS::Nova::Server depends_on: server2 server2: type: OS::Nova::Server If a resource depends on more than one other resources, the value of the ``depends_on`` attribute is specified as a list of resource IDs, as shown in the following example .. code-block:: yaml 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 ~~~~~~~~~~~~~~~ The ``outputs`` section defines output parameters that should be available to the user after a stack has been created. 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 .. code-block:: yaml outputs: : description: value: parameter name The output parameter name, which must be unique within the ``outputs`` section of a template. description A short description of the output parameter. This attribute is optional. parameter value The value of the output parameter. This value is usually resolved by means of a function. See :ref:`hot_spec_intrinsic_functions` for details about the functions. This attribute is required. The example below shows how the IP address of a compute resource can be defined as an output parameter .. code-block:: yaml 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 templates to perform specific tasks, such as getting the value of a resource attribute at runtime. The following section describes the role and syntax of the intrinsic functions. Note: these functions can only be used within the "properties" section of each resource or in the outputs section. get_attr -------- The ``get_attr`` function references an attribute of a resource. The attribute value is resolved at runtime using the resource instance created from the respective resource definition. Path based attribute referencing using keys or indexes requires ``heat_template_version`` ``2014-10-16`` or higher. The syntax of the ``get_attr`` function is .. code-block:: yaml get_attr: - - - (optional) - (optional) - ... resource name The resource name for which the attribute needs to be resolved. The resource name must exist in the ``resources`` section of the template. attribute name The attribute name 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. These additional parameters are used to navigate the data structure to return the desired value. The following example demonstrates how to use the :code:`get_attr` function: .. code-block:: yaml 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 ``get_attr`` function would resolve to ``10.0.0.1`` (first item of the ``private`` entry in the ``networks`` map). From ``heat_template_version``: '2015-10-15' is optional and if is not specified, ``get_attr`` returns dict of all attributes for the given resource excluding *show* attribute. In this case syntax would be next: .. code-block:: yaml get_attr: - get_file -------- The ``get_file`` function returns the content of a file into the template. It is generally used as a file inclusion mechanism for files containing scripts or configuration files. The syntax of ``get_file`` function is .. code-block:: yaml get_file: The ``content key`` is used to look up the ``files`` dictionary that is provided in the REST API call. The Orchestration client command (``heat``) is ``get_file`` aware and populates the ``files`` dictionary with the actual content of fetched paths and URLs. The Orchestration client command supports relative paths and transforms these to the absolute URLs required by the Orchestration API. .. note:: The ``get_file`` argument must be a static path or URL and not rely on intrinsic functions like ``get_param``. the Orchestration client does not process intrinsic functions (they are only processed by the Orchestration engine). The example below demonstrates the ``get_file`` function usage with both relative and absolute URLs .. code-block:: yaml 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 The ``files`` dictionary generated by the Orchestration client during instantiation of the stack would contain the following keys: * :file:`file:///path/to/my_instance_user_data.sh` * :file:`http://example.com/my_other_instance_user_data.sh` get_param --------- The ``get_param`` function references an input parameter of a template. It resolves to the value provided for this input parameter at runtime. The syntax of the ``get_param`` function is .. code-block:: yaml get_param: - - (optional) - (optional) - ... parameter name The parameter name to be resolved. If the parameters returns a complex data structure such as a list or a map, then subsequent keys or indexes can be specified. These additional parameters are used to navigate the data structure to return the desired value. The following example demonstrates the use of the ``get_param`` function .. code-block:: yaml 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`` and ``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 references another resource within the same template. At runtime, it is resolved to reference the ID of the referenced resource, which is resource type specific. For example, a reference to a floating IP resource returns the respective IP address at runtime. The syntax of the ``get_resource`` function is .. code-block:: yaml get_resource: The resource ID of the referenced resource is given as single parameter to the ``get_resource`` function. For example .. code-block:: yaml resources: instance_port: type: OS::Neutron::Port properties: ... instance: type: OS::Nova::Server properties: ... networks: port: { get_resource: instance_port } list_join --------- The ``list_join`` function joins a list of strings with the given delimiter. The syntax of the ``list_join`` function is .. code-block:: yaml list_join: - - For example .. code-block:: yaml list_join: [', ', ['one', 'two', 'and three']] This resolve to the string ``one, two, and three``. From HOT version ``2015-10-15`` you may optionally pass additional lists, which will be appended to the previous lists to join. For example:: list_join: [', ', ['one', 'two'], ['three', 'four']]] This resolve to the string ``one, two, three, four``. From HOT version ``2015-10-15`` you may optionally also pass non-string list items (e.g json/map/list parameters or attributes) and they will be serialized as json before joining. digest ------ The ``digest`` function allows for performing digest operations on a given value. This function has been introduced in the Kilo release and is usable with HOT versions later than ``2015-04-30``. The syntax of the ``digest`` function is .. code-block:: yaml digest: - - algorithm The digest algorithm. Valid algorithms are the ones provided natively by hashlib (md5, sha1, sha224, sha256, sha384, and sha512) or any one provided by OpenSSL. value The value to digest. This function will resolve to the corresponding hash of the value. For example .. code-block:: yaml # from a user supplied parameter pwd_hash: { digest: ['sha512', { get_param: raw_password }] } The value of the digest function would resolve to the corresponding hash of the value of ``raw_password``. repeat ------ The ``repeat`` function allows for dynamically transforming lists by iterating over the contents of one or more source lists and replacing the list elements into a template. The result of this function is a new list, where the elements are set to the template, rendered for each list item. The syntax of the ``repeat`` function is .. code-block:: yaml repeat: template: