Using Ansible

Ansible is a popular open source configuration management and application deployment tool. Ansible provides a set of core modules for interacting with OpenStack. This makes Ansible an ideal tool for providing both OpenStack orchestration and instance configuration, letting you use a single tool to setup the underlying infrastructure and configure instances. As such Ansible can replace other tools, such as Heat for OpenStack orchestration, and Puppet for instance configuration.

Comprehensive documentation of the Ansible OpenStack modules is available at

Install Ansible

A script is provided by Catalyst which installs the required Ansible and OpenStack libraries within a Python virtual environment. This script is part of the catalystcloud-ansible git repository. Clone this repository and run the install script in order to install Ansible.

$ git clone && CC_ANSIBLE_DIR="$(pwd)/catalystcloud-ansible" && echo $CC_ANSIBLE_DIR
$ cd catalystcloud-ansible
$ ./
Installing stable version of Ansible
Ansible installed successfully!

To activate run the following command:

source /home/yourname/src/catalystcloud-ansible/ansible-venv/bin/activate

$ source $CC_ANSIBLE_DIR/ansible-venv/bin/activate
$ ansible --version
  config file = /etc/ansible/ansible.cfg
  configured module search path = Default w/o overrides


Catalyst recommends customers use Ansible >= 2.0 and Shade >= 1.4 with the Catalyst Cloud.

OpenStack credentials

Before running the Ansible playbooks, ensure your OpenStack credentials have been set up. The easiest way to achieve this is by making use of environment variables. Use the standard variables provided by an OpenStack RC file as described in Source an OpenStack RC file. These variables are read by the Ansible os_auth module, and will provide Ansible with the credentials required to access the Catalyst Cloud APIs.


If credentials are not set up by sourcing an OpenStack RC file, a few mandatory authentication attributes will need to be included in the playbooks. See the “vars” section of the playbooks for details.

Once the Ansible installation includes the required OpenStack modules, and the OpenStack credentials have been set up, a first instance may be built. The first instance playbooks have been split up as follows:

  • The first playbook, create-network.yml creates the required network components.
  • The second playbook, launch-instance.yml launches the instance.

Run the create network playbook

These are the tasks the create-network.yml playbook will perform:

$ ansible-playbook --list-tasks create-network.yml

playbook: create-network.yml

 play #1 (localhost): Create a network in the Catalyst Cloud   TAGS: []
     Connect to the Catalyst Cloud TAGS: []
     Create a network  TAGS: []
     Create a subnet   TAGS: []
     Create a router   TAGS: []
     Create a security group   TAGS: []
     Create a security group rule for SSH access   TAGS: []
     Import an SSH keypair TAGS: []

In order for this playbook to work, the path to a valid SSH key must be provided. Edit create-network.yml and update the ssh_public_key variable, or override the variable when running the playbook as shown below:

$ ansible-playbook --extra-vars "ssh_public_key=$HOME/.ssh/" create-network.yml

PLAY [Deploy a cloud instance in OpenStack] ************************************

TASK [setup] *******************************************************************
ok: [localhost]

TASK [Connect to the Catalyst Cloud] *******************************************
ok: [localhost]

TASK [Create a network] ********************************************************
changed: [localhost]

TASK [Create a subnet] *********************************************************
changed: [localhost]

TASK [Create a router] *********************************************************
changed: [localhost]

TASK [Create a security group] *************************************************
changed: [localhost]

TASK [Create a security group rule for SSH access] *****************************
changed: [localhost]

TASK [Import an SSH keypair] ***************************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=8    changed=6    unreachable=0    failed=0


Pay careful attention to the console output. It provides lots of useful information.

Run the launch instance playbook

After the network has been setup successfully, run the launch-instance.yml playbook:

$ ansible-playbook launch-instance.yml

PLAY [Deploy a cloud instance in OpenStack] ************************************

TASK [setup] *******************************************************************
ok: [localhost]

TASK [Connect to the Catalyst Cloud] *******************************************
ok: [localhost]

TASK [Create a compute instance on the Catalyst Cloud] *************************
changed: [localhost]

TASK [Assign a floating IP] ****************************************************
changed: [localhost]

TASK [Output floating IP] ******************************************************
ok: [localhost] => {
    "floating_ip_info.floating_ip.floating_ip_address": ""

PLAY RECAP *********************************************************************
localhost                  : ok=4    changed=2    unreachable=0    failed=1

The new instance is accessible using SSH. Retrieve the instance’s IP address from the console output. It is echoed by the example Output floating IP task above as “”. Login using SSH (using the username appropriate to the build image):

$ ssh ubuntu@


Additional Ansible playbooks may now be used to configure this instance further, as required.

Resource cleanup with an Ansible playbook

This playbook will remove all resources created by the previous playbooks.

It has been included in the catalystcloud-ansible git repository referenced earlier, but may also be downloaded as follows:

$ wget -q

Run the playbook to remove all resources created previously:

$ ansible-playbook remove-stack.yml --extra-vars "floating_ip=<ip-address>"

Replace <ip-address> with the floating-ip assigned by the launch-instance.yml playbook.


This cleanup playbook assumes that all resources have been created using the default names defined in the original playbooks. If the original names have been changed, it will be necessary to edit the cleanup playbook to reflect these changes.