From 587831498787288c6ae9bd0f1829393d2c11fc66 Mon Sep 17 00:00:00 2001 From: tengqm Date: Tue, 1 Dec 2015 23:58:06 -0500 Subject: [PATCH] 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 --- doc/source/architecture.rst | 62 ++++++++++++++----- doc/source/getting_started/on_devstack.rst | 25 +++++--- doc/source/gmr.rst | 51 ++++++++++----- doc/source/man/heat-db-setup.rst | 16 +++-- doc/source/man/heat-keystone-setup-domain.rst | 3 +- doc/source/man/heat-keystone-setup.rst | 13 ++-- doc/source/man/heat-manage.rst | 3 +- 7 files changed, 125 insertions(+), 48 deletions(-) diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst index 0ea47d967a..e045607290 100644 --- a/doc/source/architecture.rst +++ b/doc/source/architecture.rst @@ -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 diff --git a/doc/source/getting_started/on_devstack.rst b/doc/source/getting_started/on_devstack.rst index ed1aaa8d29..ab16c10cbb 100644 --- a/doc/source/getting_started/on_devstack.rst +++ b/doc/source/getting_started/on_devstack.rst @@ -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:: diff --git a/doc/source/gmr.rst b/doc/source/gmr.rst index 24a80a3192..a8b8b3a594 100644 --- a/doc/source/gmr.rst +++ b/doc/source/gmr.rst @@ -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 `_ +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 `_ diff --git a/doc/source/man/heat-db-setup.rst b/doc/source/man/heat-db-setup.rst index 275a8ea731..905698a2dc 100644 --- a/doc/source/man/heat-db-setup.rst +++ b/doc/source/man/heat-db-setup.rst @@ -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 `__ +Heat bugs are managed through Launchpad +`OpenStack Heat Bugs `__ diff --git a/doc/source/man/heat-keystone-setup-domain.rst b/doc/source/man/heat-keystone-setup-domain.rst index 285dace570..5b194c8632 100644 --- a/doc/source/man/heat-keystone-setup-domain.rst +++ b/doc/source/man/heat-keystone-setup-domain.rst @@ -103,4 +103,5 @@ EXAMPLES BUGS ==== -Heat bugs are managed through Launchpad `OpenStack Heat Bugs `__ +Heat bugs are managed through Launchpad +`OpenStack Heat Bugs `__ diff --git a/doc/source/man/heat-keystone-setup.rst b/doc/source/man/heat-keystone-setup.rst index b8727e4829..a9afc2325c 100644 --- a/doc/source/man/heat-keystone-setup.rst +++ b/doc/source/man/heat-keystone-setup.rst @@ -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 `__ +Heat bugs are managed through Launchpad +`OpenStack Heat Bugs `__ diff --git a/doc/source/man/heat-manage.rst b/doc/source/man/heat-manage.rst index ef329e4754..88d4d3d13c 100644 --- a/doc/source/man/heat-manage.rst +++ b/doc/source/man/heat-manage.rst @@ -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