Public | Automated Build

Last pushed: a year ago
Short Description
Short description is empty for this repo.
Full Description

<div align="center"><img src="./ursula.png" alt="Ursula"></div><hr />

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-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.


System Dependencies

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

Python Environment

We recommend using virtualenv or
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/
$ 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/ to your shell startup file, changing the path to
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/" >> .bash_profile

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

Install ursula and dependencies:

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,

$ pip install -U pip

Now you can continue cloning and installing ursula:

$ cd ~/development
$ git clone
$ 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.

Performing a deployment:

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

Host allinone
  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.


Contributions in the form of pull requests or issues are very welcome. We
ask that you review Code Guidelines.

More Docs

See the /doc directory of this repo.

Docker Pull Command
Source Repository