openstack
/
heat
Code Issues Proposed changes

Fix some line wrap problems in doc 

According to RST doc guidelines, we should avoid line length beyond 79
characters:
http://docs.openstack.org/contributor-guide/rst-conv/gen-guidelines.html

Change-Id: I51332f92cbdfd5319e9a0209b2436df716ca2311
This commit is contained in:
tengqm 2015-12-01 23:58:06 -05:00
parent 1a8790d970
commit 5878314987
7 changed files with 125 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
doc/source/architecture.rst
View File

@ -14,54 +14,84 @@
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.
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.*
*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:
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 and users), 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.*
*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 and users), 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.
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.
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.
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.
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.
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 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
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

25
doc/source/getting_started/on_devstack.rst
View File

@ -13,9 +13,12 @@
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.
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.
These instructions assume you already have a working DevStack installation
which can launch basic instances.
Configure DevStack to enable Heat
---------------------------------
@ -34,16 +37,22 @@ 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_URLS+=",http://download.fedoraproject.org/pub/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.qcow2"
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.
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-`.
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::
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
@ -57,7 +66,9 @@ Add the profiler notifier to your Ceilometer to your config::
Enable the profiler in /etc/heat/heat.conf::
$ echo -e "[profiler]\nprofiler_enabled = True\ntrace_sqlalchemy = True\n" >> /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::

51
doc/source/gmr.rst
View File

@ -13,41 +13,57 @@
License for the specific language governing permissions and limitations
under the License.
=======================
Guru Meditation Reports
=======================
Heat contains a mechanism whereby developers and system administrators can generate a report about the state of a running Heat executable. This report is called a *Guru Meditation Report* (*GMR* for short).
Heat contains a mechanism whereby developers and system administrators can
generate a report about the state of a running Heat executable. This report
is called a *Guru Meditation Report* (*GMR* for short).
Generating a GMR
----------------
~~~~~~~~~~~~~~~~
A *GMR* can be generated by sending the *USR2* signal to any Heat process with support (see below). The *GMR* will then be outputted standard error for that particular process.
A *GMR* can be generated by sending the *USR2* signal to any Heat process with
support (see below). The *GMR* will then be outputted standard error for that
particular process.
For example, suppose that ``heat-api`` has process id ``10172``, and was run
with ``2>/var/log/heat/heat-api-err.log``. Then, ``kill -USR2 10172`` will
trigger the Guru Meditation report to be printed to
``/var/log/heat/heat-api-err.log``.
For example, suppose that ``heat-api`` has process id ``10172``, and was run with ``2>/var/log/heat/heat-api-err.log``. Then, ``kill -USR2 10172`` will trigger the Guru Meditation report to be printed to ``/var/log/heat/heat-api-err.log``.
Structure of a GMR
------------------
~~~~~~~~~~~~~~~~~~
The *GMR* is designed to be extensible; any particular executable may add its own sections. However, the base *GMR* consists of several sections:
The *GMR* is designed to be extensible; any particular executable may add its
own sections. However, the base *GMR* consists of several sections:
Package
Shows information about the package to which this process belongs, including version information
Shows information about the package to which this process belongs, including
version information
Threads
Shows stack traces and thread ids for each of the threads within this process
Green Threads
Shows stack traces for each of the green threads within this process (green threads don't have thread ids)
Shows stack traces for each of the green threads within this process (green
threads don't have thread ids)
Configuration
Lists all the configuration options currently accessible via the CONF object for the current process
Lists all the configuration options currently accessible via the CONF object
for the current process
Adding support for GMRs to new executable
------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adding support for a *GMR* to a given executable is fairly easy.
First import the module (currently residing in oslo-incubator), as well as the Heat version module:
First import the module (currently residing in oslo-incubator), as well as the
Heat version module:
.. code-block:: python
@ -61,13 +77,18 @@ Then, register any additional sections (optional):
TextGuruMeditation.register_section('Some Special Section',
some_section_generator)
Finally (under main), before running the "main loop" of the executable (usually ``server.start()`` or something similar), register the *GMR* hook:
Finally (under main), before running the "main loop" of the executable
(usually ``server.start()`` or something similar), register the *GMR* hook:
.. code-block:: python
TextGuruMeditation.setup_autorun(version)
Extending the GMR
-----------------
As mentioned above, additional sections can be added to the GMR for a particular executable. For more information, see the documentation about oslo.reports: `oslo.reports <http://docs.openstack.org/developer/oslo.reports/>`_
Extending the GMR
~~~~~~~~~~~~~~~~~
As mentioned above, additional sections can be added to the GMR for a
particular executable. For more information, see the documentation about
``oslo.reports``:
`oslo.reports <http://docs.openstack.org/developer/oslo.reports/>`_

16
doc/source/man/heat-db-setup.rst
View File

@ -39,15 +39,22 @@ OPTIONS
.. cmdoption:: -p, --password
Specify the password for the 'heat' MySQL user that the script will use to connect to the 'heat' MySQL database. By default, the password 'heat' will be used.
Specify the password for the 'heat' MySQL user that the script will use to
connect to the 'heat' MySQL database. By default, the password 'heat' will
be used.
.. cmdoption:: -r, --rootpw
Specify the root MySQL password. If the script installs the MySQL server, it will set the root password to this value instead of prompting for a password. If the MySQL server is already installed, this password will be used to connect to the database instead of having to prompt for it.
Specify the root MySQL password. If the script installs the MySQL server,
it will set the root password to this value instead of prompting for a
password. If the MySQL server is already installed, this password will be
used to connect to the database instead of having to prompt for it.
.. cmdoption:: -y, --yes
In cases where the script would normally ask for confirmation before doing something, such as installing mysql-server, just assume yes. This is useful if you want to run the script non-interactively.
In cases where the script would normally ask for confirmation before doing
something, such as installing mysql-server, just assume yes. This is useful
if you want to run the script non-interactively.
EXAMPLES
========
@ -60,4 +67,5 @@ EXAMPLES
BUGS
====
Heat bugs are managed through Launchpad `OpenStack Heat Bugs <https://bugs.launchpad.net/heat>`__
Heat bugs are managed through Launchpad
`OpenStack Heat Bugs <https://bugs.launchpad.net/heat>`__

3
doc/source/man/heat-keystone-setup-domain.rst
View File

@ -103,4 +103,5 @@ EXAMPLES
BUGS
====
Heat bugs are managed through Launchpad `OpenStack Heat Bugs <https://bugs.launchpad.net/heat>`__
Heat bugs are managed through Launchpad
`OpenStack Heat Bugs <https://bugs.launchpad.net/heat>`__

13
doc/source/man/heat-keystone-setup.rst
View File

@ -13,11 +13,15 @@ SYNOPSIS
DESCRIPTION
===========
Warning: This script is deprecated, please use other tool to setup keystone for heat.
Warning: This script is deprecated, please use other tool to setup keystone
for heat.
The heat-keystone-setup tool configures keystone for use with heat. This script requires admin keystone credentials to be available in the shell environment and write access to /etc/keystone.
The ``heat-keystone-setup`` tool configures keystone for use with heat. This
script requires admin keystone credentials to be available in the shell
environment and write access to ``/etc/keystone``.
Distributions may provide other tools to setup keystone for use with Heat, so check the distro documentation first.
Distributions may provide other tools to setup keystone for use with Heat, so
check the distro documentation first.
EXAMPLES
========
@ -26,4 +30,5 @@ EXAMPLES
BUGS
====
Heat bugs are managed through Launchpad `OpenStack Heat Bugs <https://bugs.launchpad.net/heat>`__
Heat bugs are managed through Launchpad
`OpenStack Heat Bugs <https://bugs.launchpad.net/heat>`__

3
doc/source/man/heat-manage.rst
View File

@ -22,7 +22,8 @@ The standard pattern for executing a heat-manage command is:
Run with -h to see a list of available commands:
``heat-manage -h``
Commands are db_version, db_sync, purge_deleted and service. Detailed descriptions are below.
Commands are ``db_version``, ``db_sync``, ``purge_deleted`` and ``service``.
Detailed descriptions are below.
Heat Db version