Improve the doc

Change-Id: I41bf34cd482dcf880cd66c8bd123898f77c10056

8 files changed, 122 insertions, 203 deletions

diff --git a/doc/source/install/common_configure.txt b/doc/source/install/common_configure.txt
index d4783a2b..d66bcd34 100644
--- a/doc/source/install/common_configure.txt
+++ b/doc/source/install/common_configure.txt
@@ -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_
-        ...
+        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
+        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://trove:TROVE_DBPASS@controller/trove
+        connection = mysql+pymysql://root:password@127.0.0.1/trove?charset=utf8
 
-   * Configure the Database service to use the ``RabbitMQ`` message broker
-     by setting the following options in each file:
+        [mariadb]
+        tcp_ports = 3306,4444,4567,4568
 
-     .. code-block:: ini
+        [mysql]
+        tcp_ports = 3306
 
-        [DEFAULT]
-        ...
-        rpc_backend = rabbit
-        transport_url = rabbit://<rabbit_userid>:<rabbit_password>@<rabbit_host>:5672
+        [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.
-
diff --git a/doc/source/install/get_started.rst b/doc/source/install/get_started.rst
index ac8aca67..f84df61d 100644
--- a/doc/source/install/get_started.rst
+++ b/doc/source/install/get_started.rst
@@ -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.
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
index d14d1027..17d209bf 100644
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@@ -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
diff --git a/doc/source/install/install-manual.rst b/doc/source/install/install-manual.rst
index 563e23a4..36af8e0f 100644
--- a/doc/source/install/install-manual.rst
+++ b/doc/source/install/install-manual.rst
@@ -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
 ~~~~~~~~~
diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-redhat.rst
index aa15662a..3a7bf765 100644
--- a/doc/source/install/install-rdo.rst
+++ b/doc/source/install/install-redhat.rst
@@ -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.
diff --git a/doc/source/install/install-obs.rst b/doc/source/install/install-suse.rst
index 884286b7..6af627f3 100644
--- a/doc/source/install/install-obs.rst
+++ b/doc/source/install/install-suse.rst
@@ -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.
 
diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/install/install-ubuntu.rst
index cec20c23..1b67dd0a 100644
--- a/doc/source/install/install-ubuntu.rst
+++ b/doc/source/install/install-ubuntu.rst
@@ -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
 
diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst
index f02eff78..ffeedff6 100644
--- a/doc/source/install/verify.rst
+++ b/doc/source/install/verify.rst
@@ -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>`_.