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).
ceph-osd roles were originally taken from
ceph/ceph-ansible, but have since been
ceph/ceph-ansible is released under the Apache License.
The following system packages ( or their equivalents for your OS ) are
required to run
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
If you're new to python, the following will install
virtualenvwrapper and set
virtualenv for ursula:
$ pip install virtualenvwrapper $ source /usr/local/bin/virtualenvwrapper.sh $ 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/virtualenvwrapper.sh to your shell startup file, changing the path to virtualenvwrapper.sh
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/virtualenvwrapper.sh" >> .bash_profile
From now on to work with ursula you can run
$ workon ursula to
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 firstname.lastname@example.org: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
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.
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
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
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
host_vars, and a
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
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
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
tells Ansible what roles to apply to which servers.
Finally, we have the
group_vars/all.yml file. This contains values that will
defaults.yml in the parent directory. For example, we're
disabling Percona replication by setting
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 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.
Contributions in the form of pull requests or issues are very welcome. We ask that you review Code Guidelines.
See the /doc directory of this repo.