Merge "document configure and verify steps"

doc/source/dev/guest_cloud_init.rst

@@ -0,0 +1,74 @@
+.. _guest_cloud_init:
+
+.. role:: bash(code)
+   :language: bash
+
+===========================
+Guest Images via Cloud-Init
+===========================
+
+.. If section numbers are desired, unindent this
+    .. sectnum::
+
+.. If a TOC is desired, unindent this
+    .. contents::
+
+Overview
+========
+
+While creating an image is the preferred method for providing a base
+for the Guest Instance, there may be cases where creating an image
+is impractical. In those cases a Guest instance can be based on
+an available Cloud Image and configured at boot via cloud-init.
+
+Currently the most tested Guest image is Ubunutu 14.04 (trusty).
+
+Setting up the Image
+====================
+
+* Visit the `Ubuntu Cloud Archive <https://cloud-images.ubuntu.com/trusty/20160816>`_ and download ``trusty-server-cloudimg-amd64-disk1.img``.
+
+* Upload that image to glance, and note the glance ID for the image.
+
+* Cloud-Init files go into the directory set by the ``cloudinit_location``
+  configuration parameter, usually ``/etc/trove/cloudinit``. Files in
+  that directory are of the format ``[datastore].cloudinit``, for
+  example ``mysql.cloudinit``.
+
+* Create a cloud-init file for your datastore and put it into place.
+  For this example, it is assumed you are using Ubuntu 14.04, with
+  the MySQL database and a Trove Agent from the Mitaka release. You
+  would put this into ``/etc/trove/cloudinit/mysql.cloudinit``.
+
+.. code-block:: console
+
+    #cloud-config
+    # For Ubuntu-14.04 cloudimage
+    apt_sources:
+    - source: "cloud-archive:mitaka"
+    packages:
+    - trove-guestagent
+    - mysql-server-5.5
+    write_files:
+    - path: /etc/sudoers.d/trove
+      content: |
+        Defaults:trove !requiretty
+        trove ALL=(ALL) NOPASSWD:ALL
+    runcmd:
+    - stop trove-guestagent
+    - cat /etc/trove/trove-guestagent.conf /etc/trove/conf.d/guest_info.conf >/etc/trove/trove.conf
+    - start trove-guestagent
+
+
+* If you need to debug guests failing to launch simply append
+  the cloud-init to add a user to allow you to login and
+  debug the instance.
+
+* When using ``trove-manage datastore_version_update`` to
+  define your datastore simply use the Glance ID you have for
+  the Trusty Cloud image.
+
+When trove launches the Guest Instance, the cloud-init will install
+the Mitaka Trove Guest Agent and MySQL database, and then adjust
+the configuration files and launch the Guest Agent.
+

doc/source/index.rst

@@ -48,6 +48,7 @@ functionality, the following resources are provided.
   dev/install
   dev/manual_install.rst
   dev/building_guest_images.rst
+  dev/guest_cloud_init.rst
   dev/notifier.rst
   dev/trove_api_extensions.rst
 

install-guide/source/common_configure.txt

@@ -63,7 +63,11 @@
       password = TROVE_PASS
 
 5. Edit the ``trove-taskmanager.conf`` file so it includes the required
-   settings to connect to the OpenStack Compute service as shown below:
+   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
 
@@ -79,6 +83,13 @@
       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:
 

install-guide/source/dashboard.rst

@@ -0,0 +1,28 @@
+
+.. _dashboard:
+
+Install and configure the Trove dashboard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  * Installation of the Trove dashboard for Horizon is straightforward.
+    While there packages available for Mitaka, they have a `bug
+    <https://bugs.launchpad.net/trove-dashboard/+bug/1580527>`_
+    which prevents network selection while creating instances.
+    So it is best to install via pip.
+
+   .. code-block:: console
+
+      # pip install trove-dashboard
+
+  * The command above will install the latest version which is
+    appropriate if you are running the latest Trove. If you are
+    running an earlier version of Trove you may need to specify
+    a compatible version of trove-dashboard. 7.0.0.0b2 is known
+    to work with the Mitaka release of Trove.
+
+  * After pip installs them locate the trove-dashboard directory and
+    copy the contents of the ``enabled/`` directory to your horizon
+    ``openstack_dashboard/local/enabled/`` directory.
+
+  * Reload apache to pick up the changes to Horizon.
+

install-guide/source/index.rst

@@ -6,6 +6,7 @@ Database service
 
    get_started.rst
    install.rst
+   dashboard.rst
    verify.rst
    next-steps.rst
 

install-guide/source/verify.rst

@@ -61,6 +61,12 @@ Verify operation of the Database service.
         | 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
+     <http://docs.openstack.org/developer/trove/dev/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
      each type of database you want to use, for example, MySQL, MongoDB,
      Cassandra. This example shows you how to create a datastore for a