diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | install-guide/source/common_configure.txt | 106 | ||||
| -rw-r--r-- | install-guide/source/common_prerequisites.txt | 137 | ||||
| -rw-r--r-- | install-guide/source/conf.py | 300 | ||||
| -rw-r--r-- | install-guide/source/get_started.rst | 66 | ||||
| -rw-r--r-- | install-guide/source/index.rst | 17 | ||||
| -rw-r--r-- | install-guide/source/install-obs.rst | 45 | ||||
| -rw-r--r-- | install-guide/source/install-rdo.rst | 37 | ||||
| -rw-r--r-- | install-guide/source/install-ubuntu.rst | 80 | ||||
| -rw-r--r-- | install-guide/source/install.rst | 24 | ||||
| -rw-r--r-- | install-guide/source/next-steps.rst | 9 | ||||
| -rw-r--r-- | install-guide/source/verify.rst | 91 | ||||
| -rw-r--r-- | test-requirements.txt | 1 | ||||
| -rw-r--r-- | tox.ini | 7 |
14 files changed, 921 insertions, 0 deletions
@@ -25,6 +25,7 @@ trove.iml # Sphinx doc/build/* doc/source/api/* +install-guide/build/ # Docs .DS_Store diff --git a/install-guide/source/common_configure.txt b/install-guide/source/common_configure.txt new file mode 100644 index 00000000..d2c001d9 --- /dev/null +++ b/install-guide/source/common_configure.txt @@ -0,0 +1,106 @@ +2. In the ``/etc/trove`` directory, edit the ``trove.conf``, + ``trove-taskmanager.conf`` and ``trove-conductor.conf`` files and + complete the following steps: + + * Provide appropriate values for the following settings: + + .. code-block:: ini + + [DEFAULT] + log_dir = /var/log/trove + trove_auth_url = http://controller:5000/v2.0 + nova_compute_url = http://controller:8774/v2 + cinder_url = http://controller:8776/v1 + swift_url = http://controller:8080/v1/AUTH_ + notifier_queue_hostname = controller + ... + [database] + connection = mysql://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] + ... + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + +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 <http://git.openstack.org/cgit/openstack/trove/plain/etc/trove/api-paste.ini?h=stable/mitaka>`__. + +4. Edit the ``trove.conf`` file so it includes appropriate values for the + settings shown below: + + .. 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] + ... + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + auth_type = password + project_domain_name = default + user_domain_name = default + project_name = service + username = trove + 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: + + .. 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 + +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 + nova_proxy_admin_user = admin + nova_proxy_admin_pass = ADMIN_PASS + nova_proxy_admin_tenant_name = service + trove_auth_url = http://controller:35357/v2.0 + +7. Populate the trove database you created earlier in this procedure: + + .. code-block:: console + + # su -s /bin/sh -c "trove-manage db_sync" trove + ... + 2016-04-06 22:00:17.771 10706 INFO trove.db.sqlalchemy.migration [-] + Upgrading mysql://trove:dbaasdb@controller/trove to version latest + + .. note:: + + Ignore any deprecation messages in this output. + diff --git a/install-guide/source/common_prerequisites.txt b/install-guide/source/common_prerequisites.txt new file mode 100644 index 00000000..cb4a1d73 --- /dev/null +++ b/install-guide/source/common_prerequisites.txt @@ -0,0 +1,137 @@ +Prerequisites +------------- + +Before you install and configure the Database service, you must create a +database, service credentials, and API endpoints. + +#. To create the database, complete these steps: + + * Use the database access client to connect to the database + server as the ``root`` user: + + .. code-block:: console + + $ mysql -u root -p + + * Create the ``trove`` database: + + .. code-block:: console + + CREATE DATABASE trove; + + * Grant proper access to the ``trove`` database: + + .. code-block:: console + + GRANT ALL PRIVILEGES ON trove.* TO 'trove'@'localhost' \ + IDENTIFIED BY 'TROVE_DBPASS'; + GRANT ALL PRIVILEGES ON trove.* TO 'trove'@'%' \ + IDENTIFIED BY 'TROVE_DBPASS'; + + Replace ``TROVE_DBPASS`` with a suitable password. + + * Exit the database access client. + +#. Source the ``admin`` credentials to gain access to + admin-only CLI commands: + + .. code-block:: console + + $ . admin-openrc + +#. To create the service credentials, complete these steps: + + * Create the ``trove`` user: + + .. code-block:: console + + $ openstack user create --domain default --password-prompt trove + User Password: + Repeat User Password: + +-----------+-----------------------------------+ + | Field | Value | + +-----------+-----------------------------------+ + | domain_id | default | + | enabled | True | + | id | ca2e175b851943349be29a328cc5e360 | + | name | trove | + +-----------+-----------------------------------+ + + * Add the ``admin`` role to the ``trove`` user: + + .. code-block:: console + + $ openstack role add --project service --user trove admin + + .. note:: + + This command provides no output. + + * Create the ``trove`` service entity: + + .. code-block:: console + + $ openstack service create --name trove \ + --description "Database" database + +-------------+-----------------------------------+ + | Field | Value | + +-------------+-----------------------------------+ + | description | Database | + | enabled | True | + | id | 727841c6f5df4773baa4e8a5ae7d72eb | + | name | trove | + | type | database | + +-------------+-----------------------------------+ + + +#. Create the Database service API endpoints: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + database public http://controller:8779/v1.0/%\(tenant_id\)s + +--------------+----------------------------------------------+ + | Field | Value | + +--------------+----------------------------------------------+ + | enabled | True | + | id | 3f4dab34624e4be7b000265f25049609 | + | interface | public | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 727841c6f5df4773baa4e8a5ae7d72eb | + | service_name | trove | + | service_type | database | + | url | http://controller:8779/v1.0/%\(tenant_id\)s | + +--------------+----------------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + database internal http://controller:8779/v1.0/%\(tenant_id\)s + +--------------+----------------------------------------------+ + | Field | Value | + +--------------+----------------------------------------------+ + | enabled | True | + | id | 9489f78e958e45cc85570fec7e836d98 | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 727841c6f5df4773baa4e8a5ae7d72eb | + | service_name | trove | + | service_type | database | + | url | http://controller:8779/v1.0/%\(tenant_id\)s | + +--------------+----------------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + database admin http://controller:8779/v1.0/%\(tenant_id\)s + +--------------+----------------------------------------------+ + | Field | Value | + +--------------+----------------------------------------------+ + | enabled | True | + | id | 76091559514b40c6b7b38dde790efe99 | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 727841c6f5df4773baa4e8a5ae7d72eb | + | service_name | trove | + | service_type | database | + | url | http://controller:8779/v1.0/%\(tenant_id\)s | + +--------------+----------------------------------------------+ diff --git a/install-guide/source/conf.py b/install-guide/source/conf.py new file mode 100644 index 00000000..bb91c1e7 --- /dev/null +++ b/install-guide/source/conf.py @@ -0,0 +1,300 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +# import sys + + +import openstackdocstheme + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' +# extensions = + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Installation Guide for Database Service Service' +bug_tag = u'install-guide' +copyright = u'2016, OpenStack contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# A few variables have to be set for the log-a-bug feature. +# giturl: The location of conf.py on Git. Must be set manually. +# gitsha: The SHA checksum of the bug description. Automatically +# extracted from git log. +# bug_tag: Tag for categorizing the bug. Must be set manually. +# These variables are passed to the logabug code via html_context. +giturl = u'http://git.openstack.org/cgit/openstack/trove/tree/install-guide/source' # noqa +git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '" +gitsha = os.popen(git_cmd).read().strip('\n') +html_context = {"gitsha": gitsha, "bug_tag": bug_tag, + "giturl": giturl} + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'openstackdocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = [openstackdocstheme.get_html_theme_path()] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = [] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# So that we can enable "log-a-bug" links from each output HTML page, this +# variable must be set to a format that includes year, month, day, hours and +# minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'install-guide' + +# If true, publish source files +html_copy_source = False + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # 'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'InstallGuide.tex', u'Install Guide', + u'OpenStack contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'installguide', u'Install Guide', + [u'OpenStack contributors'], 1) +] + +# If true, show URL addresses after external links. +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'InstallGuide', u'Install Guide', + u'OpenStack contributors', 'InstallGuide', + 'This guide shows OpenStack end users how to install ' + 'an OpenStack cloud.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + +# -- Options for Internationalization output ------------------------------ +locale_dirs = ['locale/'] + +# -- Options for PDF output -------------------------------------------------- + +pdf_documents = [ + ('index', u'InstallGuide', u'Install Guide', + u'OpenStack contributors') +] diff --git a/install-guide/source/get_started.rst b/install-guide/source/get_started.rst new file mode 100644 index 00000000..ac8aca67 --- /dev/null +++ b/install-guide/source/get_started.rst @@ -0,0 +1,66 @@ +========================= +Database service overview +========================= + +The Database service provides scalable and reliable cloud provisioning +functionality for both relational and non-relational database engines. +Users can quickly and easily use database features without the burden of +handling complex administrative tasks. Cloud users and database +administrators can provision and manage multiple database instances as +needed. + +The Database service provides resource isolation at high performance +levels, and automates complex administrative tasks such as deployment, +configuration, patching, backups, restores, and monitoring. + +**Process flow example** + +This example is a high-level process flow for using Database services: + +#. The OpenStack Administrator configures the basic infrastructure using + the following steps: + + #. Install the Database service. + #. Create an image for each type of database. For example, one for MySQL + and one for MongoDB. + #. Use the :command:`trove-manage` command to import images and offer them + to tenants. + +#. 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. + #. Access the Database service instance using typical database access + commands. For example, with MySQL: + + .. code-block:: console + + $ mysql -u myuser -p -h TROVE_IP_ADDRESS mydb + +**Components** + +The Database service includes the following components: + +``python-troveclient`` command-line client + 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. + +``trove-conductor`` service + Runs on the host, and receives messages from guest instances that + want to update information on the host. + +``trove-taskmanager`` service + Instruments the complex system flows that support provisioning + instances, managing the lifecycle of instances, and performing + operations on instances. + +``trove-guestagent`` service + Runs within the guest instance. Manages and performs operations on + the database itself. diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst new file mode 100644 index 00000000..ffe14144 --- /dev/null +++ b/install-guide/source/index.rst @@ -0,0 +1,17 @@ +================ +Database service +================ + +.. toctree:: + + get_started.rst + install.rst + verify.rst + next-steps.rst + + +The Database service (trove) provides cloud provisioning functionality +for database engines. + +This chapter assumes a working setup of OpenStack following the +`OpenStack Installation Tutorial <http://docs.openstack.org/#install-guides>`_. diff --git a/install-guide/source/install-obs.rst b/install-guide/source/install-obs.rst new file mode 100644 index 00000000..0c481179 --- /dev/null +++ b/install-guide/source/install-obs.rst @@ -0,0 +1,45 @@ +.. _install-obs: + + +Install and configure for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Database service +for openSUSE Leap 42.1 and SUSE Linux Enterprise Server 12 SP1. + +.. include:: common_prerequisites.txt + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # zypper --quiet --non-interactive install python-oslo.db \ + python-MySQL-python + + # zypper --quiet --non-interactive install openstack-trove-api \ + openstack-trove-taskmanager openstack-trove-conductor \ + openstack-trove-guestagent + + +.. include:: common_configure.txt + + +Finalize installation +--------------------- + +Start the Database services and configure them to start when +the system boots: + +.. code-block:: console + + # systemctl enable openstack-trove-api.service \ + openstack-trove-taskmanager.service \ + openstack-trove-conductor.service + + # systemctl start openstack-trove-api.service \ + openstack-trove-taskmanager.service \ + openstack-trove-conductor.service + diff --git a/install-guide/source/install-rdo.rst b/install-guide/source/install-rdo.rst new file mode 100644 index 00000000..aa15662a --- /dev/null +++ b/install-guide/source/install-rdo.rst @@ -0,0 +1,37 @@ +.. _install-rdo: + +Install and configure for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +This section describes how to install and configure the Database service +for Red Hat Enterprise Linux 7 and CentOS 7. + +.. include:: common_prerequisites.txt + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # yum install openstack-trove python-troveclient + +.. include:: common_configure.txt + +Finalize installation +--------------------- + +Start the Database services and configure them to start when +the system boots: + +.. code-block:: console + + # systemctl enable openstack-trove-api.service \ + openstack-trove-taskmanager.service \ + openstack-trove-conductor.service + + # systemctl start openstack-trove-api.service \ + openstack-trove-taskmanager.service \ + openstack-trove-conductor.service diff --git a/install-guide/source/install-ubuntu.rst b/install-guide/source/install-ubuntu.rst new file mode 100644 index 00000000..3509db4c --- /dev/null +++ b/install-guide/source/install-ubuntu.rst @@ -0,0 +1,80 @@ +.. _install-ubuntu: + +Install and configure for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Orchestration +service for Ubuntu 14.04 (LTS). + +This section assumes that you already have a working OpenStack +environment with at least the following components installed: +Compute, Image Service, Identity. + +* If you want to do backup and restore, you also need Object Storage. + +* If you want to provision datastores on block-storage volumes, you also + need Block Storage. + + +.. include:: common_prerequisites.txt + + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get update + + # apt-get install python-trove python-troveclient \ + python-glanceclient trove-common trove-api trove-taskmanager \ + trove-conductor + + +.. include:: common_configure.txt + + +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: + + .. code-block:: console + + # service trove-api restart + # service trove-taskmanager restart + # service trove-conductor restart diff --git a/install-guide/source/install.rst b/install-guide/source/install.rst new file mode 100644 index 00000000..3e93c533 --- /dev/null +++ b/install-guide/source/install.rst @@ -0,0 +1,24 @@ +.. _trove-install: + +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Database service, code-named trove, on the controller node. + +This section assumes that you already have a working OpenStack +environment with at least the following components installed: +Compute, Image Service, Identity. + +* If you want to do backup and restore, you also need Object Storage. + +* If you want to provision datastores on block-storage volumes, you also + need Block Storage. + +Note that installation and configuration vary by distribution. + +.. toctree:: + + install-obs.rst + install-rdo.rst + install-ubuntu.rst diff --git a/install-guide/source/next-steps.rst b/install-guide/source/next-steps.rst new file mode 100644 index 00000000..19ab5d6f --- /dev/null +++ b/install-guide/source/next-steps.rst @@ -0,0 +1,9 @@ +.. _trove-next-steps: + +Next steps +~~~~~~~~~~ + +Your OpenStack environment now includes Database services. + +To add more services, see the `additional OpenStack install documentation +<http://docs.openstack.org/#install-guides>`_. diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst new file mode 100644 index 00000000..65fc7edf --- /dev/null +++ b/install-guide/source/verify.rst @@ -0,0 +1,91 @@ +.. _trove-verify: + +Verify operation +~~~~~~~~~~~~~~~~ + +Verify operation of the Database service. + +.. note:: + + Perform these commands on the node where you installed trove. + +#. Source the ``admin`` tenant credentials: + + .. code-block:: console + + $ . admin-openrc + +#. Run the ``trove list`` command. You should see output similar to this: + + .. code-block:: console + + $ trove list + +----+------+-----------+-------------------+--------+-----------+------+ + | id | name | datastore | datastore_version | status | flavor_id | size | + +----+------+-----------+-------------------+--------+-----------+------+ + +----+------+-----------+-------------------+--------+-----------+------+ + +#. Add a datastore to trove: + + * `Create a trove image <http://docs.openstack.org/developer/trove/dev/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 | + +------------------+--------------------------------------+ + + * 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 + MySQL database: + + .. 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. + +#. Create a database `instance + <http://docs.openstack.org/user-guide/create_db.html>`_. diff --git a/test-requirements.txt b/test-requirements.txt index 54a7a4bd..c260c715 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -11,6 +11,7 @@ coverage>=3.6 # Apache-2.0 nose # LGPL nosexcover # BSD openstack-doc-tools>=0.23 # Apache-2.0 +openstackdocstheme>=1.0.3 # Apache-2.0 openstack.nose-plugin>=0.7 # Apache-2.0 WebTest>=2.0 # MIT wsgi-intercept>=0.6.1 # MIT License @@ -172,3 +172,10 @@ commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasen [testenv:bandit] commands = bandit -r trove -n5 -x tests + +[testenv:install-guide] +# NOTE(jaegerandi): this target does not use constraints because +# upstream infra does not yet support it. Once that's fixed, we can +# drop the install_command. +install_command = pip install -U --force-reinstall {opts} {packages} +commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html |