From: Jeff Sloyer Date: Tue, 16 Jul 2013 18:36:06 +0000 (-0400) Subject: add docs from the heat wiki X-Git-Tag: 2014.1~343^2 X-Git-Url: https://review.fuel-infra.org/gitweb?a=commitdiff_plain;h=6bfd774df842195969814201f6bf5dc8a1ec4797;p=openstack-build%2Fheat-build.git add docs from the heat wiki updated index.rst to mimic the layout of the keystone docs updated the structure for troubleshooting ported howto guides from the heat wiki ported the troubleshooting page from the heat wiki updated the nav for the man pages and getting started added docs for a cfn template and hot template Change-Id: I14c1b0b6aa6ea3529c4de994851f7a798a3061bf --- diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst new file mode 100644 index 00000000..005fb8ef --- /dev/null +++ b/doc/source/architecture.rst @@ -0,0 +1,67 @@ +.. + Copyright 2011-2012 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +Heat Architecture +================= + +Heat is a service to orchestrate multiple composite cloud applications using the .. _AWS CloudFormation: http://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/Welcome.html?r=7078 template format, through both an OpenStack-native ReST API and a CloudFormation-compatible Query API. + + +-------------------- +Detailed Description +-------------------- + +What is the purpose of the project and vision for it? + +*Heat provides an AWS CloudFormation implementation for OpenStack that orchestrates an AWS CloudFormation template describing a cloud application by executing appropriate OpenStack API calls to generate running cloud applications. + +Describe the relevance of the project to other OpenStack projects and the OpenStack mission to provide a ubiquitous cloud computing platform: + +*The software integrates other core components of OpenStack into a one-file template system. 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. By providing very tight integration with other OpenStack core projects, all OpenStack core projects could receive a larger user base. +*Currently no other CloudFormation implementation exists for OpenStack. The developers believe cloud developers have a strong desire to move workloads from AWS to OpenStack deployments. Given the missing gap of a well-implemented and integrated CloudFormation API in OpenStack, we provide a high quality implementation of this gap improving the ubiquity of OpenStack. + +------------- +Heat Services +------------- + +The developers are focused on creating an OpenStack style project using OpenStack design tenets, implemented in Python. We have started with full integration with Keystone. We have a number of components. + +As the developers have only started development in March 2012, the architecture is evolving rapidly. + +heat +----- + +The heat tool is a CLI which communicates with the heat-api to execute AWS CloudFormation APIs. End developers could also use the heat REST API directly. + + +heat-api +-------- + +The heat-api component provides an OpenStack-native REST API that processes API requests by sending them to the heat-engine over RPC. + + +heat-api-cfn +------------ + +The heat-api-cfn component provides an AWS Query API that is compatible with AWS CloudFormation and processes API requests by sending them to the heat-engine over RPC. + + +heat-engine +----------- + +The heat engine's main responsibility is to orchestrate the launching of templates and provide events back to the API consumer. + +The templates integrate well with .. _Puppet: https://s3.amazonaws.com/cloudformation-examples/IntegratingAWSCloudFormationWithPuppet.pdf and .. _Chef: http://www.full360.com/2011/02/27/integrating-aws-cloudformation-and-chef.html \ No newline at end of file diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 2c71f54b..610b2bd0 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -21,6 +21,4 @@ Getting Started Guides on_fedora on_ubuntu on_other - jeos_building - -.. update index + jeos_building \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index b448e62d..ed5cd0e3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -21,35 +21,47 @@ both an OpenStack-native ReST API and a CloudFormation-compatible Query API. What is the purpose of the project and vision for it? ===================================================== -* Heat provides a template based orchestration for describing a cloud application - by executing appropriate :term:`OpenStack` API calls to generate running cloud applications. -* The software integrates other core components of OpenStack into a one-file - template system. 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. By providing very tight integration with other - OpenStack core projects, all OpenStack core projects could receive a larger user base. +* Heat provides a template based orchestration for describing a cloud application by executing appropriate :term:`OpenStack` API calls to generate running cloud applications. +* The software integrates other core components of OpenStack into a one-file template system. 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. By providing very tight integration with other OpenStack core projects, all OpenStack core projects could receive a larger user base. * Allow deployers to integrate with Heat directly or by adding custom plugins. -This documentation offers information on how heat works and how to -contribute to the project. +This documentation offers information on how heat works and how to contribute to the project. -Table of contents -================= +Getting Started +=============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - man/index - getting_started/index - troubleshooting/index - glossary + getting_started/index + troubleshooting/index + glossary -.. update index +Man Pages +========= + +.. toctree:: + :maxdepth: 2 + + man/index + +Developers Documentation +======================== +.. toctree:: + :maxdepth: 1 + + architecture + +Code Documentation +================== +.. toctree:: + :maxdepth: 1 + + api/autoindex Indices and tables ================== * :ref:`genindex` * :ref:`modindex` -* :ref:`search` +* :ref:`search` \ No newline at end of file diff --git a/doc/source/templates/cfn/WordPress_Single_Instance.rst b/doc/source/templates/cfn/WordPress_Single_Instance.rst new file mode 100644 index 00000000..c5625931 --- /dev/null +++ b/doc/source/templates/cfn/WordPress_Single_Instance.rst @@ -0,0 +1,59 @@ +.. + 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 +-------- +_https://github.com/openstack/heat-templates/blob/master/cfn/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 key pair to use for the instance +*InstanceType :mod:`(optional)` + *type + *string + *description + *Instance type for the instance to be created +*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 + *Distribution of choice \ No newline at end of file diff --git a/doc/source/templates/hot/hello_world.rst b/doc/source/templates/hot/hello_world.rst new file mode 100644 index 00000000..d08c75ee --- /dev/null +++ b/doc/source/templates/hot/hello_world.rst @@ -0,0 +1,40 @@ +.. + 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 +-------- +_https://github.com/openstack/heat-templates/blob/master/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 +---------- +*KeyName :mod:`(required)` + *type + *string + *description + *Name of an existing key pair to use for the instance +*InstanceType :mod:`(required)` + *type + *string + *description + *Instance type for the instance to be created +*ImageId :mod:`(required)` + *type + *string + *description + *ID of the image to use for the instance \ No newline at end of file diff --git a/doc/source/troubleshooting/index.rst b/doc/source/templates/index.rst similarity index 66% rename from doc/source/troubleshooting/index.rst rename to doc/source/templates/index.rst index 42820e42..76480dac 100644 --- a/doc/source/troubleshooting/index.rst +++ b/doc/source/templates/index.rst @@ -11,9 +11,19 @@ License for the specific language governing permissions and limitations under the License. -Troubleshooting -=============== +This page documents the templates at _https://github.com/openstack/heat-templates/ +HOT Templates +============= -If you encounter issues running heat, see if the solution to the issue is documented on the Troubleshooting_ wiki page. If not, let us know about the problem in the #heat IRC channel on freenode. +.. toctree:: + :maxdepth: 1 -.. _Troubleshooting: http://wiki.openstack.org/Heat/TroubleShooting + hot/hello_world + +CFN Templates +============= + +.. toctree:: + :maxdepth: 1 + + cfn/WordPress_Single_Instance \ No newline at end of file