Ursula provides a series of Ansible playbooks for installing, managing, and maintaining OpenStack powered clouds.

Ursula was originally created by a team at Blue Box and is released under the MIT License (MIT).

The ceph-common, ceph-monitor, and ceph-osd roles were originally taken from ceph/ceph-ansible, but have since been modified. ceph/ceph-ansible is released under the Apache License.

The following system packages ( or their equivalents for your OS ) are required to run ursula:

• python-pip
• python-dev
• libxml2-dev
• libxslt-dev
• libffi-dev
• libssl-dev

We recommend using virtualenv or virtualenvwrapper to isolate your Python environment.

If you're new to python, the following will install virtualenvwrapper and set up a virtualenv for ursula:

$ pip install virtualenvwrapper
$ source /usr/local/bin/virtualenvwrapper.sh
$ mkvirtualenv ursula

Note: If you're using OSX El Capitan, you need to use pip install --ignore-installed six virtualenvwrapper to get pip to not attempt to uninstall the existing version of six which the system will not allow.

You will want to add source /usr/local/bin/virtualenvwrapper.sh to your shell startup file, changing the path to virtualenvwrapper.sh depending on where it was installed by pip.

echo " " >> .bash_profile (for OSX; .bashrc for various linux flavors)
echo "#sourcing statement for virtualenvwrapper" >> .bash_profile
echo "source /usr/local/bin/virtualenvwrapper.sh" >> .bash_profile

From now on to work with ursula you can run $ workon ursula to enter the virtualenv

Now that your python environment is ready, you can clone ursula and install its prerequisites.

You'll need a modern version of pip, so if you're using a version <7, run:

$ pip install -U pip

Now you can continue cloning and installing ursula:

$ cd ~/development
$ git clone git@github.com:blueboxgroup/ursula.git
$ cd ursula
$ pip install -r requirements.txt

These steps will have installed ursula-cli, the various openstack clients, and our patched fork of Ansible.

Ursula was designed by Blue Box to manage a large number of OpenStack deployments. In order to do this efficiently we've made some changes to how ansible works. As part of these changes we have a wrapper tool called ursula-cli which was installed during the pip install -r requirements.txt above.

Make sure ursula-cli is installed in your environment:

ursula -h
usage: ursula [-h] [--ursula-forward] [--ursula-test] [--ursula-debug]
              environment playbook

A CLI wrapper for ansible
...
...

There are two mandatory fields required by ursula-cli. The first is environment which will require some further explanation. The second is playbook which will almost always be site.yml.

One of the modifications that we have made to Ansible is the ability to have a seperate path that includes all of the configuration options for your OpenStack deployment(s). An example of this can be found in /envs/example

If you look in the /envs/example path, you'll see a defaults.yml file and a series of directories each representing a different OpenStack deployment.

We then utilize the standard Ansible features by having group_vars, host_vars, and a hosts file.

There are also some vagrant.yml files scattered around. These are helper files to make using Vagrant even easier with ursula to test your environments in VMs.

The simplest example deployment is allinone which is a single server deployment that acts as both a controller and a compute node.

Whether or not you're using Vagrant if you look in the envs/example/allinone/vagrant.yml file it will give you some hints on what your server should look like. If you do not wish to use Vagrant then you should install Ubuntu 12.04 on a server and configure its networking as described in the vagrant.yml file.

Next, look in the hosts file. It's very simple in this case due to the fact we have only a single server. This file combined with the site.yml playbook tells Ansible what roles to apply to which servers.

Finally, we have the group_vars/all.yml file. This contains values that will override the defaults.yml in the parent directory. For example, we're disabling Percona replication by setting percona.replication: False.

For the sake of simplicity, I recommend using Vagrant rather than Manual for your first install.

If you want to install manually, do not use envs/examples/* without modifications as it contains several circuit breakers such as invalid certificates and your installs will fail.

If you're not running Vagrant and have installed ubuntu onto a server and configured the networking then we need to tell our system how to talk to this new server. The easiest way is via an entry in your ssh config file in ~/.ssh/config.

Host allinone
  HostName 172.16.0.100
  User ubuntu
  IdentityFile ~/.ssh/private_key

$ ursula envs/example/allinone site.yml

If you're running Vagrant, we have a wrapper script that stands up the appropriate vagrant environment, saves it as an ssh config, and then calls ursula for you.

To deploy your allinone environment via Vagrant simply run:

$ ursula --provisioner=vagrant envs/example/allinone site.yml

Note: The default OS for ursula is Ubuntu Trusty. If you want Precise, set the env var URSULA_BOX_NAME to the name of your precise vagrant box before running vagrant.

See the /doc directory of this repo.