openstack/openstack-manuals
Code Issues Proposed changes

Merge "Add info on how to add Database service (Trove)"

Browse Source
This commit is contained in:
Jenkins 2014-04-16 12:32:46 +00:00 committed by Gerrit Code Review
commit 613d37ffe7
7 changed files with 365 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
doc/common/section_getstart_trove.xml Normal file
View File

@ -0,0 +1,71 @@
<section 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"
xml:id="trove-service">
<title>Database service overview</title>
<para>The Database service provides scalable and reliable cloud provisioning functionality for both relational and non-relational database engines. Users can quickly and easily utilize database features without the burden of handling complex administrative tasks. Cloud users and database administrators can provision and manage multiple database instances as needed.</para>
<para>The Database service provides resource isolation at high performance levels, and automates complex administrative tasks such as deployment, configuration, patching, backups, restores, and monitoring.</para>
<formalpara>
<title>Process flow example.</title><para>Here is a high-level process flow example for using Database services:</para>
</formalpara>
<procedure>
<step><para>Administrator sets up infrastructure:</para>
<substeps>
<step>
<para>OpenStack administrator installs the Database service.</para>
</step>
<step>
<para>She creates one image for each type of database the
administrator wants to have (one for MySQL, one for MongoDB,
and so on).</para>
</step>
<step>
<para>OpenStack administrator updates the datastore to use the
new images, using the <command>trove-manage</command>
command.</para>
</step>
</substeps>
</step>
<step>
<para>End user uses database service:</para>
<substeps>
<step>
<para>Now that the basic infrastructure is set up, an end user
can create a Trove instance (database) whenever the user
wants, using the <command>trove create</command>
command.</para>
</step>
<step>
<para>The end user gets the IP address of the Trove instance by using
the <command>trove list</command> command to get the ID of the instance, and
then using the <command>trove show <replaceable>instanceID</replaceable></command> command to get the IP address.</para>
</step>
<step>
<para>The end user can now access the Trove instance using typical database access commands. MySQL example:</para>
<screen><prompt>$</prompt> mysql -u myuser -pmypass -h <replaceable>trove_ip_address</replaceable> mydb</screen>
</step>
</substeps>
</step>
</procedure>
<formalpara>
<title>Components:</title><para>The Database service includes the following components:</para>
</formalpara>
<itemizedlist>
<listitem>
<para><code>python-troveclient</code> command-line client. A CLI that communicates with the <code>trove-api</code> component.</para>
</listitem>
<listitem>
<para><code>trove-api</code> component. Provides an
OpenStack-native RESTful API that supports JSON to provision and manage Trove instances.</para>
</listitem>
<listitem>
<para><code>trove-conductor</code> service. Runs on the host, and receives messages from guest instances that want to update information on the host.</para>
</listitem>
<listitem>
<para><code>trove-taskmanager</code> service. Instruments the complex system flows that support provisioning instances, managing the lifecycle of instances, and performing operations on instances.</para>
</listitem>
<listitem>
<para><code>trove-guestagent</code> service. Runs within the guest instance. Manages and performs operations on the database itself.</para>
</listitem>
</itemizedlist>
</section>

6
doc/install-guide/app_reserved_uids.xml
View File

@ -80,6 +80,12 @@
<td os="rhel;centos;fedora">160</td>
<td os="debian;opensuse;sles;ubuntu">Assigned during package installation</td>
</tr>
<tr>
<td>trove</td>
<td>OpenStack Trove Daemons</td>
<td os="rhel;centos;fedora">Unknown FIXME</td>
<td os="debian;opensuse;sles;ubuntu">Assigned during package installation</td>
</tr>
</tbody>
</table>
<para>Each user belongs to a user group with the same name as the

1
doc/install-guide/bk_openstackinstallguide.xml
View File

@ -195,6 +195,7 @@
<xi:include href="ch_swift.xml"/>
<xi:include href="ch_heat.xml"/>
<xi:include href="ch_ceilometer.xml"/>
<xi:include href="ch_trove.xml"/>
<xi:include href="ch_launch-instance.xml"/>
<xi:include href="app_reserved_uids.xml"/>
<xi:include href="../common/app_support.xml"/>

15
doc/install-guide/ch_trove.xml Normal file
View File

@ -0,0 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter 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"
xml:id="ch_trove">
<title>Add the Database service</title>
<para>Use the <glossterm baseform="Database Service">Database
module</glossterm> to create cloud database resources. The
integrated project name is <glossterm>trove</glossterm>.</para>
<warning><para>This chapter is a work in progress. It may contain
incorrect information, and will be updated frequently.</para></warning>
<xi:include href="../common/section_getstart_trove.xml"/>
<xi:include href="section_trove-install.xml" />
<xi:include href="section_trove-verify.xml" />
</chapter>

8
doc/install-guide/section_basics-passwords.xml
View File

@ -103,6 +103,14 @@
<td><literal><replaceable>CEILOMETER_PASS</replaceable></literal></td>
<td>Password of Telemetry service user <literal>ceilometer</literal></td>
</tr>
<tr>
<td><literal><replaceable>TROVE_DBPASS</replaceable></literal></td>
<td>Database password of Database service</td>
</tr>
<tr>
<td><literal><replaceable>TROVE_PASS</replaceable></literal></td>
<td>Password of Database Service user <literal>trove</literal></td>
</tr>
</tbody>
</table>
</para>

235
doc/install-guide/section_trove-install.xml Normal file
View File

@ -0,0 +1,235 @@
<?xml version="1.0" encoding="utf-8"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="trove-install" version="5.0">
<title>Install the Database service</title>
<para>This procedure installs the Database module on the controller
node.</para>
<formalpara>
<title>Prerequisites</title>
<para>This chapter assumes that you already have a working
OpenStack environment with at least the following components
installed: Compute, Image Service, Identity.</para>
</formalpara>
<note os="ubuntu">
<title>Ubuntu 14.04 Only</title>
<para>The Database module is only available under Ubuntu 14.04.
Packages are not available for 12.04, or via the Ubuntu Cloud
Archive.</para>
</note>
<para>To install the Database module on the controller:</para>
<procedure>
<step>
<para>Install required packages:</para>
<screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install python-trove python-troveclient python-glanceclient \
trove-common trove-api trove-taskmanager</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-trove FIXME</userinput></screen>
<screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-trove python-troveclient</userinput></screen>
</step>
<step><para>Prepare OpenStack:</para>
<substeps>
<step>
<para>Source the <filename>admin-openrc.sh</filename> file.</para>
<screen><prompt>$</prompt> <userinput>source ~/admin-openrc.sh</userinput></screen>
</step>
<step os="rhel;centos;fedora;opensuse;sles;ubuntu">
<para>Create a <literal>trove</literal> user that Compute uses 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=trove --pass=<replaceable>TROVE_PASS</replaceable> --email=<replaceable>trove@example.com</replaceable></userinput>
<prompt>$</prompt> <userinput>keystone user-role-add --user=trove --tenant=service --role=admin</userinput></screen>
</step>
</substeps>
</step>
<step>
<para>Edit the the following configuration files, taking the below
actions for each file:</para>
<itemizedlist>
<listitem><para><filename>trove.conf</filename></para></listitem>
<listitem><para><filename>trove-taskmanager.conf</filename></para></listitem>
<listitem><para><filename>trove-conductor.conf</filename></para></listitem>
</itemizedlist>
<substeps>
<step><para>Edit the <literal>[DEFAULT]</literal> section of each file
for the, client URLs and logging configuration</para>
<programlisting language="ini">[DEFAULT]
log_dir=/var/log/trove
trove_auth_url = http://controller:5000/v2.0
nova_compute_url = http://controller:8774/v2
cinder_url = http://controller:8776/v1
swift_url = http://controller:8080/v1/AUTH_
</programlisting>
</step>
<step os="fedora;rhel;centos">
<para>Set these configuration keys to configure thee Database
module to use the Qpid message broker:</para>
<screen><prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-api.conf \
DEFAULT rpc_backend rabbit</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-taskmaster.conf \
DEFAULT rpc_backend rabbit</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-conductor.conf \
DEFAULT rpc_backend rabbit</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-api.conf DEFAULT qpid_hostname <replaceable>controller</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-taskmaster.conf DEFAULT qpid_hostname <replaceable>controller</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-conductor.conf DEFAULT qpid_hostname <replaceable>controller</replaceable></userinput>
</screen>
</step>
<step os="ubuntu">
<para>Configure the Database module to use the RabbitMQ message broker by
setting these configuration keys in the <literal>[DEFAULT]</literal>
configuration group of each file:</para>
<programlisting language="ini">[DEFAULT]
...
rpc_backend = rabbit
rabbit_host = controller
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
</step>
<step os="opensuse;sles">
<para>Set these configuration keys to configure the Database module to use
the RabbitMQ message broker:</para>
<screen><prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-api.conf \
DEFAULT rpc_backend rabbit</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-taskmaster.conf \
DEFAULT rpc_backend rabbit</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-conductor.conf \
DEFAULT rpc_backend rabbit</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-api.conf DEFAULT rabbit_host controller</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-taskmaster.conf DEFAULT rabbit_host controller</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-conductor.conf DEFAULT rabbit_host controller</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-api.conf DEFAULT rabbit_password <replaceable>RABBIT_PASS</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-taskmaster.conf DEFAULT rabbit_password <replaceable>RABBIT_PASS</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/trove/trove-conductor.conf DEFAULT rabbit_password <replaceable>RABBIT_PASS</replaceable></userinput></screen>
</step>
<step>
<para>Edit the <literal>[keystone_authtoken]</literal> section of each file so it matches the listing shown below:</para>
<programlisting language="ini">
[keystone_authtoken]
auth_host = controller
auth_port = 35357
auth_protocol = http
admin_user = trove
admin_password = TROVE_PASS
admin_tenant_name = service
auth_uri = https://controller:5000/v2.0</programlisting>
</step>
<step>
<para>Edit the <literal>[database]</literal> section of each file,
adding it if necessary, so it matches the listing shown below:</para>
<programlisting language="ini">[database]
connection = mysql://trove:<literal>TROVE_DBPASS</literal>@controller/trove
</programlisting>
</step>
</substeps>
</step>
<step><para>Edit the <filename>trove.conf</filename> file so it matches
the listing shown below:</para>
<programlisting language="ini">[DEFAULT]
default_datastore = mysql
....
# Config option for showing the IP address that nova doles out
add_addresses = True
network_label_regex = ^NETWORK_LABEL$
....
# ============ notifer queue kombu connection options ========================
notifier_queue_hostname = controller</programlisting>
</step>
<step>
<para>Edit the <filename>trove-taskmanager.conf</filename> file so it matches the listing shown below:</para>
<programlisting language="ini">[DEFAULT]
....
# Configuration options for talking to nova via the novaclient.
# These options are for an admin user in your keystone config.
# It proxy's the token received from the user to send to nova via this admin users creds,
# basically acting like the client via that proxy token.
nova_proxy_admin_user = admin
nova_proxy_admin_pass = ADMIN_PASSS
nova_proxy_admin_tenant_name = service
....
# ============ notifer queue kombu connection options ========================
notifier_queue_hostname = controller
...</programlisting>
</step>
<step>
<para>Create a <filename>trove_nolog.conf</filename> file:</para>
<screen><prompt>#</prompt> <userinput>cp /etc/trove/trove.conf /etc/trove/trove_nolog.conf</userinput></screen>
<para>Edit the <filename>trove_nolog.conf</filename> file:</para>
<programlisting language="ini"># remove line starting with logdir and add
use_syslog=False</programlisting>
</step>
<step>
<para>Prepare the trove admin database:</para>
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput>
<prompt>mysql&gt;</prompt> <userinput>CREATE DATABASE trove;</userinput>
<prompt>mysql&gt;</prompt> <userinput>GRANT ALL PRIVILEGES ON trove.* TO trove@'localhost' IDENTIFIED BY 'TROVE_DBPASS';</userinput>
<prompt>mysql&gt;</prompt> <userinput>GRANT ALL PRIVILEGES ON trove.* TO trove@'%' IDENTIFIED BY 'TROVE_DBPASS';</userinput></screen>
</step>
<step><para>Prepare the Database service:</para>
<substeps>
<step>
<para>Initialize the database:</para>
<screen><prompt>$</prompt> <userinput>trove-manage --config-file=/etc/trove/trove_nolog.conf db_sync</userinput></screen>
</step>
<step>
<para>Create a datastore. You need to create a separate datastore for
each type of database you want to use, for example, MySQL, MongoDB, Cassandra.
This example shows you how to create a datastore for a MySQL database:</para>
<screen><prompt>$</prompt> <userinput>trove-manage --config-file=/etc/trove/trove_nolog.conf datastore_update mysql ""</userinput></screen>
</step>
</substeps>
</step>
<step>
<para>Create a trove image.</para>
<para>Create an image for the type of database you want to use, for example, MySQL, MongoDB, Cassandra.</para>
<para>This image must have the trove guest agent installed, and it must have the <filename>trove-guestagent.conf</filename> file configured to connect to your OpenStack environment. To correctly configure the <filename>trove-guestagent.conf</filename> file, do these steps on the guest instance you are using to build your image:</para>
<substeps>
<step>
<para>Add the following lines to <filename>trove-guestagent.conf</filename>:</para>
<programlisting language="ini">rabbit_host = controller
rabbit_password = <replaceable>RABBIT_PASS</replaceable>
nova_proxy_admin_user = admin
nova_proxy_admin_pass = ADMIN_PASSS
nova_proxy_admin_tenant_name = service
trove_auth_url = http://controller:35357/v2.0</programlisting>
</step>
</substeps>
</step>
<step>
<para>Update the datastore to use the new image, using the <command>trove-manage</command> command.</para>
<para>This example shows you how to create a MySQL 5.5 datastore:</para>
<screen><prompt>#</prompt> <userinput>trove-manage --config-file=/etc/trove/trove.conf datastore_version_update \
mysql mysql-5.5 mysql <replaceable>glance_image_ID</replaceable> mysql-server-5.5 1</userinput></screen>
</step>
<step os="rhel;centos;fedora;opensuse;sles;ubuntu">
<para>You must register the Database module with the Identity service so
that other OpenStack services can locate it. Register the
service and specify the endpoint:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name=trove --type=database \
--description="OpenStack Database Service"</userinput>
<prompt>$</prompt> <userinput>keystone endpoint-create \
--service-id=$(keystone service-list | awk '/ trove / {print $2}') \
--publicurl=http://<replaceable>controller</replaceable>:8779/v1.0/%\(tenant_id\)s \
--internalurl=http://<replaceable>controller</replaceable>:8779/v1.0/%\(tenant_id\)s \
--adminurl=http://<replaceable>controller</replaceable>:8779/v1.0/%\(tenant_id\)s</userinput></screen>
</step>
<step os="rhel;centos;fedora;opensuse;sles;ubuntu">
<para os="centos;fedora;rhel;opensuse;sles">Start Database
services and configure them to start when the system
boots:</para>
<para os="ubuntu">Restart Database services:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>service trove-api restart</userinput>
<prompt>#</prompt> <userinput>service trove-taskmanager restart</userinput>
<prompt>#</prompt> <userinput>service trove-conductor restart</userinput></screen>
<screen os="centos;rhel;fedora;opensuse;sles"><prompt>#</prompt> <userinput>service openstack-trove-api start</userinput>
<prompt>#</prompt> <userinput>service openstack-trove-taskmanager start</userinput>
<prompt>#</prompt> <userinput>service openstack-trove-conductor start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-trove-api on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-trove-taskmanager on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-trove-conductor on</userinput></screen>
</step>
</procedure>
</section>

29
doc/install-guide/section_trove-verify.xml Normal file
View File

@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="trove-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 Database service installation</title>
<para>To verify that the Database service is installed and configured correctly, try executing a Trove command:</para>
<procedure>
<step>
<para>Source the <filename>demo-openrc.sh</filename> file.</para>
<screen><prompt>$</prompt> <userinput>source ~/demo-openrc.sh</userinput></screen>
</step>
<step>
<para>Retrieve the Trove instances list:</para>
<screen><prompt>$</prompt> <userinput>trove list</userinput></screen>
<para>You should see output similar to this:</para>
<screen><computeroutput>+----+------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+----+------+-----------+-------------------+--------+-----------+------+
+----+------+-----------+-------------------+--------+-----------+------+</computeroutput></screen>
</step>
<step>
<para>Assuming you have created an image for the type of database you want, and have updated the datastore to use that image, you can now create a Trove instance (database). To do this, use the trove <command>create</command> command.</para>
<para>This example shows you how to create a MySQL 5.5 database:</para>
<screen><prompt>$</prompt> <userinput>trove create <replaceable>name</replaceable> 2 --size=2 --databases=<replaceable>dbname</replaceable> \
--users <replaceable>user</replaceable>:<replaceable>pass</replaceable> --datastore_version mysql-5.5 \
--datastore mysql</userinput></screen>
</step>
</procedure>
</section>