diff --git a/README.rst b/README.rst index f67c0f92cf..d67b34f46f 100644 --- a/README.rst +++ b/README.rst @@ -11,7 +11,7 @@ To quickly run the tests for Python 2.7, run: $ tox -epy27 To quickly run PEP8, run: -$ to -epep8 +$ tox -epep8 To generate a coverage report,run: $ tox -ecover diff --git a/doc/source/dev/manual_install.rst b/doc/source/dev/manual_install.rst new file mode 100644 index 0000000000..74d9cc08a7 --- /dev/null +++ b/doc/source/dev/manual_install.rst @@ -0,0 +1,260 @@ +.. _manual_install: + +========================= +Manual Trove Installation +========================= + +Objectives +========== + +This document is aimed to provide a step-by-step guide for manual installation of Trove with an existing OpenStack +environment for development purposes. + +This document does not cover OpenStack setup. + +This document does not cover production-specific moments like high availability or security. + +This document does not cover all possible configurations. It only provides one possible way to get things +running. + +Requirements +============ + +- PC with freshly installed Ubuntu 12.04 to run Trove services. This will be referred to as "local PC" + +- Running Openstack Grizzly environment. All of Grizzly's services must be accessible directly from the local PC + +- AMQP service provided by RabbitMQ + +- MySQL database for Trove's internal needs, accessible from the local PC + +- Though it is not required by OpenStack itself, all OpenStack services must be accessible via network from virtual machines + +- Trove's database must be accessible from VMs, i.e. one must be able to connect to DB from VM + +- VMs must be accessible from local PC (same network) + +Installation +============ + +----------- +Gather info +----------- + +.. + TODO: Requirements below (e.g. admin credentials) are obviously excessive. Try to use regular account. + +The following information about existing environment is required: + +- Keystone host and port(s) + +- OpenStack administrator's username, tenant and password + +- Nova compute URL + +- Cinder URL + +- Swift URL + +- RabbitMQ URL, user Id, password + +- Trove's MySQL connection string + +-------------------- +Install dependencies +-------------------- +* Install required packages:: + + # sudo apt-get install build-essential libxslt1-dev qemu-utils mysql-client git python-dev python-pexpect python-mysqldb + +* Some packages in Ubuntu repo are outdated, so install their latest version from sources:: + + # cd ~ + # wget https://pypi.python.org/packages/source/s/setuptools/setuptools-0.9.8.tar.gz + # tar xfvz setuptools-0.9.8.tar.gz + # cd setuptools-0.9.8 + # python setup.py install --user + + # cd ~ + # wget https://pypi.python.org/packages/source/p/pip/pip-1.4.1.tar.gz + # tar xfvz pip-1.4.1.tar.gz + # cd pip-1.4.1 + # python setup.py install --user + + # cd ~ + +* Note '--user' above -- we installed packages in user's home dir, in $HOME/.local/bin, so we need to add it to path:: + + # echo PATH="$HOME/.local/bin:$PATH" >> ~/.profile + # . ~/.profile + +* Install virtualenv, create environment and activate it:: + + # pip install virtualenv --user + # virtualenv --system-site-packages env + # . env/bin/activate + + +------------ +Obtain Trove +------------ +* Get Trove's sources from git:: + + # git clone https://github.com/openstack/trove.git + # git clone https://github.com/openstack/python-troveclient.git + +------------- +Install Trove +------------- +* First install required python packages:: + + # cd ~/trove + # pip install -r requirements.txt + +* Resolve dependency conflicts (if there are any) + +Trove is being built and tested against latest versions of OpenStack components that can be obtained from GitHub. +But setup downloads dependencies from PyPI which may contain outdated versions. This may cause a dependency conflicts. +E.g. for now python-cinderclient from PyPI requires older 'requests' than one installed by default, so fix it manually:: + + # pip install --upgrade 'requests<1.2.3' + +or consider manual installing fresh OpenStack components from GitHub + +* Install Trove itself:: + + # python setup.py develop + +* Install Trove CLI:: + + # cd ~/python-troveclient + # python setup.py develop + # cd ~ + +* We'll need glance client as well:: + + # pip install python-glanceclient + +----------------- +Prepare OpenStack +----------------- +* Create a tenant 'trove' and user 'trove' with password 'trove' to be used with Trove. + +These values are not required to all be 'trove'; you can instead choose your own values for the name, +tenant, and password:: + + # keystone --os-username --os-password + --os-tenant-name --os-auth-url http://:35357/v2.0 + tenant-create --name trove + + # keystone --os-username --os-password + --os-tenant-name --os-auth-url http://:35357/v2.0 + user-create --name trove --pass trove --tenant trove + + # keystone --os-username --os-password + --os-tenant-name --os-auth-url http://:35357/v2.0 + user-role-add --name trove --tenant trove --role admin + +* Create service for trove:: + + # keystone --os-username --os-password + --os-tenant-name --os-auth-url http://:35357/v2.0 + service-create --name trove --type database + +* Create an endpoint that points to localhost. Pay attention to the use of quotes ('):: + + # keystone --os-username --os-password + --os-tenant-name --os-auth-url http://:35357/v2.0 + endpoint-create --service trove --region RegionOne + --publicurl 'http://localhost:8779/v1.0/$(tenant_id)s' + --adminurl 'http://localhost:8779/v1.0/$(tenant_id)s' + --internalurl 'http://localhost:8779/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 + +- trove-taskmanager.conf -- for trove-taskmanager + +- trove-guestagent.conf -- for trove-guestagent + +- .cloudinit -- cloudinit scripts for different service types. For now only 'mysql' and 'percona' are recognized as valid service types. NOTE: file names must exactly follow the pattern, e.g. 'mysql.cloudinit' + +Samples of the above are available in $TROVE/trove/etc/trove/ as *.conf.sample files. + +If a vanilla Ubuntu image used as a source image for Trove instances, then it is cloudinit script's responsibility +to install and run Trove guestagent in the instance. + +As an alternative one may consider creating a custom image with pre-installed and pre-configured Trove in it. + +------------- +Prepare image +------------- +* As the source image for trove instances, we will use a cloudinit-enabled vanilla Ubuntu image:: + + # wget http://cloud-images.ubuntu.com/precise/current/precise-server-cloudimg-amd64-disk1.img + +* Convert the downloaded image into uncompressed qcow2:: + + # qemu-img convert -O qcow2 precise-server-cloudimg-amd64-disk1.img precise.qcow2 + +* Upload the converted image into Glance:: + + # glance --os-username trove --os-password trove --os-tenant-name trove --os-auth-url http://:35357/v2.0 + image-create --name trove-image --public --container-format ovf --disk-format qcow2 --owner trove < precise.qcow2 + +---------------- +Prepare database +---------------- +* Initialize the database:: + + # trove-manage --config-file= db_wipe trove_test.sqlite mysql fake + +* Setup trove to use the uploaded image. Enter the following in a single line, note quotes (') and backquotes(`):: + + # trove-manage --config-file= image_update mysql + `nova --os-username trove --os-password trove --os-tenant-name trove + --os-auth-url http://:5000/v2.0 image-list | awk '/trove-image/ {print $2}'` + +--------- +Run Trove +--------- +* Run trove-api:: + + # trove-api --config-file= & + +* Run trove-taskmanager:: + + # trove-taskmanager --config-file= & + +* Try executing a trove command, like get-instance. You must first issue an "auth login" to obtain an API key.:: + + # trove-cli --username=trove --apikey=trove --tenant=trove --auth_url=http://:35357/v2.0/tokens auth login + + # trove-cli instance list + + +Troubleshooting +=============== + +------------- +No instance IPs in the output of 'trove-cli instance get' +------------- + +If Trove instance is created properly, is in the state ACTIVE, and is known for sure to be working, +but there are no IP addresses for the instance in the output of 'trove-cli instance get ', then make sure +the following lines are added to trove.conf:: + + add_addresses = True + network_label_regex = ^NETWORK_NAME$ + +where NETWORK_NAME should be replaced with real name of the nova network to which the instance is connected to. + +One possible way to find the nova 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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 35d06b2cf2..67b6d024bf 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -31,6 +31,8 @@ github in the `Trove Integration`_ Repository. For further details on how to install Trove using the integration scripts please refer to the :doc:`dev/install` page. +For further details on how to install Trove to work with existing +OpenStack environment please refer to the :doc:`dev/manual_install` page. Developer Resources ===================