MultiOS

MultiOS is little integration tool designed to work with multiple OpenStack installations. The intention is to support automatic load balancing of arbitrary work loads between multiple independent OpenStack installations without modifications to OpenStack.

The tool was created as a part of SIGMONA research project at Aalto University School of Science, Department of Computer Science, Communication Networks research group.

Getting started

Create new Python 2.7 virtual environment for your project (Python 3.x is not supported). You do not want to mess with your system-wide python installation.

There are various ways for doing this, and the method does not really matter. My personal favourite is virtualenvwrapper. Other popular choice is bare virtualenv.

If you chose to use virtualenvwrapper, install it globally using sudo pip install virtualenvwrapper and add the following to your shell startup script (often ~/.bashrc)
```
export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devel
export VIRTUALENVWRAPPER_SCRIPT=/usr/local/bin/virtualenvwrapper.sh
source /usr/local/bin/virtualenvwrapper_lazy.sh
```
Then create new virtualenv: mkvirtualenv multios.
Ensure that you are using your new virtual env (run which python). Remember to do this step every time you work on this project!

If you are using virtualenvwrpper you can activate the existing virtualenv using command workon multios.
Install required libraries: sudo apt-get install libxml2-dev libxslt1-dev python-dev
Install required python libraries and development tools: pip install -r requirements.txt -r dev-requirements.txt.
Copy multios.cfg.sample to multios.cfg and edit it to contain your own set of OpenStack credentials. Also ensure that you are able to reach given OpenStack installation from your development machine.
Run the development server with command multios server. If the project can't load config file, then do export MULTIOS_CONFIG=/absolute/path/to/multios.cfg and run the server again.
Test different end-points either with multios cli or curl.

Running in 'production' mode

Install gunicorn with gevent support: pip install gunicorn greenlet gevent Note: You need at least python-dev package.
Run command: gunicorn -k gevent -b 0.0.0.0:5000 --keep-alive 6000 multios .server:app

Running tests

The simplest and fastest way to run all the tests in this project is to run python -m unittest discover multios/tests.

For more fine-grained control of tests to be executed consult the documentation of Python Unit testing framework.

Package management

For obvious reasons the package versions in this project are pinned. Top-level requirements and development requirements are declared in requirements.txt.in and dev-requirements.txt.in respectively and converted to "normal" requirements.txt and dev-requirements.txt using pip-tools.

To update requirements run pip-review --interactive to update packages. Verify that everything works as expected with new package versions and then run pip-dump to generate new *-requirements.txt files. Remember to commit the changed files to git.

To add new packages to the project add the package name to requirements.txt.in file and the pinned version to requirements.txt and then use pip-review and pip-dump in similar way as when updating packages.

Remarks about the code

The MultiOSCLI class in file cli.py uses Python docopt module to parse command line arguments. Because of this it is required that the docstring in the beginning of the class contains all the possible command line options, commands and arguments in the standard POSIX notation. The argument parser is constructed from the usage string automatically.

License

TODO: decide license

kimmoahokas / multios