Published: April 07, 2019
Updated: April 10, 2019
Tags: Ansible, ARA
4 min read

Analyzing Ansible Playbooks Using ARA

Introduction to ARA

ARA [1] is an open source tool which is able to log your Ansible playbook runs, save them into a database and display them in an intuitive web interface. It integrates with Ansible using Ansible's callback plugin [2] in order to log your playbook run.

ARA can be deployed anywhere, and record Ansible playbook runs from multiple sources.

In this blog post we'll discuss in how to quickstart ARA and add it as part of your Ansible flow.

ARA as part of your stack

ARA is production tested and is a big part of OpenStack upstream CI initiative.

One of the downsides of Ansible is that all of your Ansible executions are only logged to output. There is no native way to keep a record of an Ansible run.

Ansible Tower [3] or its upstream project AWX [4] is a different product which leverages Ansible and enhances it with many additional capabilities (like recording executions).

Compared to Ansible Tower, ARA aims to solve a single issue, provide an interface to log and view Ansible playbook runs and doesn't require any additional complex deployments or maintenance.

Quickstart ARA

ARA is a python tool hosted on PyPI [5], it can be used as part of a [6] to minimize effect on system.

For a more in-depth guide on installing ARA, refer to its documentation [7].

Installing ARA

Install ARA via pip(make sure Ansible is installed):

pip install ara

Configure Ansible To Use Ara

ARA integrates with Ansible using callback plugins, which can be defined via configuration file(ansible.cfg [8]) or via environment variables.

Retrieve the needed environment variables:

# View environment variables
python -m  ara.setup.env
export ANSIBLE_CALLBACK_PLUGINS=/tmp/PY2/lib/python2.7/site-packages/ara/plugins/callbacks
export ANSIBLE_ACTION_PLUGINS=/tmp/PY2/lib/python2.7/site-packages/ara/plugins/actions
export PYTHONPATH=/tmp/PY2/lib/python2.7/site-packages:/tmp/PY/lib/python2.7/site-packages

# Source environment variables
eval $(python -m  ara.setup.env)

Once a callback plugin is used, ARA also provides additional Ansible modules ara_record [9] and ara_read [10] which enhance its capabilities.

Start The ARA Standalone Server

By default, ARA web interface will be started on 127.0.0.1 due to ARA_HOST envrionment variable's default
In order to change the bind, assign a new value to ARA_HOST

A web interface is a part of ARA, it can be launched using the ara-manage CLI:

ara-manage runserver &

Browse the server at http://127.0.0.1:9191/.

Run A Demo Playbook

Create the following demo demo-playbook.yml playbook:

---
- hosts: localhost
  tasks:
    - name: Print Message
      debug:
        msg: "This is a demo for ARA"

    - name: Log ARA Key
      ara_record:
        key: 'ara_test'
        value: 'Value'
      
    - name: Retrieve ARA Key
      ara_read:
        key: 'ara_test'

Execute playbook:

ansible-playbook demo-playbook.yml

Exploring ARA Records

After each Ansible playbook run, the record is saved into a database.

We'll focus on the web interface, CLI exploration is out of scope and can be viewed in ARA's documentation [11].

Web Interface

A web interface representing all the records is available:

ARA Web Interface

Viewing Playbook

You can view the playbook's content by clicking its name:

Playbook Content

Viewing Ansible Variables

All Ansible variables are logged and can be viewed by clicking on Parameters:
Ansible Variables

Viewing Ansible Hosts

All Ansible hosts that were used in the run can be viewed by clicking on Hosts:

Ansible Hosts

View Ansible Plays

All Ansible plays that were performed in the run can be viewed by clicking Plays:

Ansible Plays

View Ansible Playbook Files

All the files that are part of the playbook can be viewed by clicking Files:

Playbook Files

View Ansible Tasks

All tasks which were performed in the run can be viewed by clicking Tasks:

Playbook Tasks

The result of an individual task can be viewed by clicking an its entry in the Status column:

Task Result

View ARA Records

ARA records are special variables that can be registered and accessed during run. Those records are logged and displayed as part of an Ansible run record.

ARA Record

Summary

ARA is a great addition to your Ansible flow, it's easy to setup, scalable and decentrailized.

A small self-hosted ARA enhances troubleshooting and logging capabilities of Ansible.


  1. ARA Project Homepage ↩︎

  2. Ansible Documentation - Callback Plugins ↩︎

  3. Ansible Tower Homepage ↩︎

  4. AWX GitHub Project Page ↩︎

  5. PyPi ARA Project Page ↩︎

  6. Python Documentation - Virtual Environment ↩︎

  7. ARA Documentation - Installing ARA ↩︎

  8. ARA Documentation - Using ansible.cfg ↩︎

  9. ARA Documentation - Using the ara_record module ↩︎

  10. ARA Documentation - Using the ara_read module ↩︎

  11. ARA Documentation - Querying the database with the CLI ↩︎