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

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

@ -1,98 +1,89 @@
2. In the ``/etc/trove`` directory, edit the ``trove.conf`` file and 2. In the ``/etc/trove`` directory, edit the ``trove.conf`` file, here is an example:
complete the following steps:
* Provide appropriate values for the following settings:
.. code-block:: ini .. code-block:: ini
[DEFAULT] [DEFAULT]
log_dir = /var/log/trove network_driver = trove.network.neutron.NeutronDriver
trove_auth_url = http://controller/identity/v2.0 management_networks = ef7541ad-9599-4285-878a-e0ab62032b03
nova_compute_url = http://controller:8774/v2 management_security_groups = d0d797f7-11d4-436e-89a3-ac8bca829f81
cinder_url = http://controller:8776/v1 cinder_volume_type = lvmdriver-1
swift_url = http://controller:8080/v1/AUTH_ nova_keypair = trove-mgmt
... default_datastore = mysql
[database] taskmanager_manager = trove.taskmanager.manager.Manager
connection = mysql+pymysql://trove:TROVE_DBPASS@controller/trove trove_api_workers = 5
transport_url = rabbit://stackrabbit:password@192.168.1.34:5672/
* Configure the Database service to use the ``RabbitMQ`` message broker control_exchange = trove
by setting the following options in each file:
.. code-block:: ini
[DEFAULT]
...
rpc_backend = rabbit 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``. 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 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>`__. `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 4. Edit the ``/etc/trove/trove-guestagent.conf`` file
settings shown below: so that future trove guests can connect to your OpenStack environment, here
is an example:
.. code-block:: ini .. code-block:: ini
[DEFAULT] [DEFAULT]
auth_strategy = keystone log_file = trove-guestagent.log
... log_dir = /var/log/trove/
# Config option for showing the IP address that nova doles out ignore_users = os_admin
add_addresses = True control_exchange = trove
network_label_regex = ^NETWORK_LABEL$ transport_url = rabbit://stackrabbit:password@172.24.5.1:5672/
... rpc_backend = rabbit
api_paste_config = /etc/trove/api-paste.ini command_process_timeout = 60
... use_syslog = False
[keystone_authtoken] debug = True
...
www_authenticate_uri = http://controller/identity [service_credentials]
auth_url = http://controller/identity_admin auth_url = http://192.168.1.34/identity/v3
auth_type = password region_name = RegionOne
project_domain_name = default
user_domain_name = default
project_name = service project_name = service
password = password
project_domain_name = Default
user_domain_name = Default
username = trove username = trove
password = TROVE_PASS
5. Edit the ``trove.conf`` file so it includes the required 5. Populate the trove database you created earlier in this procedure:
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:
.. code-block:: console .. code-block:: console
@ -104,4 +95,3 @@
.. note:: .. note::
Ignore any deprecation messages in this output. 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 #. The OpenStack end user deploys the Database service using the following
steps: steps:
#. Create a Database service instance using the :command:`trove create` #. Create a Database service instance using the
command. ``openstack database instance create`` command.
#. Use the :command:`trove list` command to get the ID of the instance, #. Use the :command:`openstack database instance list` command to get the ID
followed by the :command:`trove show` command to get the IP address of of the instance, followed by the
it. :command:`openstack database instance show` command to get the IP address
of it.
#. Access the Database service instance using typical database access #. Access the Database service instance using typical database access
commands. For example, with MySQL: 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. A CLI that communicates with the ``trove-api`` component.
``trove-api`` component ``trove-api`` component
Provides an OpenStack-native RESTful API that supports JSON to This component is responsible for providing the RESTful API. It talks to the
provision and manage Trove instances. 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 ``trove-conductor`` service
Runs on the host, and receives messages from guest instances that The conductor component is responsible for updating the Trove backend
want to update information on the host. 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 ``trove-taskmanager`` service
Instruments the complex system flows that support provisioning The task manager is the engine responsible for doing the majority of the
instances, managing the lifecycle of instances, and performing work. It is responsible for provisioning instances, managing the life cycle,
operations on instances. 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 ``trove-guestagent`` service
Runs within the guest instance. Manages and performs operations on The guest agent runs inside the Nova instances that are used to run the
the database itself. 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:: .. toctree::
apache-mod-wsgi.rst
get_started.rst get_started.rst
apache-mod-wsgi.rst
install-devstack.rst install-devstack.rst
install-manual.rst install-manual.rst
install-obs.rst
install-rdo.rst
install-ubuntu.rst install-ubuntu.rst
install-redhat.rst
install-suse.rst
dashboard.rst dashboard.rst
verify.rst verify.rst
next-steps.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 There are several configuration files for Trove, you can find samples of the
config files in ``etc/trove/`` of Trove repo: 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 - 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 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. environment.
.. code-block:: ini .. code-block:: ini
nova_proxy_admin_user = admin [service_credentials]
nova_proxy_admin_pass = password auth_url = <Keystone service URL>
nova_proxy_admin_tenant_name = admin username = admin
nova_proxy_admin_tenant_id = f472127c03f6410899225e26a3c1d22c password = password
nova_proxy_admin_user_domain_name = default user_domain_name = default
nova_proxy_admin_project_domain_name = default project_name = admin
remote_nova_client = trove.common.clients_admin.nova_client_trove_admin project_domain_name = default
remote_cinder_client = trove.common.clients_admin.cinder_client_trove_admin region_name = RegionOne
remote_neutron_client = trove.common.clients_admin.neutron_client_trove_admin
os_region_name = RegionOne
#. Management config options. #. Management config options.
@ -216,7 +216,7 @@ Create and register Trove guest image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build Trove guest image, refer to 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 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 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 This section describes how to install and configure the Database service
for Red Hat Enterprise Linux 7 and CentOS 7. 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 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 This section describes how to install and configure the Database service
for openSUSE Leap 42.2 and SUSE Linux Enterprise Server 12 SP2. 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 Finalize installation
--------------------- ---------------------
1. Due to a bug in the Ubuntu packages, edit the service definition files 1. Restart the Database services:
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:
.. code-block:: console .. code-block:: console

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

@ -15,57 +15,17 @@ Verify operation of the Database service.
$ . admin-openrc $ . 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 .. code-block:: console
$ trove list $ openstack database instance list
+----+------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+----+------+-----------+-------------------+--------+-----------+------+
+----+------+-----------+-------------------+--------+-----------+------+
#. Add a datastore to trove: #. Add a datastore to trove:
* `Create a trove image <https://docs.openstack.org/trove/latest/admin/building_guest_images.html>`_. * `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, Create an image for the type of database you want to use, for example,
MySQL, MongoDB, Cassandra. MySQL, MariaDB, etc.
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 a datastore. You need to create a separate datastore for * Create a datastore. You need to create a separate datastore for
each type of database you want to use, for example, MySQL, MongoDB, 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 .. code-block:: console
# su -s /bin/sh -c "trove-manage \ $ trove-manage datastore_update mysql ""
--config-file /etc/trove/trove.conf \ $ trove-manage datastore_version_update mysql 5.7 mysql $imageid "" 1
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.
#. Create a database `instance #. Create a database `instance
<http://docs.openstack.org/user-guide/create_db.html>`_. <http://docs.openstack.org/user-guide/create_db.html>`_.