Ansible playbooks for operating OpenStack - Powering Blue Box Cloud.
Python Shell Ruby Other
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin cleanup envs/test May 4, 2017
doc Merge pull request #2309 from mlangbehn/fix_openstack_capitalization Dec 9, 2016
envs Pin filebeat and fabric Jun 21, 2018
library increase nofile for cinder-volume/backup services Jun 30, 2017
playbooks change pinned versions to vars Jul 25, 2018
plugins refactor structure Apr 27, 2017
roles change pinned versions to vars Jul 25, 2018
test Revert "workaround for setuptool regression to unbreak ci." Jun 1, 2017
.gitattributes Add an Ursula metadata motd entry Nov 13, 2013
.gitignore cleanup envs/test May 4, 2017 0.9.3 release May 29, 2014
Dockerfile fix the dockerfile to actually build Sep 10, 2015
LICENSE Update license. Aug 2, 2013 added Mac OS X specific installation instructions to the top-level RE… Mar 30, 2018
Vagrantfile experimental CentOS support Jan 31, 2017
ansible.cfg ansible ssh should check host keys May 22, 2017 Adding the file necessary for the previous changes. Sep 4, 2015
branch-validation.yml fix branch validation for converged and dedicated stacks May 16, 2016 Add the start of a coding guideline file. Jul 6, 2016
requirements.txt added python-openstackclient to requirements.txt Dec 1, 2017
site.yml site.yml duplicate variable cleanup. May 17, 2017 Disable rally testing temporarily Jul 26, 2018
tox.ini specify vagrant vms via vagrant.yml Jun 22, 2015
upgrade-db-cluster.yml add do..until loops to all apt, pip modules (#2011) Jun 17, 2016
upgrade.yml remove pause from upgrade.yml Apr 11, 2018
ursula.png Add Ursula logo. Sep 29, 2015
vagrant.yml Make swift great again (#2033) Jun 23, 2016


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

Mac OS X specific notes non installing dependencies

If you have already installed python via brew, you'll need to remove it so you can force the devel headers to be installed AND usable by your libraries.

brew uninstall python

Next, install python and pip if not already installed.

brew install --devel --framework python
pip install -U pip

If you've already attempted or installed libxml2 and/or libxslt unlink and uninstall those first.

brew unlink libxml2
brew unlink libxslt
brew uninstall libxml2
brew uninstall libxslt

Now, install libxml2 and force static dependencies to enabled linking to the installed devel headers.

brew install --with-python libxml2
STATIC_DEPS=true sudo pip install -U lxml

Install libxslt and relink the newly installed libraries. As we already forced libxml2 to link the headers libxslt should do so as well without further steps.

brew install --with-python libxslt
brew link libxml2 --force
brew link libxslt --force

Install the remaining needed libraries.

brew install libffi
brew install openssl

Python Environment

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/
$ mkvirtualenv ursula

Note: If you're using OSX El Capitan (version 10.11) or newer, 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. For bash users on MaC OS X, use .bash_profile; if, like me, you've moved to Zsh, use .zshrc instead.

echo " " >> .bash_profile
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, run:

$ 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 ~/.ssh/config.

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.