openstack/openstack-manuals
Code Issues Proposed changes

[install-guide] convert heat chapter to RST

Browse Source 
just a conversion to rst files.
* ch_heat.xml
* section_heat-install.xml
* section_heat-verify.xml

Change-Id: Iedb8d0485fcae30268853d76e66f9bcf9977c8ae
Implements: blueprint installguide-liberty
This commit is contained in:
KATO Tomoyuki
2015-07-08 13:49:48 +09:00
parent a2f2e7e49b
commit be821a93ff
4 changed files with 487 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

392
doc/install-guide-rst/source/heat-install.rst Normal file
View File

@@ -0,0 +1,392 @@
===================================
Install and configure Orchestration
===================================
This section describes how to install and configure the
Orchestration module, code-named heat, on the controller node.
To configure prerequisites
~~~~~~~~~~~~~~~~~~~~~~~~~~
Before you install and configure Orchestration, you must create a
database, service credentials, and API endpoints.
#. To create the database, complete these steps:
* Use the database access client to connect to the database
server as the ``root`` user:
.. code-block:: console
$ mysql -u root -p
* Create the ``heat`` database::
CREATE DATABASE heat;
* Grant proper access to the ``heat`` database::
GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'localhost' \
IDENTIFIED BY 'HEAT_DBPASS';
GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'%' \
IDENTIFIED BY 'HEAT_DBPASS';
Replace ``HEAT_DBPASS`` with a suitable password.
* Exit the database access client.
#. Source the ``admin`` credentials to gain access to
admin-only CLI commands:
.. code-block:: console
$ source admin-openrc.sh
#. To create the service credentials, complete these steps:
* Create the ``heat`` user:
.. code-block:: console
$ openstack user create --password-prompt heat
User Password:
Repeat User Password:
+----------+----------------------------------+
| Field | Value |
+----------+----------------------------------+
| email | None |
| enabled | True |
| id | 7fd67878dcd04d0393469ef825a7e005 |
| name | heat |
| username | heat |
+----------+----------------------------------+
* Add the ``admin`` role to the ``heat`` user:
.. code-block:: console
$ openstack role add --project service --user heat admin
+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | cd2cb9a39e874ea69e5d4b896eb16128 |
| name | admin |
+-------+----------------------------------+
* Create the ``heat_stack_owner`` role:
.. code-block:: console
$ openstack role create heat_stack_owner
+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | c0a1cbee7261446abc873392f616de87 |
| name | heat_stack_owner |
+-------+----------------------------------+
* Add the ``heat_stack_owner`` role to the ``demo`` tenant and user:
.. code-block:: console
$ openstack role add --project demo --user demo heat_stack_owner
+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | c0a1cbee7261446abc873392f616de87 |
| name | heat_stack_owner |
+-------+----------------------------------+
.. note::
You must add the ``heat_stack_owner`` role to users
that manage stacks.
* Create the ``heat_stack_user`` role:
.. code-block:: console
$ openstack role create heat_stack_user
+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | e01546b1a81c4e32a6d14a9259e60154 |
| name | heat_stack_user |
+-------+----------------------------------+
.. note::
The Orchestration service automatically assigns the
``heat_stack_user`` role to users that it creates
during stack deployment. By default, this role restricts
API operations. To avoid conflicts, do not add this role
to users with the ``heat_stack_owner`` role.
* Create the ``heat`` and ``heat-cfn`` service entities:
.. code-block:: console
$ openstack service create --name heat \
--description "Orchestration" orchestration
+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | Orchestration |
| enabled | True |
| id | 031112165cad4c2bb23e84603957de29 |
| name | heat |
| type | orchestration |
+-------------+----------------------------------+
$ openstack service create --name heat-cfn \
--description "Orchestration" cloudformation
+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | Orchestration |
| enabled | True |
| id | 297740d74c0a446bbff867acdccb33fa |
| name | heat-cfn |
| type | cloudformation |
+-------------+----------------------------------+
#. Create the Orchestration service API endpoints:
.. code-block:: console
$ openstack endpoint create \
--publicurl http://controller:8004/v1/%\(tenant_id\)s \
--internalurl http://controller:8004/v1/%\(tenant_id\)s \
--adminurl http://controller:8004/v1/%\(tenant_id\)s \
--region RegionOne \
orchestration
+--------------+-----------------------------------------+
| Field | Value |
+--------------+-----------------------------------------+
| adminurl | http://controller:8004/v1/%(tenant_id)s |
| id | f41225f665694b95a46448e8676b0dc2 |
| internalurl | http://controller:8004/v1/%(tenant_id)s |
| publicurl | http://controller:8004/v1/%(tenant_id)s |
| region | RegionOne |
| service_id | 031112165cad4c2bb23e84603957de29 |
| service_name | heat |
| service_type | orchestration |
+--------------+-----------------------------------------+
$ openstack endpoint create \
--publicurl http://controller:8000/v1 \
--internalurl http://controller:8000/v1 \
--adminurl http://controller:8000/v1 \
--region RegionOne \
cloudformation
+--------------+----------------------------------+
| Field | Value |
+--------------+----------------------------------+
| adminurl | http://controller:8000/v1 |
| id | f41225f665694b95a46448e8676b0dc2 |
| internalurl | http://controller:8000/v1 |
| publicurl | http://controller:8000/v1 |
| region | RegionOne |
| service_id | 297740d74c0a446bbff867acdccb33fa |
| service_name | heat-cfn |
| service_type | cloudformation |
+--------------+----------------------------------+
To install and configure the Orchestration components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. only:: obs
1. Run the following commands to install the packages:
.. code-block:: console
# zypper install openstack-heat-api openstack-heat-api-cfn \
openstack-heat-engine python-heatclient
.. only:: rdo
1. Run the following commands to install the packages:
.. code-block:: console
# yum install openstack-heat-api openstack-heat-api-cfn \
openstack-heat-engine python-heatclient
.. only:: ubuntu
1. Run the following commands to install the packages:
.. code-block:: console
# apt-get install heat-api heat-api-cfn heat-enginea \
python-heatclient
2.
.. only:: rdo
.. Workaround for https://bugzilla.redhat.com/show_bug.cgi?id=1213476.
Copy the :file:`/usr/share/heat/heat-dist.conf` file
to :file:`/etc/heat/heat.conf`.
.. code-block:: console
# cp /usr/share/heat/heat-dist.conf /etc/heat/heat.conf
# chown -R heat:heat /etc/heat/heat.conf
Edit the :file:`/etc/heat/heat.conf` file and complete the following
actions:
* In the ``[database]`` section, configure database access:
.. code-block:: ini
:linenos:
[database]
...
connection = mysql://heat:HEAT_DBPASS@controller/heat
Replace ``HEAT_DBPASS`` with the password you chose for the
Orchestration database.
* In the ``[DEFAULT]`` and ``[oslo_messaging_rabbit]`` sections,
configure ``RabbitMQ`` message queue access:
.. code-block:: ini
:linenos:
[DEFAULT]
...
rpc_backend = rabbit
[oslo_messaging_rabbit]
...
rabbit_host = controller
rabbit_userid = openstack
rabbit_password = RABBIT_PASS
Replace ``RABBIT_PASS`` with the password you chose for the
``openstack`` account in ``RabbitMQ``.
* In the ``[keystone_authtoken]`` and ``[ec2authtoken]`` sections,
configure Identity service access:
.. code-block:: ini
:linenos:
[keystone_authtoken]
...
auth_uri = http://controller:5000/v2.0
identity_uri = http://controller:35357
admin_tenant_name = service
admin_user = heat
admin_password = HEAT_PASS
[ec2authtoken]
...
auth_uri = http://controller:5000/v2.0
Replace ``HEAT_PASS`` with the password you chose for the
``heat`` user in the Identity service.
.. note::
Comment out any ``auth_host``, ``auth_port``, and
``auth_protocol`` options because the
``identity_uri`` option replaces them.
* In the ``[DEFAULT]`` section, configure the metadata and
wait condition URLs:
.. code-block:: ini
:linenos:
[DEFAULT]
...
heat_metadata_server_url = http://controller:8000
heat_waitcondition_server_url = http://controller:8000/v1/waitcondition
* In the ``[DEFAULT]`` section, configure information about the heat
Identity service domain:
.. code-block:: ini
:linenos:
[DEFAULT]
...
stack_domain_admin = heat_domain_admin
stack_domain_admin_password = HEAT_DOMAIN_PASS
stack_user_domain_name = heat_user_domain
Replace ``HEAT_DOMAIN_PASS`` with the password you chose for the admin
user of the ``heat`` user domain in the Identity service.
* (Optional) To assist with troubleshooting, enable verbose
logging in the ``[DEFAULT]`` section:
.. code-block:: ini
:linenos:
[DEFAULT]
...
verbose = True</programlisting>
3.
* Source the ``admin`` credentials to gain access to
admin-only CLI commands:
.. code-block:: console
$ source admin-openrc.sh
* Create the heat domain in Identity service:
.. code-block:: console
$ heat-keystone-setup-domain \
--stack-user-domain-name heat_user_domain \
--stack-domain-admin heat_domain_admin \
--stack-domain-admin-password HEAT_DOMAIN_PASS
Replace ``HEAT_DOMAIN_PASS`` with a suitable password.
4. Populate the Orchestration database:
.. code-block:: console
# su -s /bin/sh -c "heat-manage db_sync" heat
To finalize installation
~~~~~~~~~~~~~~~~~~~~~~~~
.. only:: obs or rdo
#. Start the Orchestration services and configure them to start
when the system boots:
.. code-block:: console
# systemctl enable openstack-heat-api.service \
openstack-heat-api-cfn.service openstack-heat-engine.service
# systemctl start openstack-heat-api.service \
openstack-heat-api-cfn.service openstack-heat-engine.service
.. only:: ubuntu
#. Restart the Orchestration services:
.. code-block:: console
# service heat-api restart
# service heat-api-cfn restart
# service heat-engine restart
#. By default, the Ubuntu packages create a SQLite database.
Because this configuration uses a SQL database server, you
can remove the SQLite database file:
.. code-block:: console
# rm -f /var/lib/heat/heat.sqlite

9
doc/install-guide-rst/source/heat-next-step.rst Normal file
View File

@@ -0,0 +1,9 @@
==========
Next steps
==========
Your OpenStack environment now includes Orchestration. You can
launch an instance or add more
services to your environment in the following chapters.
.. TODO (katomo) add link to launch an instance after creation.

75
doc/install-guide-rst/source/heat-verify.rst Normal file
View File

@@ -0,0 +1,75 @@
================
Verify operation
================
This section describes how to verify operation of the Orchestration
module (heat).
#. Source the ``admin`` tenant credentials:
.. code-block:: console
$ source admin-openrc.sh
#. The Orchestration module uses templates to describe stacks.
To learn about the template language, see `the Template Guide
<http://docs.openstack.org/developer/heat/template_guide/index.html>`__
in the `Heat developer documentation
<http://docs.openstack.org/developer/heat/index.html>`__.
Create a test template in the :file:`test-stack.yml`
file with the following content:
.. code-block:: yaml
:linenos:
heat_template_version: 2014-10-16
description: A simple server.
parameters:
ImageID:
type: string
description: Image use to boot a server
NetID:
type: string
description: Network ID for the server
resources:
server:
type: OS::Nova::Server
properties:
image: { get_param: ImageID }
flavor: m1.tiny
networks:
- network: { get_param: NetID }
outputs:
private_ip:
description: IP address of the server in the private network
value: { get_attr: [ server, first_address ] }</programlisting>
#. Use the :command:`heat stack-create` command to create a stack from the
template:
.. code-block:: console
$ NET_ID=$(nova net-list | awk '/ demo-net / { print $2 }')
$ heat stack-create -f test-stack.yml \
-P "ImageID=cirros-0.3.4-x86_64;NetID=$NET_ID" testStack
+--------------------------------------+------------+--------------------+----------------------+
| id | stack_name | stack_status | creation_time |
+--------------------------------------+------------+--------------------+----------------------+
| 477d96b4-d547-4069-938d-32ee990834af | testStack | CREATE_IN_PROGRESS | 2014-04-06T15:11:01Z |
+--------------------------------------+------------+--------------------+----------------------+
#. Use the :command:`heat stack-list` command to verify
successful creation of the stack:
.. code-block:: console
$ heat stack-list
+--------------------------------------+------------+-----------------+----------------------+
| id | stack_name | stack_status | creation_time |
+--------------------------------------+------------+-----------------+----------------------+
| 477d96b4-d547-4069-938d-32ee990834af | testStack | CREATE_COMPLETE | 2014-04-06T15:11:01Z |
+--------------------------------------+------------+-----------------+----------------------+

11
doc/install-guide-rst/source/heat.rst
View File

@@ -1,3 +1,14 @@
============================
Add the Orchestration module
============================
.. toctree::
heat-install.rst
heat-verify.rst
heat-next-step.rst
.. TODO (katomo) include common/getstart_orchestration after creation.
The Orchestration module (heat) uses a heat orchestration
template (HOT) to create and manage cloud resources.