openstack/openstack-manuals
Code Issues Proposed changes

Edited the Orchestration module sections

Browse Source 
1. Reordered instructions in the orchestration module installation section
    1. Create database.
    2. Create identity service credentials.
    3. Install packages.
    4. Configure service.
    5. Synchronize database.
    6. Start or restart service.
2. Edited titles and wording for consistency and conventions

Change-Id: I7f35274b7cbc99ce0452f4ec5b81d8412ea85b05
Implements: blueprint installation-guide-improvements
Co-Authored-By: Matt Kassawara <mkassawara@gmail.com>
This commit is contained in:
Darren
2014-05-29 13:05:36 +10:00
committed by Diane Fleming
parent 4c3383b192
commit 61dafb33ed
4 changed files with 193 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/common/section_getstart_orchestration.xml
View File

@@ -2,7 +2,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="orchestration-service">
<title>Orchestration module</title>
<title>Orchestration module concepts</title>
<para>The Orchestration module provides a template-based
orchestration for describing a cloud application, by running
OpenStack API calls to generate running cloud applications. The

7
doc/install-guide/ch_heat.xml
View File

@@ -3,10 +3,9 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_heat">
<title>Add the Orchestration service</title>
<para>Use the Orchestration module to create cloud resources using a
template language called HOT. The integrated project name is
Heat.</para>
<title>Add the Orchestration module</title>
<para>The Orchestration module (heat) uses a heat orchestration template
(HOT) to create and manage cloud resources.</para>
<xi:include href="../common/section_getstart_orchestration.xml"/>
<xi:include href="section_heat-install.xml"/>
<xi:include href="section_heat-verify.xml"/>

328
doc/install-guide/section_heat-install.xml
View File

@@ -2,198 +2,186 @@
<section xml:id="heat-install" xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Install the Orchestration service</title>
<procedure os="debian">
<title>Install and configure Orchestration</title>
<para>This section describes how to install and configure the
Orchestration module (heat) on the controller node.</para>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To configure prerequisites</title>
<para>Before you install and configure Orchestration, you must create a
database and Identity service credentials including endpoints.</para>
<step>
<para>Install the Orchestration module on the controller
node:</para>
<screen os="debian"><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine</userinput></screen>
<para>Connect to the database server as the <literal>root</literal> user:</para>
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>
<para>Create the <literal>heat</literal> database:</para>
<screen><prompt>mysql></prompt> <userinput>CREATE DATABASE heat;</userinput></screen>
<para>Grant the
proper access to the database:</para>
<screen><prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'localhost' IDENTIFIED BY '<replaceable>HEAT_DBPASS</replaceable>';</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'%' IDENTIFIED BY '<replaceable>HEAT_DBPASS</replaceable>';</userinput>
<prompt>mysql></prompt> <userinput>exit</userinput></screen>
<para>Replace <replaceable>HEAT_DBPASS</replaceable> with a suitable
password.</para>
</step>
<step>
<para>Respond to prompts for <link
linkend="debconf-dbconfig-common">database
management</link>, <link linkend="debconf-keystone_authtoken"
><systemitem>[keystone_authtoken]</systemitem>
settings</link>, <link linkend="debconf-rabbitmq">RabbitMQ
credentials</link> and <link linkend="debconf-api-endpoints"
>API endpoint</link> registration.</para>
</step>
</procedure>
<procedure>
<step>
<para>Install the Orchestration module on the controller
node:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-heat-api openstack-heat-engine \
openstack-heat-api-cfn</userinput></screen>
<screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-heat-api openstack-heat-api-cfn \
openstack-heat-engine</userinput></screen>
</step>
<step os="rhel;centos;fedora;opensuse;sles;ubuntu">
<para>In the configuration file, specify the location of the
database where the Orchestration service stores data. These
examples use a MySQL database with a
<literal>heat</literal> user on the controller node. Replace
<replaceable>HEAT_DBPASS</replaceable> with the password for
the database user:</para>
<screen os="rhel;centos;fedora;opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/heat/heat.conf \
database connection mysql://heat:<replaceable>HEAT_DBPASS</replaceable>@<replaceable>controller</replaceable>/heat</userinput></screen>
<para os="ubuntu">Edit
<filename>/etc/heat/heat.conf</filename> and modify the
<literal>[database]</literal> section:</para>
<programlisting os="ubuntu" language="ini">[database]
# The SQLAlchemy connection string used to connect to the database
connection = mysql://heat:<replaceable>HEAT_DBPASS</replaceable>@<replaceable>controller</replaceable>/heat</programlisting>
</step>
<step os="ubuntu">
<para>By default, the Ubuntu packages create an SQLite database.
Delete the <filename>heat.sqlite</filename> file that was created in
the <filename>/var/lib/heat/</filename> directory so that it
does not get used by mistake:</para>
<screen><prompt>#</prompt> <userinput>rm /var/lib/heat/heat.sqlite</userinput></screen>
</step>
<step os="rhel;centos;fedora;opensuse;sles;ubuntu">
<para>Use the password that you set previously to log in as <literal>root</literal> and
create a <literal>heat</literal> database user:</para>
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput>
<prompt>mysql></prompt> <userinput>CREATE DATABASE heat;</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'localhost' \
IDENTIFIED BY '<replaceable>HEAT_DBPASS</replaceable>';</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'%' \
IDENTIFIED BY '<replaceable>HEAT_DBPASS</replaceable>';</userinput></screen>
</step>
<step os="fedora;centos;rhel;ubuntu">
<para>Create the heat service tables:</para>
<screen><prompt>#</prompt> <userinput>su -s /bin/sh -c "heat-manage db_sync" heat</userinput></screen>
<note>
<para>Ignore <errortext>DeprecationWarning</errortext>
errors.</para>
</note>
</step>
<step os="ubuntu">
<para>The Ubuntu packages do not correctly set up logging. Edit
the <filename>/etc/heat/heat.conf</filename> file and change
the <literal>[DEFAULT]</literal> section:</para>
<programlisting os="ubuntu" language="ini">[DEFAULT]
...
# Print more verbose output (set logging level to INFO instead
# of default WARNING level). (boolean value)
verbose = True
...
# (Optional) The base directory used for relative --log-file
# paths (string value)
log_dir=/var/log/heat</programlisting>
</step>
<step os="opensuse;sles;ubuntu">
<para>Configure the Orchestration Service to use the RabbitMQ
message broker.</para>
<para os="ubuntu">Edit <filename>/etc/heat/heat.conf</filename>
and modify the <literal>[DEFAULT]</literal> section:</para>
<programlisting os="ubuntu" language="ini">rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
<para os="opensuse;sles">Run the following commands:</para>
<screen os="opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/heat/heat.conf DEFAULT rabbit_host <replaceable>controller</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/heat/heat.conf DEFAULT rabbit_password <replaceable>RABBIT_PASS</replaceable></userinput></screen>
</step>
<step os="rhel;centos;fedora;opensuse;sles;ubuntu">
<para>Create a <literal>heat</literal> user that the
Orchestration service can use to authenticate with the
Identity Service. Use the <literal>service</literal> tenant
and give the user the <literal>admin</literal> role:</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name=heat --pass=<replaceable>HEAT_PASS</replaceable> \
--email=<replaceable>heat@example.com</replaceable></userinput>
<prompt>$</prompt> <userinput>keystone user-role-add --user=heat --tenant=service --role=admin</userinput></screen>
</step>
<step os="rhel;centos;fedora;opensuse;sles;ubuntu">
<para>Edit the <filename>/etc/heat/heat.conf</filename> file to
change the <literal>[keystone_authtoken]</literal> and
<literal>[ec2authtoken]</literal> sections to add
credentials to the Orchestration Service:</para>
<programlisting language="ini">[keystone_authtoken]
auth_host = <replaceable>controller</replaceable>
auth_port = 35357
auth_protocol = http
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
admin_tenant_name = service
admin_user = heat
admin_password = <replaceable>HEAT_PASS</replaceable>
[ec2authtoken]
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0</programlisting>
</step>
<step os="debian">
<para>Edit the <filename>/etc/heat/heat.conf</filename> file to
change the <literal>[ec2authtoken]</literal> sections:</para>
<programlisting language="ini">[ec2authtoken]
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0</programlisting>
</step>
<step>
<para>Register the Heat and CloudFormation APIs with the
Identity Service so that other OpenStack services can locate
these APIs. Register the services and specify the
endpoints:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name=heat --type=orchestration \
<para>Create Identity service credentials:</para>
<substeps>
<step>
<para>Create the <literal>heat</literal> user:</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name heat --pass <replaceable>HEAT_PASS</replaceable> --email <replaceable>EMAIL_ADDRESS</replaceable></userinput></screen>
<para>Replace <replaceable>HEAT_PASS</replaceable> with a suitable
password and <replaceable>EMAIL_ADDRESS</replaceable> with
a suitable e-mail address.</para>
</step>
<step>
<para>Link the <literal>heat</literal> user to the
<literal>service</literal> tenant and <literal>admin</literal>
role:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-add --user heat --tenant service --role admin</userinput></screen>
</step>
<step>
<para>Create the <literal>heat</literal> and
<literal>heat-cfn</literal> services:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name=heat --type=orchestration \
--description="Orchestration"</userinput>
<prompt>$</prompt> <userinput>keystone endpoint-create \
<prompt>$</prompt> <userinput>keystone service-create --name=heat-cfn --type=cloudformation \
--description="Orchestration CloudFormation"</userinput></screen>
</step>
<step>
<para>Create the <literal>heat_stack_user</literal> role:</para>
<para>By default, users created by Orchestration use this role.</para>
<screen><prompt>$</prompt> <userinput>keystone role-create --name heat_stack_user</userinput></screen>
</step>
</substeps>
</step>
<step>
<para>Create the Identity service endpoints:</para>
<screen><prompt>$</prompt> <userinput>keystone endpoint-create \
--service-id=$(keystone service-list | awk '/ orchestration / {print $2}') \
--publicurl=http://<replaceable>controller</replaceable>:8004/v1/%\(tenant_id\)s \
--internalurl=http://<replaceable>controller</replaceable>:8004/v1/%\(tenant_id\)s \
--adminurl=http://<replaceable>controller</replaceable>:8004/v1/%\(tenant_id\)s</userinput>
<prompt>$</prompt> <userinput>keystone service-create --name=heat-cfn --type=cloudformation \
--description="Orchestration CloudFormation"</userinput>
<prompt>$</prompt> <userinput>keystone endpoint-create \
--service-id=$(keystone service-list | awk '/ cloudformation / {print $2}') \
--publicurl=http://<replaceable>controller</replaceable>:8000/v1 \
--internalurl=http://<replaceable>controller</replaceable>:8000/v1 \
--adminurl=http://<replaceable>controller</replaceable>:8000/v1</userinput></screen>
</step>
</procedure>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To install and configure the Orchestration components</title>
<step>
<para>Create the <literal>heat_stack_user</literal> role.</para>
<para>This role is used as the default role for users created by the
Orchestration module.</para>
<para>Run the following command to create the
<literal>heat_stack_user</literal> role:</para>
<screen><prompt>$</prompt> <userinput>keystone role-create --name heat_stack_user</userinput></screen>
<para>Run the following commands to install the packages:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-heat-api openstack-heat-engine openstack-heat-api-cfn</userinput></screen>
<screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-heat-api openstack-heat-engine openstack-heat-api-cfn</userinput></screen>
</step>
<step>
<para>Configure the metadata and waitcondition servers' URLs.</para>
<para os="debian;ubuntu">Edit the <filename>/etc/heat/heat.conf</filename> file
and modify the following options in the <literal>[DEFAULT]</literal>
section:</para>
<programlisting os="debian;ubuntu" language="ini">[DEFAULT]
<para>Edit the <filename>/etc/heat/heat.conf</filename> file.</para>
<substeps>
<step>
<para>In the <literal>[database]</literal> section, configure
database access:</para>
<programlisting language="ini">[database]
...
# URL of the Heat metadata server. (string value)
heat_metadata_server_url = http://<replaceable>10.0.0.11</replaceable>:8000
connection = mysql://heat:<replaceable>HEAT_DBPASS</replaceable>@<replaceable>controller</replaceable>/heat</programlisting>
<para>Replace <replaceable>HEAT_DBPASS</replaceable> with the password
you chose for the Orchestration database.</para>
</step>
<step>
<para>In the <literal>[DEFAULT]</literal> section, configure
<application>RabbitMQ</application> message broker access:</para>
<programlisting language="ini">[DEFAULT]
...
rpc_backend = heat.openstack.common.rpc.impl_kombu
rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
<para>Replace <replaceable>RABBIT_PASS</replaceable> with the password
you chose for the <literal>guest</literal> account in
<application>RabbitMQ</application>.</para>
</step>
<step>
<para>In the <literal>[keystone_authtoken]</literal> and
<literal>[ec2authtoken]</literal> sections, configure Identity
service access:</para>
<programlisting language="ini">[keystone_authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
auth_host = <replaceable>controller</replaceable>
auth_port = 35357
auth_protocol = http
admin_tenant_name = service
admin_user = heat
admin_password = <replaceable>HEAT_PASS</replaceable>
# URL of the Heat waitcondition server. (string value)
heat_waitcondition_server_url = http://<replaceable>10.0.0.11</replaceable>:8000/v1/waitcondition</programlisting>
<para os="centos;rhel;fedora;sles;opensuse">Run the following commands to modify the
<literal>[DEFAULT]</literal> section of the
<filename>/etc/heat/heat.conf</filename> file:</para>
<screen os="centos;rhel;fedora;sles;opensuse"><prompt>#</prompt> <userinput>openstack-config --set /etc/heat/heat.conf \
DEFAULT heat_metadata_server_url http://<replaceable>10.0.0.11</replaceable>:8000</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/heat/heat.conf \
DEFAULT heat_waitcondition_server_url http://<replaceable>10.0.0.11</replaceable>:8000/v1/waitcondition</userinput></screen>
<note>
<para>The example uses the IP address of the controller (10.0.0.11)
instead of the <literal>controller</literal> host name since our
example architecture does not include a DNS setup. Make sure that
the instances can resolve the controller host name if you choose to
use it in the URLs.</para>
</note>
[ec2authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0</programlisting>
<para>Replace <replaceable>HEAT_PASS</replaceable> with the
password you chose for the <literal>heat</literal> user
in the Identity service.</para>
</step>
<step>
<para>In the <literal>[DEFAULT]</literal> section, configure
the metadata and wait condition URLs:</para>
<programlisting language="ini">[DEFAULT]
...
heat_metadata_server_url = http://<replaceable>controller</replaceable>:8000
heat_waitcondition_server_url = http://<replaceable>controller</replaceable>:8000/v1/waitcondition</programlisting>
</step>
<step os="ubuntu">
<para>Configure the log directory in the <literal>[DEFAULT]</literal>
section:</para>
<programlisting os="ubuntu" language="ini">[DEFAULT]
...
log_dir = /var/log/heat</programlisting>
</step>
</substeps>
</step>
<step os="ubuntu">
<para>Restart the service with its new settings:</para>
</procedure>
<procedure os="debian">
<title>To install and configure the Orchestration components</title>
<step>
<para>Run the following commands to install the packages:</para>
<screen><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine</userinput></screen>
</step>
<step>
<para>Respond to prompts for
<link linkend="debconf-dbconfig-common">database management</link>,
<link linkend="debconf-keystone_authtoken">Identity service
credentials</link>,
<link linkend="debconf-api-endpoints">service endpoint
registration</link>, and
<link linkend="debconf-rabbitmq">message broker
credentials</link>.</para>
</step>
<step>
<para>Respond to the <literal>debconf</literal> configuration
tool prompts.</para>
</step>
<step>
<para>Edit the <filename>/etc/heat/heat.conf</filename> file.</para>
<substeps>
<step>
<para>In the <literal>[ec2authtoken]</literal> section, configure
Identity service access for EC2 operations:</para>
<programlisting language="ini">[ec2authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0</programlisting>
</step>
</substeps>
</step>
</procedure>
<procedure>
<title>To finalize installation</title>
<step os="ubuntu;debian">
<para>Restart the Orchestration services:</para>
<screen><prompt>#</prompt> <userinput>service heat-api restart</userinput>
<prompt>#</prompt> <userinput>service heat-api-cfn restart</userinput>
<prompt>#</prompt> <userinput>service heat-engine restart</userinput></screen>
</step>
<step os="rhel;fedora;centos;opensuse;sles">
<para>Start the <systemitem class="service"
>heat-api</systemitem>, <systemitem class="service"
>heat-api-cfn</systemitem> and <systemitem class="service"
>heat-engine</systemitem> services and configure them to
start when the system boots:</para>
<para>Start the Orchestration services and configure them to start when
the system boots:</para>
<screen os="rhel;fedora;centos;opensuse;sles"><prompt>#</prompt> <userinput>service openstack-heat-api start</userinput>
<prompt>#</prompt> <userinput>service openstack-heat-api-cfn start</userinput>
<prompt>#</prompt> <userinput>service openstack-heat-engine start</userinput>
@@ -201,5 +189,11 @@ heat_waitcondition_server_url = http://<replaceable>10.0.0.11</replaceable>:8000
<prompt>#</prompt> <userinput>chkconfig openstack-heat-api-cfn on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-heat-engine on</userinput></screen>
</step>
<step os="ubuntu">
<para>By default, the Ubuntu packages create a SQLite database.</para>
<para>Because this configuration uses a SQL database server, you
can remove the SQLite database file:</para>
<screen><prompt>#</prompt> <userinput>rm /var/lib/heat/heat.sqlite</userinput></screen>
</step>
</procedure>
</section>

52
doc/install-guide/section_heat-verify.xml
View File

@@ -2,28 +2,29 @@
<section xml:id="heat-verify" xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Verify the Orchestration service installation</title>
<para>To verify that the Orchestration service is installed and configured
correctly, make sure that your credentials are set up correctly in the
<filename>demo-openrc.sh</filename> file. Source the file, as follows:</para>
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
<para>The Orchestration Module uses templates to describe stacks. To learn
about the template languages, see <link
<title>Verify operation</title>
<para>This section describes how to verify operation of the Orchestration
module (heat).</para>
<procedure>
<step>
<para>Source the <literal>demo</literal> tenant credentials:</para>
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
</step>
<step>
<para>The Orchestration module uses templates to describe stacks. To learn
about the template language, see <link
xlink:href="http://docs.openstack.org/developer/heat/template_guide/index.html"
>the Template Guide</link> in the <link
>the Template Guide</link> in the <link
xlink:href="http://docs.openstack.org/developer/heat/">Heat developer
documentation</link>.</para>
<para>Create a test template in the <filename>test-stack.yml</filename>
file with the following content:</para>
<programlisting language="yml"><xi:include parse="text" href="samples/test-stack.yml"/></programlisting>
<para>Use the <command>heat stack-create</command> command to create a stack
from this template:</para>
<screen><prompt>$</prompt> <userinput>NET_ID=$(nova net-list | awk '/ demo-net / { print $2 }')</userinput>
documentation</link>.</para>
<para>Create a test template in the <filename>test-stack.yml</filename>
file with the following content:</para>
<programlisting language="yml"><xi:include parse="text" href="samples/test-stack.yml"/></programlisting>
</step>
<step>
<para>Use the <command>heat stack-create</command> command to create a
stack from the template:</para>
<screen><prompt>$</prompt> <userinput>NET_ID=$(nova net-list | awk '/ demo-net / { print $2 }')</userinput>
<prompt>$</prompt> <userinput>heat stack-create -f test-stack.yml \
-P "ImageID=cirros-0.3.2-x86_64;NetID=$NET_ID" testStack</userinput>
<computeroutput>+--------------------------------------+------------+--------------------+----------------------+
@@ -31,13 +32,16 @@
+--------------------------------------+------------+--------------------+----------------------+
| 477d96b4-d547-4069-938d-32ee990834af | testStack | CREATE_IN_PROGRESS | 2014-04-06T15:11:01Z |
+--------------------------------------+------------+--------------------+----------------------+</computeroutput></screen>
<para>Verify that the stack was created successfully with the <command>heat stack-list</command> command:</para>
<screen><prompt>$</prompt> <userinput>heat stack-list</userinput>
</step>
<step>
<para>Use the <command>heat stack-list</command> command to verify
successful creation of the stack:</para>
<screen><prompt>$</prompt> <userinput>heat stack-list</userinput>
<computeroutput>+--------------------------------------+------------+-----------------+----------------------+
| id | stack_name | stack_status | creation_time |
+--------------------------------------+------------+-----------------+----------------------+
| 477d96b4-d547-4069-938d-32ee990834af | testStack | CREATE_COMPLETE | 2014-04-06T15:11:01Z |
+--------------------------------------+------------+-----------------+----------------------+</computeroutput></screen>
</step>
</procedure>
</section>