Objectives¶

This document provides a step-by-step guide for manual installation of Trove with an existing OpenStack environment for development purposes.

This document will not cover:

• OpenStack setup
• Trove service configuration

Requirements¶

A running OpenStack environment is required, including the following components:

• Compute (Nova)
• Image Service (Glance)
• Identity (Keystone)
• Network (Neutron)
• If you want to provision datastores on block-storage volumes, you also will need Block Storage (Cinder)
• If you want to do backup/restore and replication, you will also need Object Storage (Swift)
• An environment with a freshly installed Ubuntu 16.04 LTS to run Trove services. This will be referred to as “local environment”
• AMQP service (RabbitMQ or QPID)
• MySQL (SQLite, PostgreSQL) database for Trove’s internal needs, accessible from the local environment

• Certain OpenStack services must be accessible from VMs:

  • Swift

• VMs must be accessible from local environment for development/debugging purposes

• OpenStack services must be accessible directly from the local environment, such as:

  • Nova
  • Cinder
  • Swift
  • Heat

Installation¶

$ sudo apt-get install build-essential libxslt1-dev qemu-utils mysql-client \
  git python-dev python-pexpect python-pymysql libmysqlclient-dev

$ cd ~
$ tar xfvz setuptools-{{latest}}.tar.gz
$ cd setuptools-{{latest}}
$ python setup.py install --user

$ tar xfvz pip-{{latest}}.tar.gz
$ cd pip-{{latest}}
$ python setup.py install --user

$ echo PATH="$HOME/.local/bin:$PATH" >> ~/.profile
$ . ~/.profile

$ pip install virtualenv --user
$ virtualenv --system-site-packages env
$ . env/bin/activate

$ cd ~
$ git clone https://git.openstack.org/openstack/trove.git
$ git clone https://git.openstack.org/openstack/python-troveclient.git

Install Trove¶

First, install the requirements:

$ cd ~/trove
$ pip install -r requirements.txt -r test-requirements.txt

Then, install Trove:

$ sudo python setup.py develop

Finally, install the Trove client:

$ cd ~/python-troveclient
$ sudo python setup.py develop
$ cd ~

Other required OpenStack clients (python-novaclient, python-keystoneclient, etc.) should already be installed as part of the Trove requirements.

$ keystone --os-username <OpenStackAdminUsername> --os-password <OpenStackAdminPassword> --os-tenant-name <OpenStackAdminTenant> --os-auth-url http://<KeystoneIP>:<KeystonePort>/v2.0 tenant-create --user trove_for_trove_usage

$ keystone --os-username <OpenStackAdminUsername> --os-password <OpenStackAdminPassword> --os-tenant-name <OpenStackAdminTenant> --os-auth-url http://<KeystoneIP>:<KeystonePort>/v2.0 user-create --user regular_trove_user --pass trove --tenant trove_for_trove_usage

$ keystone --os-username <OpenStackAdminUsername> --os-password <OpenStackAdminPassword> --os-tenant-name <OpenStackAdminTenant> --os-auth-url http://<KeystoneIP>:<KeystonePort>/v2.0 user-create --user admin_trove_user --pass trove --tenant trove_for_trove_usage

$ keystone --os-username <OpenStackAdminUsername> --os-password <OpenStackAdminPassword> --os-tenant-name <OpenStackAdminTenant> --os-auth-url http://<KeystoneIP>:<KeystonePort>/v2.0 user-role-add --user admin_trove_user --tenant trove_for_trove_usage --role admin

$ keystone --os-username <OpenStackAdminUsername> --os-password <OpenStackAdminPassword> --os-tenant-name <OpenStackAdminTenant> --os-auth-url http://<KeystoneIP>:<KeystonePort>/v2.0 service-create --user trove --type database

$ keystone --os-username <OpenStackAdminUsername> --os-password <OpenStackAdminPassword> --os-tenant-name <OpenStackAdminTenant> --os-auth-url http://<KeystoneIP>:<KeystonePort>/v2.0 endpoint-create --service trove --region RegionOne --publicurl 'http://<EnvironmentPublicIP>:<EnvironmentPort>/v1.0/$(tenant_id)s' --adminurl 'http://<EnvironmentPublicIP>:<EnvironmentPort>/v1.0/$(tenant_id)s' --internalurl 'http://<EnvironmentPublicIP>:<EnvironmentPort>/v1.0/$(tenant_id)s'

Prepare Trove configuration files¶

There are several configuration files for Trove:

• api-paste.ini and trove.conf — For trove-api service
• trove-taskmanager.conf — For trove-taskmanager service
• trove-guestagent.conf — For trove-guestagent service
• trove-conductor.conf — For trove-conductor service
• <datastore_manager>.cloudinit — Userdata for VMs during provisioning

Cloud-init scripts are userdata that is being used for different datastore types like mysql/percona, cassandra, mongodb, redis, couchbase while provisioning new compute instances.

Samples of the above are available in ~/trove/etc/trove/ as *.conf.sample files.

If a clean Ubuntu image is used as the source image for Trove instances, the cloud-init script must install and run guestagent in the instance.

As an alternative, one may consider creating a custom image with pre-installed and pre-configured Trove in it.

Source images¶

As the source image for Trove instances, we will use a Trove-compatible Ubuntu image:

$ export DATASTORE_TYPE="mysql"
$ wget http://tarballs.openstack.org/trove/images/ubuntu/${DATASTORE_TYPE}.qcow2
$ glance --os-username admin_trove_user --os-password trove --os-tenant-name trove_for_trove_usage --os-auth-url http://<KeystoneIP>:<KeystoneAdminPort>/v2.0 image-create --name trove-image --is-public True --container-format ovf --disk-format qcow2 --file ${DATASTORE_TYPE}.qcow2

Note: http://tarballs.openstack.org/trove/images includes mysql, percona, mongodb Trove-compatible images.

At this step please remember the image ID or store it in an environment variable (IMAGEID).

$ glance --os-username trove --os-password trove --os-tenant-name trove --os-auth-url http://<KeystoneIP>:<KeystoneAdminPort>/v2.0
    image-create --name trove-image --is-public true --container-format ovf --disk-format qcow2 --owner trove < precise.qcow2

$ export IMAGEID=<glance_image_id>

Cloud-init scripts¶

Custom images with Trove code inside¶

To be added

Prepare the database¶

Create the Trove database schema:

• Connect to the storage backend (MySQL, PostgreSQL)
• Create a database called trove (this database will be used for storing Trove ORM)
• Compose connection string. Example: mysql+pymysql://<user>:<password>@<backend_host>:<backend_port>/<database_name>

Initialize the database¶

Once the database for Trove is created, its structure needs to be populated.

$ trove-manage db_sync

Setup Trove Datastores¶

- ID -- simple auto-generated UUID
- Name -- user-defined attribute, actual name of a datastore
- Datastore Versions

- mysql, cassandra, redis, etc.

- ID — Simple auto-generated UUID
- Datastore ID — Reference to Datastore
- Name — User-defined attribute, actual name of a database version
- Datastore manager — trove-guestagent manager that is used for datastore management
- Image ID — Reference to a specific Glance image ID
- Packages — Operating system specific packages that would be deployed onto datastore VM
- Active — Boolean flag that defines if version can be used for instance deployment or not

- ID - edb1d22a-b66d-4e86-be60-756240439272
- Datastore ID - 9c3d890b-a2f2-4ba5-91b2-2997d0791502
- Name - mysql-5.7
- Datastore manager - mysql
- Image ID - d73a402-3953-4721-8c99-86fc72e1cb51
- Packages - mysql-server=5.7, percona-xtrabackup=2.4
- Active - True

$ export DATASTORE_TYPE="mysql" # available options: mysql, mongodb, postgresql, redis, cassandra, couchbase, couchdb, db2, vertica, etc.

$ export DATASTORE_VERSION="5.7" # available options: for cassandra 2.0.x, for mysql: 5.x, for mongodb: 2.x.x, etc.

$ export PACKAGES="mysql-server-5.7" # available options: cassandra=2.0.9, mongodb=2.0.4, etc

$ export IMAGEID="9910350b-77e3-4790-86be-b971d0cf9175" # Glance image ID of the relevant Datastore version (see Source images section)

$ trove-manage datastore_update ${DATASTORE_TYPE} ""

$ trove-manage datastore_version_update ${DATASTORE_TYPE} ${DATASTORE_VERSION} ${DATASTORE_TYPE} ${IMAGEID} ${PACKAGES} 1

$ trove-manage datastore_update ${DATASTORE_TYPE} ${DATASTORE_VERSION}

Trove services configuration and tuning¶

To be added

Starting Trove services¶

Run trove-api:

$ trove-api --config-file=${TROVE_CONF_DIR}/trove-api.conf &

Run trove-taskmanager:

$ trove-taskmanager --config-file=${TROVE_CONF_DIR}/trove-taskamanger.conf &

Run trove-conductor:

$ trove-conductor --config-file=${TROVE_CONF_DIR}/trove-conductor.conf &

Keystonerc¶

You need to build a keystonerc file that contains data to simplify the auth processes while using the Trove client:

export OS_TENANT_NAME=trove

export OS_USERNAME=regular_trove_user

export OS_PASSWORD=trove

export OS_AUTH_URL="http://<KeystoneIP>:<KeystonePort>/v2.0/"

export OS_AUTH_STRATEGY=keystone

Trove deployment verification¶

First you need to execute:

$ . keystonerc

To see help for a specific command:

$ trove help <command>

To create an instance:

$ trove create <name> <flavor_id>
                [--size <size>]
                [--databases <databases> [<databases> ...]]
                [--users <users> [<users> ...]] [--backup <backup>]
                [--availability_zone <availability_zone>]
                [--datastore <datastore>]
                [--datastore_version <datastore_version>]
                [--nic <net-id=net-uuid,v4-fixed-ip=ip-addr,port-id=port-uuid>]
                [--configuration <configuration>]
                [--replica_of <source_id>]

No instance IPs in the output of ‘trove show <instance_id>’¶

If the Trove instance was successfully created, is showing ACTIVE state and working, yet there is no IP address for the instance shown in the output of ‘trove show <instance_id>, then confirm the following lines are added to trove.conf

network_label_regex = ^NETWORK_NAME$

where NETWORK_NAME should be replaced with real name of the network to which the instance is connected to.

To decide which network would you like to attach a Trove instance to, run the following command:

$ openstack network list

One possible way to find the network name is to execute the ‘nova list’ command. The output will list all OpenStack instances for the tenant, including network information. Look for

NETWORK_NAME=IP_ADDRESS

Additional information¶

Additional information can be found in the OpenStack installation guide for the trove project. This document can be found under the “Installation Tutorials and Guides” section of the OpenStack Documentation.

For the current documentation, visit:

http://docs.openstack.org/index.html#install-guides

Select the link for “Installation Tutorials and Guides”

The installation guides for trove (the Database Service) can be found under the appropriate operating system.

If you are interested in documentation for a specific OpenStack release, visit:

http://docs.openstack.org/<release-code-name>/

For example, the documentation for the Pike release is found at:

http://docs.openstack.org/pike/

and the documentation for the Queens release is found at:

http://docs.openstack.org/queens/