From d1fd1ac32dedcfec6285c1f5a0e81871df3d2120 Mon Sep 17 00:00:00 2001 From: Greg Retkowski Date: Tue, 16 Aug 2016 22:47:43 -0700 Subject: [PATCH] document configure and verify steps This improves the documentation for the installation of Trove. The following items were documented: * Required ConfigDrive parameter change for taskmanager * Network regex and driver for Neutron * Installation of the trove-dashboard component * Using cloud-init as an alternative for guest-images Change-Id: I1c5d5bab9e4e73f139bba645cda925176abcce82 Partial-Bug: 1610466 --- doc/source/dev/guest_cloud_init.rst | 74 +++++++++++++++++++++++ doc/source/index.rst | 1 + install-guide/source/common_configure.txt | 13 +++- install-guide/source/dashboard.rst | 28 +++++++++ install-guide/source/index.rst | 1 + install-guide/source/verify.rst | 6 ++ 6 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 doc/source/dev/guest_cloud_init.rst create mode 100644 install-guide/source/dashboard.rst diff --git a/doc/source/dev/guest_cloud_init.rst b/doc/source/dev/guest_cloud_init.rst new file mode 100644 index 0000000000..eb95f203dd --- /dev/null +++ b/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 `_ 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. + diff --git a/doc/source/index.rst b/doc/source/index.rst index d9d9a4400b..4e0d9514ab 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/install-guide/source/common_configure.txt b/install-guide/source/common_configure.txt index eef5b28848..e768daaf7c 100644 --- a/install-guide/source/common_configure.txt +++ b/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: diff --git a/install-guide/source/dashboard.rst b/install-guide/source/dashboard.rst new file mode 100644 index 0000000000..475da46491 --- /dev/null +++ b/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 + `_ + 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. + diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst index ffe1414495..a88d5ac41d 100644 --- a/install-guide/source/index.rst +++ b/install-guide/source/index.rst @@ -6,6 +6,7 @@ Database service get_started.rst install.rst + dashboard.rst verify.rst next-steps.rst diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst index 65fc7edf8c..104f7a2fd7 100644 --- a/install-guide/source/verify.rst +++ b/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 + `_ . + 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