Add info on how to add Database service (Trove)
The install guide did not have a chapter on how to add the Database service. Created one with the following sections: overview, install, verify. This draft reflects the fact that some technical issues are still being worked out: -- image creation questions. Before you can use Trove, you need to create an image for each flavor of database you want to have (MySQL, MongoDB, etc.) The appropriate level of documentation for this step is still under discussion and has not yet been determined. Change-Id: I31e02f48975c7050022ee6fb8f31b878c6b508ff Partial-Bug: #1304584
This commit is contained in:
Laurel Michaels
Andreas Jaeger
parent
ccbad50832
commit
1ff983782a
|
|
@ -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>
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"/>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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></prompt> <userinput>CREATE DATABASE trove;</userinput>
|
||||
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON trove.* TO trove@'localhost' IDENTIFIED BY 'TROVE_DBPASS';</userinput>
|
||||
<prompt>mysql></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>
|
||||
|
|
@ -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>
|
||||
Loading…
Reference in New Issue