openstack/trove
Code Issues Proposed changes

Improve the doc

Browse Source 
Change-Id: I41bf34cd482dcf880cd66c8bd123898f77c10056
This commit is contained in:
Lingxian Kong 2020-03-19 23:01:02 +13:00
parent 513e0dd3cd
commit dc0bfe1d39
8 changed files with 125 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
doc/source/install/common_configure.txt
View File

@ -1,98 +1,89 @@
2. In the ``/etc/trove`` directory, edit the ``trove.conf`` file and
complete the following steps:
2. In the ``/etc/trove`` directory, edit the ``trove.conf`` file, here is an example:
* Provide appropriate values for the following settings:
.. code-block:: ini
.. code-block:: ini
[DEFAULT]
log_dir = /var/log/trove
trove_auth_url = http://controller/identity/v2.0
nova_compute_url = http://controller:8774/v2
cinder_url = http://controller:8776/v1
swift_url = http://controller:8080/v1/AUTH_
...
[database]
connection = mysql+pymysql://trove:TROVE_DBPASS@controller/trove
* Configure the Database service to use the ``RabbitMQ`` message broker
by setting the following options in each file:
.. code-block:: ini
[DEFAULT]
...
network_driver = trove.network.neutron.NeutronDriver
management_networks = ef7541ad-9599-4285-878a-e0ab62032b03
management_security_groups = d0d797f7-11d4-436e-89a3-ac8bca829f81
cinder_volume_type = lvmdriver-1
nova_keypair = trove-mgmt
default_datastore = mysql
taskmanager_manager = trove.taskmanager.manager.Manager
trove_api_workers = 5
transport_url = rabbit://stackrabbit:password@192.168.1.34:5672/
control_exchange = trove
rpc_backend = rabbit
transport_url = rabbit://<rabbit_userid>:<rabbit_password>@<rabbit_host>:5672
reboot_time_out = 300
usage_timeout = 900
agent_call_high_timeout = 1200
use_syslog = False
debug = True
[keystone_authtoken]
memcached_servers = localhost:11211
cafile = /devstack/stack/data/ca-bundle.pem
project_domain_name = Default
project_name = service
user_domain_name = Default
password = password
username = trove
auth_url = http://192.168.1.34/identity
auth_type = password
[service_credentials]
auth_url = http://192.168.1.34/identity/v3
region_name = RegionOne
project_name = service
password = password
project_domain_name = Default
user_domain_name = Default
username = trove
[database]
connection = mysql+pymysql://root:password@127.0.0.1/trove?charset=utf8
[mariadb]
tcp_ports = 3306,4444,4567,4568
[mysql]
tcp_ports = 3306
[postgresql]
tcp_ports = 5432
3. Verify that the ``api-paste.ini`` file is present in ``/etc/trove``.
If the file is not present, you can get it from this
`location <https://opendev.org/openstack/trove/raw/branch/master/etc/trove/api-paste.ini>`__.
4. Edit the ``trove.conf`` file so it includes appropriate values for the
settings shown below:
4. Edit the ``/etc/trove/trove-guestagent.conf`` file
so that future trove guests can connect to your OpenStack environment, here
is an example:
.. code-block:: ini
[DEFAULT]
auth_strategy = keystone
...
# Config option for showing the IP address that nova doles out
add_addresses = True
network_label_regex = ^NETWORK_LABEL$
...
api_paste_config = /etc/trove/api-paste.ini
...
[keystone_authtoken]
...
www_authenticate_uri = http://controller/identity
auth_url = http://controller/identity_admin
auth_type = password
project_domain_name = default
user_domain_name = default
log_file = trove-guestagent.log
log_dir = /var/log/trove/
ignore_users = os_admin
control_exchange = trove
transport_url = rabbit://stackrabbit:password@172.24.5.1:5672/
rpc_backend = rabbit
command_process_timeout = 60
use_syslog = False
debug = True
[service_credentials]
auth_url = http://192.168.1.34/identity/v3
region_name = RegionOne
project_name = service
password = password
project_domain_name = Default
user_domain_name = Default
username = trove
password = TROVE_PASS
5. Edit the ``trove.conf`` file so it includes the required
settings to connect to the OpenStack Compute service as shown below.
Include ConfigDrive settings so that configuration is injected
into the Guest VM. And finally, if using Nova Network, set the
the network driver name and a regex which allows Projects to
launch Guests on any of their networks.
.. code-block:: 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_PASS
nova_proxy_admin_tenant_name = service
taskmanager_manager = trove.taskmanager.manager.Manager
# Inject configuration into guest via ConfigDrive
use_nova_server_config_drive = True
# Set these if using Neutron Networking
network_driver=trove.network.neutron.NeutronDriver
network_label_regex=.*
6. Edit the ``/etc/trove/trove-guestagent.conf`` file
so that future trove guests can connect to your OpenStack environment:
.. code-block:: ini
rabbit_host = controller
rabbit_password = RABBIT_PASS
trove_auth_url = http://controller/identity_admin/v2.0
7. Populate the trove database you created earlier in this procedure:
5. Populate the trove database you created earlier in this procedure:
.. code-block:: console
@ -104,4 +95,3 @@
.. note::
Ignore any deprecation messages in this output.

38
doc/source/install/get_started.rst
View File

@ -29,11 +29,12 @@ This example is a high-level process flow for using Database services:
#. The OpenStack end user deploys the Database service using the following
steps:
#. Create a Database service instance using the :command:`trove create`
command.
#. Use the :command:`trove list` command to get the ID of the instance,
followed by the :command:`trove show` command to get the IP address of
it.
#. Create a Database service instance using the
``openstack database instance create`` command.
#. Use the :command:`openstack database instance list` command to get the ID
of the instance, followed by the
:command:`openstack database instance show` command to get the IP address
of it.
#. Access the Database service instance using typical database access
commands. For example, with MySQL:
@ -49,18 +50,27 @@ The Database service includes the following components:
A CLI that communicates with the ``trove-api`` component.
``trove-api`` component
Provides an OpenStack-native RESTful API that supports JSON to
provision and manage Trove instances.
This component is responsible for providing the RESTful API. It talks to the
task manager for complex tasks, but it can also talk to the guest agent
directly to perform simple tasks, such as retrieving databases or users from
trove instance.
``trove-conductor`` service
Runs on the host, and receives messages from guest instances that
want to update information on the host.
The conductor component is responsible for updating the Trove backend
database with the information that the guest agent sends regarding the
instances. It eliminates the need for direct database access by all the guest
agents for updating information.
``trove-taskmanager`` service
Instruments the complex system flows that support provisioning
instances, managing the lifecycle of instances, and performing
operations on instances.
The task manager is the engine responsible for doing the majority of the
work. It is responsible for provisioning instances, managing the life cycle,
and performing different operations. The task manager normally sends common
commands to trove guest agent, which are of an abstract nature; it is the
responsibility of the guest agent to read them and issue database-specific
commands in order to execute them.
``trove-guestagent`` service
Runs within the guest instance. Manages and performs operations on
the database itself.
The guest agent runs inside the Nova instances that are used to run the
database engines. The agent listens to the messaging bus for the topic and is
responsible for actually translating and executing the commands that are sent
to it by the task manager component for the particular datastore.

6
doc/source/install/index.rst
View File

@ -8,13 +8,13 @@ database engines.
.. toctree::
apache-mod-wsgi.rst
get_started.rst
apache-mod-wsgi.rst
install-devstack.rst
install-manual.rst
install-obs.rst
install-rdo.rst
install-ubuntu.rst
install-redhat.rst
install-suse.rst
dashboard.rst
verify.rst
next-steps.rst

28
doc/source/install/install-manual.rst
View File

@ -150,28 +150,28 @@ Trove configuration
There are several configuration files for Trove, you can find samples of the
config files in ``etc/trove/`` of Trove repo:
- api-paste.ini and trove.conf — For trove-api service
- api-paste.ini — For trove-api service
- trove.conf - For trove-api, trove-taskmanagerr, trove-conductor services.
- trove-guestagent.conf — For trove-guestagent service
- ``<datastore_manager>.cloudinit`` — Userdata for VMs during provisioning
- ``<datastore_manager>.cloudinit`` — Userdata for trove instance during
provisioning
Options in trove.conf
---------------------
#. Config service tenant model, change the values according to your own
#. Service tenant credentials, change the values according to your own
environment.
.. code-block:: ini
nova_proxy_admin_user = admin
nova_proxy_admin_pass = password
nova_proxy_admin_tenant_name = admin
nova_proxy_admin_tenant_id = f472127c03f6410899225e26a3c1d22c
nova_proxy_admin_user_domain_name = default
nova_proxy_admin_project_domain_name = default
remote_nova_client = trove.common.clients_admin.nova_client_trove_admin
remote_cinder_client = trove.common.clients_admin.cinder_client_trove_admin
remote_neutron_client = trove.common.clients_admin.neutron_client_trove_admin
os_region_name = RegionOne
[service_credentials]
auth_url = <Keystone service URL>
username = admin
password = password
user_domain_name = default
project_name = admin
project_domain_name = default
region_name = RegionOne
#. Management config options.
@ -216,7 +216,7 @@ Create and register Trove guest image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build Trove guest image, refer to
`Build guest agent image <https://docs.openstack.org/trove/latest/admin/trovestack.html#build-guest-agent-image>`_
`Build guest agent image <https://docs.openstack.org/trove/latest/admin/building_guest_images.html>`_
Run Trove
~~~~~~~~~

3
doc/source/install/install-rdo.rst → doc/source/install/install-redhat.rst
View File

@ -3,6 +3,9 @@
Install and configure for Red Hat Enterprise Linux and CentOS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
This guide is not tested since stable/train.
This section describes how to install and configure the Database service
for Red Hat Enterprise Linux 7 and CentOS 7.

4
doc/source/install/install-obs.rst → doc/source/install/install-suse.rst
View File

@ -4,6 +4,10 @@
Install and configure for openSUSE and SUSE Linux Enterprise
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
This guide is not tested since stable/train.
This section describes how to install and configure the Database service
for openSUSE Leap 42.2 and SUSE Linux Enterprise Server 12 SP2.

34
doc/source/install/install-ubuntu.rst
View File

@ -29,39 +29,7 @@ Install and configure components
Finalize installation
---------------------
1. Due to a bug in the Ubuntu packages, edit the service definition files
to use the correct configuration settings.
To do this, navigate to ``/etc/init`` and edit the following files
as described below:
``trove-taskmanager.conf``
``trove-conductor.conf``
(Note that, although they have the same names, these files are
in a different location and have different content than the similarly
named files you edited earlier in this procedure.)
In each file, find this line:
.. code-block:: ini
exec start-stop-daemon --start --chdir /var/lib/trove \
--chuid trove:trove --make-pidfile \
--pidfile /var/run/trove/trove-conductor.pid \
--exec /usr/bin/trove-conductor -- \
--config-file=/etc/trove/trove.conf ${DAEMON_ARGS}
Note that ``--config-file`` incorrectly points to ``trove.conf``.
In ``trove-taskmanager.conf``, edit ``config-file`` to point to
``/etc/trove/trove-taskmanager.conf``.
In ``trove-conductor.conf``, edit ``config-file`` to point to
``/etc/trove/trove-conductor.conf``.
2. Restart the Database services:
1. Restart the Database services:
.. code-block:: console

70
doc/source/install/verify.rst
View File

@ -15,57 +15,17 @@ Verify operation of the Database service.
$ . admin-openrc
#. Run the ``trove list`` command. You should see output similar to this:
#. Check the ``openstack database instance list`` command should work.
.. code-block:: console
$ trove list
+----+------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+----+------+-----------+-------------------+--------+-----------+------+
+----+------+-----------+-------------------+--------+-----------+------+
$ openstack database instance list
#. Add a datastore to trove:
* `Create a trove image <https://docs.openstack.org/trove/latest/admin/building_guest_images.html>`_.
Create an image for the type of database you want to use, for example,
MySQL, MongoDB, Cassandra.
This image must have the trove guest agent installed.
* Upload the image to glance. Example:
.. code-block:: console
$ glance image-create --name "mysqlTest" --disk-format qcow2 \
--container-format bare \
--file mysql-5.6.qcow2
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| checksum | 51a8e6e5ff10b08f2c2ec2953f0a8086 |
| container_format | bare |
| created_at | 2016-04-08T15:15:41Z |
| disk_format | qcow2 |
| id | 5caa76dd-f44b-4d01-a3b4-a111e27896be |
| min_disk | 0 |
| min_ram | 0 |
| name | mysqlTest |
| owner | 0c0bd5e850c24893b48c4cc01e2a7986 |
| protected | False |
| size | 533790720 |
| status | active |
| tags | [] |
| updated_at | 2016-04-08T15:15:51Z |
| virtual_size | None |
| visibility | private |
+------------------+--------------------------------------+
* An alternate method of launching trove guests is to use an existing
Linux distro image and `configure the trove guest using Cloud-init
<https://docs.openstack.org/trove/latest/admin/guest_cloud_init.html>`_ .
This saves the effort of creating a customized image, but at the
cost of a slower startup time.
* `Create and upload trove guest image <https://docs.openstack.org/trove/latest/admin/building_guest_images.html>`_.
Create an image for the type of database you want to use, for example,
MySQL, MariaDB, etc.
* Create a datastore. You need to create a separate datastore for
each type of database you want to use, for example, MySQL, MongoDB,
@ -74,24 +34,8 @@ Verify operation of the Database service.
.. code-block:: console
# su -s /bin/sh -c "trove-manage \
--config-file /etc/trove/trove.conf \
datastore_update mysql ''" trove
...
Datastore 'mysql' updated.
#. Update the datastore to use the new image.
This example shows you how to update a MySQL 5.6 datastore:
.. code-block:: console
# su -s /bin/sh -c "trove-manage --config-file /etc/trove/trove.conf \
datastore_version_update \
mysql mysql-5.6 mysql glance_image_ID '' 1" trove
...
Datastore version 'mysql-5.6' updated.
$ trove-manage datastore_update mysql ""
$ trove-manage datastore_version_update mysql 5.7 mysql $imageid "" 1
#. Create a database `instance
<http://docs.openstack.org/user-guide/create_db.html>`_.