Welcome to the ARA documentation!

Table of Contents

Getting started

Requirements

• Any recent Linux distribution or Mac OS with python >=3.5 available
• The ara Ansible plugins must be installed for the same python interpreter as Ansible itself

Note

For RHEL 7 and CentOS 7 it is recommended to run the API server in a container due to missing or outdated dependencies. See this issue for more information.

Recording playbooks without an API server

The default API client, offline, requires API server dependencies to be installed but does not need the API server to be running in order to query or send data.

With defaults and using a local sqlite database:

# Install Ansible and ARA (with API server dependencies) for the current user
python3 -m pip install --user ansible "ara[server]"

# Configure Ansible to use the ARA callback plugin
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"

# Run an Ansible playbook
ansible-playbook playbook.yaml

# Use the CLI to see recorded playbooks
ara playbook list

# Start the built-in development server to browse recorded results
ara-manage runserver

Recording playbooks with an API server

When running Ansible from multiple servers or locations, data can be aggregated by running the API server as a service and configuring the ARA Ansible callback plugin to use the http API client with the API server endpoint.

The API server is a relatively simple django web application written in python that can run with WSGI application servers such as gunicorn, uwsgi or mod_wsgi.

Alternatively, the API server can also run from a container image such as the one available on DockerHub:

# Create a directory for a volume to store settings and a sqlite database
mkdir -p ~/.ara/server

# Start an API server with podman from the image on DockerHub:
podman run --name api-server --detach --tty \
  --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \
  docker.io/recordsansible/ara-api:latest

# or with docker:
docker run --name api-server --detach --tty \
  --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \
  docker.io/recordsansible/ara-api:latest

Once the server is running, Ansible playbook results can be sent to it by configuring the ARA callback plugin:

# Install Ansible and ARA (without API server dependencies) for the current user
python3 -m pip install --user ansible ara

# Configure Ansible to use the ARA callback plugin
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"

# Set up the ARA callback to know where the API server is located
export ARA_API_CLIENT="http"
export ARA_API_SERVER="http://127.0.0.1:8000"

# Run an Ansible playbook
ansible-playbook playbook.yaml

# Use the CLI to see recorded playbooks
ara playbook list

Data will be available on the API server in real time as the playbook progresses and completes.

Read more about how container images are built and how to run them here.

Installing from source

ara can be installed from source in order to preview and test unreleased features and improvements:

# Without the API server dependencies
pip install --user git+https://github.com/ansible-community/ara

# With the API server dependencies
# (Extras suffixes don't work when supplying the direct git URL)
git clone https://github.com/ansible-community/ara /tmp/ara-src
pip install --user "/tmp/ara-src[server]"

Installing from distribution packages

ara is fully packaged for Fedora, OpenSUSE as well as Debian.

There is also a package without the API server available on RHEL 8/CentOS 8 EPEL. This package contains the Ansible plugins as well as the API clients which are sufficient to query or send data to a remote API server.

Installing with Ansible roles

A collection of Ansible roles for deploying a production-ready ara API server is available on Ansible Galaxy.

For more information as well as documentation, see the collection GitHub repository: https://github.com/ansible-community/ara-collection/

Ansible configuration to use ara

In order to be able to use ara Ansible plugins, Ansible must first know where they have been installed.

Since this location will be different depending on the operating system, the version of python or how ara has been installed, there are convenient python helper modules that provide the right paths:

$ python3 -m ara.setup.path
/usr/lib/python3.7/site-packages/ara

$ python3 -m ara.setup.plugins
/usr/lib/python3.7/site-packages/ara/plugins

$ python3 -m ara.setup.action_plugins
/usr/lib/python3.7/site-packages/ara/plugins/action
$ export ANSIBLE_ACTION_PLUGINS=$(python3 -m ara.setup.action_plugins)

$ python3 -m ara.setup.callback_plugins
/usr/lib/python3.7/site-packages/ara/plugins/callback
$ export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins)

$ python3 -m ara.setup.lookup_plugins
/usr/lib/python3.7/site-packages/ara/plugins/lookup
$ export ANSIBLE_LOOKUP_PLUGINS=$(python3 -m ara.setup.lookup_plugins)

# Note: This doesn't export anything, it only prints the commands.
# To export directly from the command, use:
#     source <(python3 -m ara.setup.env)
$ python3 -m ara.setup.env
export ANSIBLE_CALLBACK_PLUGINS=/usr/lib/python3.7/site-packages/ara/plugins/callback
export ANSIBLE_ACTION_PLUGINS=/usr/lib/python3.7/site-packages/ara/plugins/action
export ANSIBLE_LOOKUP_PLUGINS=/usr/lib/python3.7/site-packages/ara/plugins/lookup

$ python3 -m ara.setup.ansible
[defaults]
callback_plugins=/usr/lib/python3.7/site-packages/ara/plugins/callback
action_plugins=/usr/lib/python3.7/site-packages/ara/plugins/action
lookup_plugins=/usr/lib/python3.7/site-packages/ara/plugins/lookup

These helpers are also available directly in python:

>>> from ara.setup import callback_plugins
>>> print(callback_plugins)
/usr/lib/python3.7/site-packages/ara/plugins/callback

>>> from ara.setup import action_plugins
>>> print(action_plugins)
/usr/lib/python3.7/site-packages/ara/plugins/action

>>> from ara.setup import lookup_plugins
>>> print(lookup_plugins)
/usr/lib/python3.7/site-packages/ara/plugins/lookup

Ansible plugins and use cases

ara_default callback: recording playbooks from Ansible

The ara_default Ansible callback plugin can be enabled by configuring Ansible with the ANSIBLE_CALLBACK_PLUGINS environment variable or the callback_plugins setting in an ansible.cfg file.

The callback is the component that recovers data during playbook execution and sends it to the API.

By default, the callback is configured up to use the local API server with the offline API client but it can be set up to use a remote API server, authenticate with credentials and more:

callback: ara
callback_type: notification
requirements:
  - ara
short_description: Sends playbook execution data to the ARA API internally or over HTTP
description:
  - Sends playbook execution data to the ARA API internally or over HTTP
options:
  api_client:
    description: The client to use for communicating with the API
    default: offline
    env:
      - name: ARA_API_CLIENT
    ini:
      - section: ara
        key: api_client
    choices: ['offline', 'http']
  api_server:
    description: When using the HTTP client, the base URL to the ARA API server
    default: http://127.0.0.1:8000
    env:
      - name: ARA_API_SERVER
    ini:
      - section: ara
        key: api_server
  api_username:
    description: If authentication is required, the username to authenticate with
    default: null
    env:
      - name: ARA_API_USERNAME
    ini:
      - section: ara
        key: api_username
  api_password:
    description: If authentication is required, the password to authenticate with
    default: null
    env:
      - name: ARA_API_PASSWORD
    ini:
      - section: ara
        key: api_password
  api_cert:
    description: If a client certificate is required, the path to the certificate to use.
    default: null
    env:
      - name: ARA_API_CERT
    ini:
      - section: ara
        key: api_cert
  api_key:
    description: If a client certificate is required, the path to the private key to use.
    default: null
    env:
      - name: ARA_API_KEY
    ini:
      - section: ara
        key: api_key
  api_ca:
    description: The path to a CA bundle.
    default: null
    env:
      - name: ARA_API_CA
    ini:
      - section: ara
        key: api_ca
  api_insecure:
    description: Can be enabled to ignore SSL certification of the API server
    type: bool
    default: false
    env:
      - name: ARA_API_INSECURE
    ini:
      - section: ara
        key: api_insecure
  api_timeout:
    description: Timeout, in seconds, before giving up on HTTP requests
    type: integer
    default: 30
    env:
      - name: ARA_API_TIMEOUT
    ini:
      - section: ara
        key: api_timeout
  argument_labels:
    description: |
        A list of CLI arguments that, if set, will be automatically applied to playbooks as labels.
        Note that CLI arguments are not always named the same as how they are represented by Ansible.
        For example, --limit is "subset", --user is "remote_user" but --check is "check".
    type: list
    default:
      - remote_user
      - check
      - tags
      - skip_tags
      - subset
    env:
      - name: ARA_ARGUMENT_LABELS
    ini:
      - section: ara
        key: argument_labels
  callback_threads:
    description:
      - The number of threads to use in API client thread pools (maximum 4)
      - When set to 0, no threading will be used (default) which is appropriate for usage with sqlite
      - Using threads is recommended when the server is using MySQL or PostgreSQL
    type: integer
    default: 0
    env:
      - name: ARA_CALLBACK_THREADS
    ini:
      - section: ara
        key: callback_threads
  default_labels:
    description: A list of default labels that will be applied to playbooks
    type: list
    default: []
    env:
      - name: ARA_DEFAULT_LABELS
    ini:
      - section: ara
        key: default_labels
  ignored_facts:
    description: List of host facts that will not be saved by ARA
    type: list
    default: ["ansible_env"]
    env:
      - name: ARA_IGNORED_FACTS
    ini:
      - section: ara
        key: ignored_facts
  ignored_arguments:
    description: List of Ansible arguments that will not be saved by ARA
    type: list
    default: ["extra_vars"]
    env:
      - name: ARA_IGNORED_ARGUMENTS
    ini:
      - section: ara
        key: ignored_arguments
  ignored_files:
    description:
      - List of file path patterns that will not be saved by ARA
      - Note that the default pattern ('.ansible/tmp') gets dynamically set to the value of ANSIBLE_LOCAL_TEMP
      - The configuration for ANSIBLE_LOCAL_TEMP is typically ~/.ansible/tmp unless it is changed.
    type: list
    default: [".ansible/tmp"]
    env:
      - name: ARA_IGNORED_FILES
    ini:
      - section: ara
        key: ignored_files
  localhost_as_hostname:
    description:
        - Associates results to the hostname (or fqdn) instead of localhost when the inventory name is localhost
        - Defaults to false for backwards compatibility, set to true to enable
        - This can be useful when targetting localhost, using ansible-pull or ansible-playbook -i 'localhost,'
        - This helps differentiating results between hosts, otherwise everything would be recorded under localhost.
    type: boolean
    default: false
    env:
      - name: ARA_LOCALHOST_AS_HOSTNAME
    ini:
      - section: ara
        key: localhost_as_hostname
  localhost_as_hostname_format:
    description:
      - The format to use when recording the hostname for localhost
      - This is used when recording the controller hostname or when ARA_LOCALHOST_TO_HOSTNAME is true
      - There are different formats to choose from based on the full (or short) configured hostname and fqdn
      - Defaults to 'fqdn' (i.e, server.example.org) but can be set to 'fqdn_short' (server)
      - Other options include 'hostname' and 'hostname_short' which may be suitable depending on server configuration
    default: fqdn
    env:
      - name: ARA_LOCALHOST_AS_HOSTNAME_FORMAT
    ini:
      - section: ara
        key: localhost_as_hostname_format
    choices: ['fqdn', 'fqdn_short', 'hostname', 'hostname_short']
  record_controller:
    description:
      - Whether ara should record the controller hostname on which the playbook ran
      - Defaults to true but may be optionally set to false for privacy or other use cases
    type: boolean
    default: true
    env:
      - name: ARA_RECORD_CONTROLLER
    ini:
      - section: ara
        key: record_controller
  record_controller_name:
    description:
      - The name to use when recording the controller hostname.
      - Defaults to the system hostname.
    type: string
    env:
      - name: ARA_RECORD_CONTROLLER_NAME
    ini:
      - section: ara
        key: record_controller_name
  record_user:
    description:
      - Whether ara should record the user that ran a playbook
      - Defaults to true but may be optionally set to false for privacy or other use cases
    type: boolean
    default: true
    env:
      - name: ARA_RECORD_USER
    ini:
      - section: ara
        key: record_user
  record_user_name:
    description:
      - The name to use when recording the user that ran a playbook.
      - Defaults to the OS user which ran the playbook.
    type: string
    env:
      - name: ARA_RECORD_USER_NAME
    ini:
      - section: ara
        key: record_user_name
  record_task_content:
    description:
      - Whether ara should record the content of a task
      - Defaults to true, set to false for privacy or other use cases
    type: boolean
    default: true
    env:
      - name: ARA_RECORD_TASK_CONTENT
    ini:
      - section: ara
        key: record_task_content

For example, a customized callback plugin configuration might look like this in an ansible.cfg file:

[ara]
api_client = http
api_server = https://demo.recordsansible.org
api_username = user
api_password = password
api_timeout = 15
callback_threads = 4
argument_labels = check,tags,subset
default_labels = prod,deploy
ignored_facts = ansible_env,ansible_all_ipv4_addresses
ignored_files = .ansible/tmp,vault.yaml,vault.yml
ignored_arguments = extra_vars,vault_password_files
localhost_as_hostname = true
localhost_as_hostname_format = fqdn

or as environment variables:

export ARA_API_CLIENT=http
export ARA_API_SERVER="https://demo.recordsansible.org"
export ARA_API_USERNAME=user
export ARA_API_PASSWORD=password
export ARA_API_TIMEOUT=15
export ARA_CALLBACK_THREADS=4
export ARA_ARGUMENT_LABELS=check,tags,subset
export ARA_DEFAULT_LABELS=prod,deploy
export ARA_IGNORED_FACTS=ansible_env,ansible_all_ipv4_addresses
export ARA_IGNORED_FILES=.ansible/tmp,vault.yaml,vault.yml
export ARA_IGNORED_ARGUMENTS=extra_vars,vault_password_files
export ARA_LOCALHOST_AS_HOSTNAME=true
export ARA_LOCALHOST_AS_HOSTNAME_FORMAT=fqdn

Recording ad-hoc commands

It is possible to record ad-hoc commands in addition to playbooks since ara 1.4.1 and Ansible 2.9.7.

Ad-hoc command recording can be enabled by setting to true the ANSIBLE_LOAD_CALLBACK_PLUGINS environment variable or bin_ansible_callbacks in an ansible.cfg file.

Playbook names and labels

Playbooks recorded by the ara callback can be given names or labels in order to make them easier to find and identify later.

They are set as ordinary Ansible variables and are evaluated at the beginning of each play. They can be provided directly in playbook files:

- name: Deploy prod environment
  hosts: prod
  vars:
    ara_playbook_name: deploy prod
    ara_playbook_labels:
      - deploy
      - prod
  roles:
    - application

or as extra-vars:

ansible-playbook -i hosts playbook.yaml \
    -e ara_playbook_name="deploy prod" \
    -e ara_playbook_labels=deploy,prod

Once set, they can be searched for in the UI, the API:

• /api/v1/playbooks?name=prod
• /api/v1/playbooks?label=prod

or the CLI:

• ara playbook list --name prod
• ara playbook list --label prod

Default labels

Default labels will be applied to every playbook recorded by the callback plugin and can be specified with an ansible.cfg file:

[defaults]
# ...
[ara]
default_labels = deploy,prod

or through the environment variable ARA_DEFAULT_LABELS:

export ARA_DEFAULT_LABELS=deploy,prod

CLI argument labels

CLI argument labels will automatically apply labels to playbooks when specified CLI arguments are used.

For example, if --check is used and set up as an argument label, the playbook will be tagged with check:True if --check was used or check:False if it wasn’t.

Note

Some CLI arguments are not always named the same as how they are represented by Ansible. For example, --limit is “subset”, --user is “remote_user” but --check is “check”.

Argument labels can be configured through an ansible.cfg file:

[defaults]
# ...
[ara]
argument_labels = check,subset,tags

or through the environment variable ARA_ARGUMENT_LABELS:

export ARA_ARGUMENT_LABELS=check,subset,tags

ara_api: free-form API queries

The ara_api Ansible lookup plugin can be enabled by configuring Ansible with the ANSIBLE_LOOKUP_PLUGINS environment variable or the lookup_plugins setting in an ansible.cfg file.

It can be used to do free-form queries to the ara API while the playbook is running:

- name: Test playbook
  hosts: localhost
  tasks:
    - name: Get failed results
      set_fact:
        failed: "{{ lookup('ara_api', '/api/v1/results?status=failed') }}"

    - name: Print task data from failed results
      vars:
        task_id: "{{ item.task | string }}"
        task: "{{ lookup('ara_api', '/api/v1/tasks/' + task_id ) }}"
        host_id: "{{ item.host | string }}"
        host: "{{ lookup('ara_api', '/api/v1/hosts/' + host_id) }}"
      debug:
        msg: "{{ host.name }} failed | {{ task.name }} ({{ task.path }}:{{ task.lineno }})"
      loop: "{{ failed.results }}"

ara_playbook: get the running playbook or one in specific

The ara_playbook Ansible action plugin can be enabled by configuring Ansible with the ANSIBLE_ACTION_PLUGINS environment variable or the action_plugins setting in an ansible.cfg file.

Without any arguments, it can be used to return data about the playbook from which it is running:

- name: Test playbook
  hosts: localhost
  tasks:
    - name: Get the currently running playbook
      ara_playbook:
      register: query

    - name: Retrieve playbook id
      set_fact:
        playbook_id: "{{ query.playbook.id | string }}"

    # With the playbook id we can create a link to the playbook report
    - name: Recover base url from ara
      set_fact:
        api_base_url: "{{ lookup('ara_api', '/api/') }}"

    - name: Print link to playbook report
      vars:
        ui_base_url: "{{ api_base_url.api[0] | regex_replace('/api/v1/', '') }}"
      debug:
        msg: "{{ ui_base_url }}/playbooks/{{ playbook_id }}.html"

With an argument, it can retrieve data from a specific playbook:

- name: Test playbook
  hosts: localhost
  tasks:
    - name: Get a specific playbook
      ara_playbook:
        playbook: 9001
      register: query

    - name: Print data about the playbook
      debug:
        msg: "Playbook {{ query.playbook.status }} in {{ query.playbook.duration }}"

ara_record: arbitrary key/values in playbook reports

The ara_record Ansible action plugin can be enabled by configuring Ansible with the ANSIBLE_ACTION_PLUGINS environment variable or the action_plugins setting in an ansible.cfg file.

It can be used to attach data or metadata to playbook reports so they are available later:

- name: Test playbook
  hosts: localhost
  tasks:
    - name: Get git version of playbooks
      command: git rev-parse HEAD
      register: git_version

    - name: Record git version
      ara_record:
        key: "git_version"
        value: "{{ git_version.stdout }}"
      register: version

    - name: Print recorded data
      debug:
        msg: "{{ version.playbook_id }} - {{ version.key }}: {{ version.value }}"

It is possible to declare a type which can be used to render the data appropriately later:

- name: Record different things
  ara_record:
    key: "{{ item.key }}"
    value: "{{ item.value }}"
    type: "{{ item.type }}"
  loop:
    - { key: "log", value: "error", type: "text" }
    - { key: "website", value: "http://domain.tld", type: "url" }
    - { key: "data", value: '{ "key": "value" }', type: "json" }
    - { key: "somelist", value: ['one', 'two'], type: "list" }
    - { key: "somedict", value: {'key': 'value' }, type: "dict" }

Adding records to playbooks after their completion

ara_record can attach data to a specific playbook by providing a playbook id. This can be useful for attaching data that might only be available once a playbook has been completed:

- name: Attach data to a specific playbook
  ara_record:
    playbook: 9001
    key: logs
    value: "{{ lookup('file', '/var/log/ansible.log') }}"
    type: text

Or as an ad-hoc command:

ansible localhost -m ara_record \
        -a "playbook=14 key=logs value={{ lookup('file', '/var/log/ansible.log') }}"

ARA API server configuration

The API server ships with sane defaults, supports the notion of different environments (such as dev, staging, prod) and allows you to customize the configuration with files, environment variables or a combination of both.

The API is a Django application that leverages django-rest-framework. Both Django and django-rest-framework have extensive configuration options which are not necessarily exposed or made customizable by ARA for the sake of simplicity.

Overview

This is a brief overview of the different configuration options for the API server. For more details, click on the configuration parameters.

Environment Variable	Default	Usage
ARA_ALLOWED_HOSTS	["127.0.0.1", "localhost", "::1"]	Django’s ALLOWED_HOSTS setting
ARA_BASE_DIR	~/.ara/server	Default directory for storing data and configuration
ARA_BASE_PATH	/	Default URL-path under which ARA resides
ARA_CORS_ORIGIN_WHITELIST	["http://127.0.0.1:8000", "http://localhost:3000"]	django-cors-headers’s CORS_ORIGIN_WHITELIST setting
ARA_CORS_ORIGIN_REGEX_WHITELIST	[]	django-cors-headers’s CORS_ORIGIN_REGEX_WHITELIST setting
ARA_CSRF_TRUSTED_ORIGINS	[]	Django’s CSRF_TRUSTED_ORIGINS setting
ARA_DATABASE_CONN_MAX_AGE	0	Django’s CONN_MAX_AGE database setting
ARA_DATABASE_ENGINE	django.db.backends.sqlite3	Django’s ENGINE database setting
ARA_DATABASE_HOST	None	Django’s HOST database setting
ARA_DATABASE_NAME	~/.ara/server/ansible.sqlite	Django’s NAME database setting
ARA_DATABASE_PASSWORD	None	Django’s PASSWORD database setting
ARA_DATABASE_PORT	None	Django’s PORT database setting
ARA_DATABASE_USER	None	Django’s USER database setting
ARA_DATABASE_OPTIONS	{}	Django’s OPTIONS database setting
ARA_DEBUG	False	Django’s DEBUG setting
ARA_DISTRIBUTED_SQLITE	False	Whether to enable distributed sqlite backend
ARA_DISTRIBUTED_SQLITE_PREFIX	ara-report	Prefix to delegate to the distributed sqlite backend
ARA_DISTRIBUTED_SQLITE_ROOT	/var/www/logs	Root under which sqlite databases are expected
ARA_ENV	default	Environment to load configuration for
ARA_EXTERNAL_AUTH	False	Whether or not to enable external authentication
ARA_LOGGING	See ARA_LOGGING	Logging configuration
ARA_LOG_LEVEL	INFO	Log level of the different components
ARA_PAGE_SIZE	100	Amount of results returned per page by the API
ARA_READ_LOGIN_REQUIRED	False	Whether authentication is required for reading data
ARA_SECRET_KEY	Randomized token, see ARA_SECRET_KEY	Django’s SECRET_KEY setting
ARA_SETTINGS	~/.ara/server/settings.yaml	Path to an API server configuration file
ARA_TIME_ZONE	Local system timezone	Time zone used when storing and returning results
ARA_WRITE_LOGIN_REQUIRED	False	Whether authentication is required for writing data

Configuration variables

ARA_ALLOWED_HOSTS

• Environment variable: ARA_ALLOWED_HOSTS

• Configuration file variable: ALLOWED_HOSTS

• Type: list

• Provided by: Django’s ALLOWED_HOSTS

• Default: ["127.0.0.1", "localhost", "::1"]

• Examples:

  • export ARA_ALLOWED_HOSTS="['api.ara.example.org', 'web.ara.example.org']"

  • In a YAML configuration file:

    dev:
      ALLOWED_HOSTS:
        - 127.0.0.1
        - localhost
    production:
      ALLOWED_HOSTS:
        - api.ara.example.org
        - web.ara.example.org
    

A list of strings representing the host/domain names that this Django site can serve.

If you are planning on hosting an instance of the API server somewhere, you’ll need to add your domain name to this list.

ARA_BASE_DIR

• Environment variable: ARA_BASE_DIR
• Configuration file variable: BASE_DIR
• Type: string
• Default: ~/.ara/server

The directory where data will be stored by default.

Changing this location influences the default root directory for the ARA_DATABASE_NAME and ARA_SETTINGS parameters.

This is also used to determine the location where the default configuration file, settings.yaml, will be generated by the API server.

ARA_BASE_PATH

• Environment variable: ARA_BASE_PATH
• Configuration file variable: BASE_PATH
• Type: string
• Default: /

The URL path under which ARA should get deployed.

By default this is empty, meaning that ARA will listen directly on /. This setting can be used in conjuntion with a reverse proxy to deploy ARA on sub paths without having the reverse proxy to rewrite all URLs in the generated HTML.

ARA_CORS_ORIGIN_WHITELIST

• Environment variable: ARA_CORS_ORIGIN_WHITELIST

• Configuration file variable: CORS_ORIGIN_WHITELIST

• Provided by: django-cors-headers

• Type: list

• Default: ["127.0.0.1:8000", "localhost:3000"]

• Examples:

  • export ARA_CORS_ORIGIN_WHITELIST="['https://api.ara.example.org', 'https://web.ara.example.org']"

  • In a YAML configuration file:

    dev:
      CORS_ORIGIN_WHITELIST:
        - http://127.0.0.1:8000
        - http://localhost:3000
    production:
      CORS_ORIGIN_WHITELIST:
        - https://api.ara.example.org
        - https://web.ara.example.org
    

Hosts in the whitelist for Cross-Origin Resource Sharing.

This setting is typically used in order to allow the API and a web client (such as ara-web) to talk to each other.

ARA_CORS_ORIGIN_REGEX_WHITELIST

• Environment variable: ARA_CORS_ORIGIN_REGEX_WHITELIST

• Configuration file variable: CORS_ORIGIN_REGEX_WHITELIST

• Provided by: django-cors-headers

• Type: list

• Default: []

• Examples:

  • export ARA_CORS_ORIGIN_REGEX_WHITELIST="['^https://pr-\d+.ara-web.example.org$']"

  • In a YAML configuration file:

    dev:
      CORS_ORIGIN_REGEX_WHITELIST:
        - '^https://pr-\d+.ara-web.example.org$'
    production:
      CORS_ORIGIN_REGEX_WHITELIST:
        - '^https://web.ara.example.(org|net)$'
    

Hosts in the whitelist for Cross-Origin Resource Sharing.

This setting is typically used in order to allow the API and a web client (such as ara-web) to talk to each other.

Especially useful for situations like CI where the deployment domain may not be known in advance, this setting is applied in addition to the individual domains in the CORS_ORIGIN_WHITELIST.

ARA_CSRF_TRUSTED_ORIGINS

• Environment variable: ARA_CSRF_TRUSTED_ORIGINS

• Configuration file variable: CSRF_TRUSTED_ORIGINS

• Provided by: Django’s CSRF_TRUSTED_ORIGINS_ setting

• Type: list

• Default: []

• Examples:

  • export CSRF_TRUSTED_ORIGINS="['api.ara.example.org', 'web.ara.example.org']"

  • In a YAML configuration file:

    dev:
      CSRF_TRUSTED_ORIGINS:
        - 127.0.0.1:8000
        - localhost:3000
    production:
      CSRF_TRUSTED_ORIGINS:
        - api.ara.example.org
        - web.ara.example.org
    

A list of hosts which are trusted origins for unsafe requests (e.g. POST). For a secure unsafe request, Django’s CSRF protection requires that the request have a Referer header that matches the origin present in the Host header. This prevents, for example, a POST request from subdomain.example.com from succeeding against api.example.com. If you need cross-origin unsafe requests over HTTPS, continuing the example, add “subdomain.example.com” to this list. The setting also supports subdomains, so you could add “.example.com”, for example, to allow access from all subdomains of example.com.

ARA_DATABASE_CONN_MAX_AGE

• Environment variable: ARA_DATABASE_CONN_MAX_AGE
• Configuration file variable: DATABASE_CONN_MAX_AGE
• Provided by: Django’s CONN_MAX_AGE database setting
• Type: integer
• Default: 0

The lifetime of a database connection, in seconds, before it is recycled by Django.

The default of 0 results in connections being closed automatically after each request and is appropriate if the API server is not running as a persistent service.

When running the API server as a persistent service, this setting can be increased to values such as 300 in order to enable persistent connections and avoid the performance overhead of re-establishing connections for each request.

When using the django.db.backends.mysql database engine, this value should be lower than the MySQL server’s wait_timeout configuration to prevent the database server from closing the connection before Django can complete queries.

ARA_DATABASE_ENGINE

• Environment variable: ARA_DATABASE_ENGINE
• Configuration file variable: DATABASE_ENGINE
• Provided by: Django’s ENGINE database setting
• Type: string
• Default: django.db.backends.sqlite3
• Examples:
  • django.db.backends.sqlite3
  • django.db.backends.postgresql
  • django.db.backends.mysql
  • ara.server.db.backends.distributed_sqlite

The Django database driver to use.

When using anything other than sqlite3 default driver, make sure to set the other database settings to allow the API server to connect to the database.

ARA_DATABASE_NAME

• Environment variable: ARA_DATABASE_NAME
• Configuration file variable: DATABASE_NAME
• Provided by: Django’s NAME database setting
• Type: string
• Default: ~/.ara/server/ansible.sqlite

The name of the database.

When using sqlite, this is the absolute path to the sqlite database file. When using drivers such as MySQL or PostgreSQL, it’s the name of the database.

ARA_DATABASE_USER

• Environment variable: ARA_DATABASE_USER
• Configuration file variable: DATABASE_USER
• Provided by: Django’s USER database setting
• Type: string
• Default: None

The username to connect to the database.

Required when using something other than sqlite.

ARA_DATABASE_PASSWORD

• Environment variable: ARA_DATABASE_PASSWORD
• Configuration file variable: DATABASE_PASSWORD
• Provided by: Django’s PASSWORD database setting
• Type: string
• Default: None

The password to connect to the database.

Required when using something other than sqlite.

ARA_DATABASE_HOST

• Environment variable: ARA_DATABASE_HOST
• Configuration file variable: DATABASE_HOST
• Provided by: Django’s HOST database setting
• Type: string
• Default: None

The host for the database server.

Required when using something other than sqlite.

ARA_DATABASE_PORT

• Environment variable: ARA_DATABASE_PORT
• Configuration file variable: DATABASE_PORT
• Provided by: Django’s PORT database setting
• Type: string
• Default: None

The port to use when connecting to the database server.

It is not required to set the port if you’re using default ports for MySQL or PostgreSQL.

ARA_DATABASE_OPTIONS

• Environment variable: ARA_DATABASE_OPTIONS

• Configuration file variable: DATABASE_OPTIONS

• Provided by: Django’s OPTIONS database setting

• Type: dictionary

• Default: {}

• Example:

  export ARA_DATABASE_OPTIONS='@json {"ssl": {"ca": "/etc/ssl/certificate.pem"}}'
  # or in settings.yaml:
  DATABASE_OPTIONS:
    ssl:
      ca: "/etc/ssl/certificate.pem"
  

Database options to pass to the Django database backend.

ARA_DEBUG

• Environment variable: ARA_DEBUG
• Configuration file variable: DEBUG
• Provided by: Django’s DEBUG
• Type: string
• Default: false

Whether or not Django’s debug mode should be enabled.

The Django project recommends turning this off for production use.

ARA_DISTRIBUTED_SQLITE

• Environment variable: ARA_DISTRIBUTED_SQLITE
• Configuration file variable: DISTRIBUTED_SQLITE
• Provided by: ara.server.db.backends.distributed_sqlite and ara.server.wsgi.distributed_sqlite
• Type: bool
• Default: False

Whether or not to enable the distributed sqlite database backend and WSGI application.

This feature is useful for loading different ARA sqlite databases dynamically based on request URLs.

For more information, see: distributed sqlite backend.

ARA_DISTRIBUTED_SQLITE_PREFIX

• Environment variable: ARA_DISTRIBUTED_SQLITE_PREFIX
• Configuration file variable: DISTRIBUTED_SQLITE_PREFIX
• Provided by: ara.server.db.backends.distributed_sqlite and ara.server.wsgi.distributed_sqlite
• Type: string
• Default: ara-report

Under which URL should requests be delegated to the distributed sqlite wsgi application. ara-report would delegate everything under .*/ara-report/.*

The path leading to this prefix must contain the ansible.sqlite database file, for example: /var/www/logs/some/path/ara-report/ansible.sqlite.

For more information, see: distributed sqlite backend.

ARA_DISTRIBUTED_SQLITE_ROOT

• Environment variable: ARA_DISTRIBUTED_SQLITE_ROOT
• Configuration file variable: DISTRIBUTED_SQLITE_ROOT
• Provided by: ara.server.db.backends.distributed_sqlite and ara.server.wsgi.distributed_sqlite
• Type: string
• Default: /var/www/logs

Root directory under which databases will be found relative to the requested URLs.

This will restrict where the WSGI application will go to seek out databases.

For example, the URL example.org/some/path/ara-report would translate to /var/www/logs/some/path/ara-report.

For more information, see: distributed sqlite backend.

ARA_ENV

• Environment variable: ARA_ENV
• Configuration file variable: None, this variable defines which section of a configuration file is loaded.
• Type: string
• Default: development
• Provided by: dynaconf

If you are using the API server in different environments and would like keep your configuration in a single file, you can use this variable to select a specific environment’s settings.

For example:

# Default settings are used only when not provided in the environments
default:
    READ_LOGIN_REQUIRED: false
    WRITE_LOGIN_REQUIRED: false
    LOG_LEVEL: INFO
    DEBUG: false
# Increase verbosity and debugging for the default development environment
development:
    LOG_LEVEL: DEBUG
    DEBUG: true
    SECRET_KEY: dev
# Enable write authentication when using the production environment
production:
    WRITE_LOGIN_REQUIRED: true
    SECRET_KEY: prod

With the example above, loading the development environment would yield the following settings:

• READ_LOGIN_REQUIRED: false
• WRITE_LOGIN_REQUIRED: false
• LOG_LEVEL: DEBUG
• DEBUG: true
• SECRET_KEY: dev

Another approach to environment-specific configuration is to use ARA_SETTINGS and keep your settings in different files such as dev.yaml or prod.yaml instead.

Tip

If it does not exist, the API server will generate a default configuration file at ~/.ara/server/settings.yaml. This generated file sets up all the configuration keys in the default environment. This lets users override only the parameters they are interested in for specific environments.

ARA_EXTERNAL_AUTH

• Environment variable: ARA_EXTERNAL_AUTH
• Configuration file variable: EXTERNAL_AUTH
• Type: bool
• Default: False
• Provided by: django-rest-framework authentication

Whether or not to enable external authentication.

ARA_LOGGING

• Environment variable: Not recommended, use configuration file

• Configuration file variable: LOGGING

• Type: dictionary

• Default:

  LOGGING:
      disable_existing_loggers: false
      formatters:
          normal:
              format: '%(asctime)s %(levelname)s %(name)s: %(message)s'
      handlers:
          console:
              class: logging.StreamHandler
              formatter: normal
              level: INFO
              stream: ext://sys.stdout
      loggers:
          ara:
              handlers:
              - console
              level: INFO
              propagate: 0
      level: INFO
      version: 1
  

The python logging configuration for the API server.

ARA_LOG_LEVEL

• Environment variable: ARA_LOG_LEVEL
• Configuration file variable: LOG_LEVEL
• Type: string
• Default: INFO

Log level of the different components from the API server.

ARA_LOG_LEVEL changes the log level of the default logging configuration provided by ARA_LOGGING.

ARA_SETTINGS

• Environment variable: ARA_SETTINGS
• Configuration file variable: None, this variable defines the configuration file itself.
• Type: string
• Default: None
• Provided by: dynaconf

Location of an API server configuration file to load settings from. The API server will generate a default configuration file at ~/.ara/server/settings.yaml that you can use to get started.

Note that while the configuration file is in YAML by default, it is possible to have configuration files written in ini, json and toml as well.

Settings and configuration parsing by the API server is provided by the dynaconf python library.

ARA_PAGE_SIZE

• Environment variable: ARA_PAGE_SIZE
• Configuration file variable: PAGE_SIZE
• Type: integer
• Default: 100
• Provided by: django-rest-framework pagination

When querying the API server or the built-in reporting interface, the amount of items per page returned by default.

ARA_READ_LOGIN_REQUIRED

• Environment variable: ARA_READ_LOGIN_REQUIRED
• Configuration file variable: READ_LOGIN_REQUIRED
• Type: bool
• Default: False
• Provided by: django-rest-framework permissions

Determines if authentication is required before being authorized to query all API endpoints exposed by the server.

There is no concept of granularity: users either have access to query everything or they don’t.

Enabling this feature first requires setting up users.

ARA_SECRET_KEY

• Environment variable: ARA_SECRET_KEY
• Configuration file variable: SECRET_KEY
• Provided by: Django’s SECRET_KEY
• Type: string
• Default: Randomized with django.utils.crypto.get_random_string()

A secret key for a particular Django installation. This is used to provide cryptographic signing, and should be set to a unique, unpredictable value.

If it is not set, a random token will be generated and persisted in the default configuration file.

ARA_TIME_ZONE

• Environment variable: ARA_TIME_ZONE
• Configuration file variable: TIME_ZONE
• Provided by: Django’s TIME_ZONE
• Type: string
• Default: Local system timezone
• Examples:
  • UTC
  • US/Eastern
  • America/Montreal
  • Europe/Paris

The time zone to store and return results in.

ARA_WRITE_LOGIN_REQUIRED

• Environment variable: ARA_WRITE_LOGIN_REQUIRED
• Configuration file variable: WRITE_LOGIN_REQUIRED
• Type: bool
• Default: False
• Provided by: django-rest-framework permissions

Determines if authentication is required before being authorized to post data to all API endpoints exposed by the server.

There is no concept of granularity: users either have access to query everything or they don’t.

Enabling this feature first requires setting up users.

ARA API Server authentication and security

The API server ships with a default configuration that emphasizes simplicity to let users get started quickly.

By default:

• A random SECRET_KEY will be generated once if none are supplied
• No users are created
• API authentication and permissions are not enabled
• ALLOWED_HOSTS and CORS_ORIGIN_WHITELIST are configured for use on localhost

These default settings can be configured according to the requirements of your deployments.

Note

For production use and to avoid unintentionally leaking passwords, tokens, secrets or otherwise sensitive information that ara might come across and record, it is strongly encouraged to:

1. Enable authentication for the web interface and API (see below)
2. Configure the callback plugin to ignore sensitive files, host facts and CLI arguments (such as extra vars)

Setting a custom secret key

By default, the API server randomly generates a token for the ARA_SECRET_KEY setting if none have been supplied by the user.

This value is persisted in the server configuration file in order to prevent the key from changing on every instanciation of the server.

The default location for the server configuration file is ~/.ara/server/settings.yaml.

You can provide a custom secret key by supplying the ARA_SECRET_KEY environment variable or by specifying the SECRET_KEY setting in your server configuration file.

Authentication and user management

It is recommended to set up authentication to protect the ara API and reporting interface since the data collected by ara can be sensitive or otherwise non-public information about your hosts, playbook files or task results.

There are two main ways of managing authentication:

1. Via a server/proxy in front of the API server (recommended, best performance)
2. Via django’s built-in authentication (impacts performance but doesn’t require server/proxy in front)

In the first scenario, there could be an nginx reverse proxy or apache2/httpd server with mod_proxy authenticating against a .htpasswd file, ldap and other authentication mechanisms supported by the servers.

Once authenticated, users and clients have read/write access unless there is a specific proxy configuration based on the URL or methods (GET/POST/PATCH/DELETE).

In the second case, there can still be a server/proxy in front but it wouldn’t manage the authentication. Users are managed in django and authentication is done against the database backend for each request, incurring a performance hit when validating access and permissions.

This method provides the possibility of a simple “read-only” access by setting READ_LOGIN_REQUIRED: false and WRITE_LOGIN_REQUIRED: true.

#1: Authentication via a server/proxy

When authentication is handled by a server or proxy in front of the ara API server, the following should be set in ~/.ara/server/settings.yaml:

default:
  # [...]
  EXTERNAL_AUTH: true
  READ_LOGIN_REQUIRED: false
  WRITE_LOGIN_REQUIRED: false
  # [...]

EXTERNAL_AUTH is used to accept authentication provided by the server in front of the API server.

READ_LOGIN_REQUIRED and WRITE_LOGIN_REQUIRED should both be false as they are only used when django is the one handling the authentication.

Once the ara API server has been restarted with the right settings, it is ready to accept requests from a server or proxy in front of it.

What follows are some example proxy configurations that have been contributed by users.

.htpasswd with nginx or apache2/httpd

1. Set up the right configuration in settings.yaml (see parent)
2. Install and start nginx or apache2/httpd
3. Create a .htpasswd file with an encrypted username/password, for example: htpasswd -c -m /etc/httpd/.htpasswd username
4. Set up a virtual host configuration in nginx or apache2/httpd
5. Ensure ara and proxy servers have been restarted with new configuration
6. Complete

For apache2/httpd, you can get started with the following configuration:

# /etc/httpd/conf.d/ara.conf
# or /etc/apache2/sites-{available|enabled}/ara.conf
<VirtualHost *:80>
    ServerName ara.example.org
    ProxyPass / http://127.0.0.1:8000/
    ProxyPassReverse / http://127.0.0.1:8000/

    <Location />
        Deny from all
        AuthUserFile /etc/httpd/.htpasswd
        AuthName "Privileged access"
        AuthType Basic
        Satisfy Any
        require valid-user
    </Location>
</VirtualHost>

For nginx, you can get started with the following configuration:

# /etc/nginx/conf.d/ara.conf
# or /etc/nginx/sites-{available|enabled}/ara.conf
upstream ara_api {
    # fail_timeout=0 means we always retry an upstream even if it failed
    # to return a good HTTP response
    server 127.0.0.1:8000 fail_timeout=0;
}

server {
    listen 80 default_server;
    server_name ara.example.org;
    auth_basic "Privileged access";
    auth_basic_user_file /etc/nginx/.htpasswd;

    # Everything, including static files, is served by the backend
    location ~ {
        # checks if the file exists, if not found proxy to app
        try_files $uri @proxy_to_app;
    }

    location @proxy_to_app {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;

        proxy_redirect off;
        proxy_pass http://ara_api;
    }
}

ldap with apache2/httpd and mod_ldap

1. Set up the right configuration in settings.yaml (see parent)
2. Install and start apache2/httpd with mod_ldap
3. Set up a virtual host configuration for apache2/httpd
4. Ensure ara and proxy servers have been restarted with new configuration
5. Complete

You can get started with the following configuration:

# /etc/httpd/conf.d/ara.conf
# or /etc/apache2/sites-{available|enabled}/ara.conf
<VirtualHost *:80>
    ServerName ara.example.org
    ProxyPass / http://127.0.0.1:8000/
    ProxyPassReverse / http://127.0.0.1:8000/

    <Location />
        AuthName "Privileged access"
        AuthType Basic
        AuthBasicProvider ldap
        AuthLDAPURL "ldap://openldap/dc=example,dc=org?uid"
        AuthLDAPBindDN "cn=admin,dc=example,dc=org"
        AuthLDAPBindPassword "some_password"
        Require valid-user
        Allow from all
        Order allow,deny
    </Location>
</VirtualHost>

#2: Authentication via django

The API server can leverage Django’s built-in user management but doesn’t create any user by default.

Note

Creating users does not enable authentication on the API. In order to make authentication required for using the API, see Enabling authentication for read or write access.

In order to create users, you’ll need to create a superuser account before running the API server:

$ ara-manage createsuperuser --username=joe --email=joe@example.com
Password:
Password (again):
Superuser created successfully.

Tip

If you ever need to reset the password of a superuser account, this can be done with the “changepassword” command:

$ ara-manage changepassword joe
Changing password for user 'joe'
Password:
Password (again):
Password changed successfully for user 'joe'

Once the superuser has been created, make sure the API server is started and then login to the Django web administrative interface using the credentials you just set up.

By default, you can start the API server with ara-manage runserver and access the admin interface at http://127.0.0.1:8000/admin/.

Log in to the admin interface:

Access the authentication and authorization configuration:

And from here, you can manage existing users or create new ones:

Enabling authentication for read or write access

Once django users have been created, you can enable authentication against the API for read (ex: GET) and write (ex: DELETE, POST, PATCH) requests.

This is done with the two following configuration options:

• ARA_READ_LOGIN_REQUIRED for read access
• ARA_WRITE_LOGIN_REQUIRED for write access

These settings are global and are effective for all API endpoints.

Setting up authentication for the Ansible plugins

The callback plugin used to record playbooks as well as the ara_record action plugin will need to authenticate against the API if authentication is enabled and required.

You can specify the necessary credentials through the ARA_API_USERNAME and ARA_API_PASSWORD environment variables or through your ansible.cfg file:

[defaults]
# ...

[ara]
api_client = http
api_server = http://api.example.org
api_username = ara
api_password = password

Using authentication with the API clients

To instanciate an authenticated client with the built-in basic HTTP authentication provided by Django:

from ara.clients.utils import get_client
client = get_client(
    client="http",
    endpoint="http://api.example.org",
    username="ara",
    password="password"
)

If you have a custom authentication that is supported by the python requests library, you can also pass the relevant auth object directly to the client:

from ara.clients.http import AraHttpClient
from requests_oauthlib import OAuth1
auth = OAuth1(
    "YOUR_APP_KEY",
    "YOUR_APP_SECRET",
    "USER_OAUTH_TOKEN",
    "USER_OAUTH_TOKEN_SECRET"
)
client = AraHttpClient(endpoint="http://api.example.org", auth=auth)

Managing hosts allowed to serve the API

By default, ARA_ALLOWED_HOSTS authorizes localhost, ::1 and 127.0.0.1 to serve requests for the API server.

In order to host an instance of the API server on another domain, the domain must be part of this list or the application server will deny any requests sent to it.

Managing CORS (cross-origin resource sharing)

The ARA_CORS_ORIGIN_WHITELIST default is designed to allow a local development instance of an ara-web dashboard to communicate with a local development instance of the API server.

The whitelist must contain the domain names where you plan on hosting instances of ara-web.

API Documentation

The API documentation is a work in progress.

Built-in API browser interface

ARA ships with a helpful interface to navigate the API directly from your favorite web browser.

For example, if you run ara-manage runserver, this interface would be available at http://127.0.0.1:8000/api/v1/:

You can navigate the interface and drill down to list views, for example:

You can also see what a detailed view looks like by querying a specific object id:

Alternatively, you may also find an up-to-date live demonstration of the API at https://demo.recordsansible.org.

Relationship between objects

Here’s a high level overview of how data is generally organized:

Label   Record (ara_record)              LatestHost
    \   /                                 /
  Playbook -> Play -> Task -> Result <- Host
          \          /          |        |
           \        /        Content   Facts
            \ File /
               |
            Content

• Every object except labels and LatestHost are associated to a parent playbook
• Labels are applied on a playbook while a LatestHost references a specific Host
• Records have a key, a value and a type provided by ara_record
• In a playbook there are plays
• In a play there are tasks
• In a task there are results
• Results have a relation to their parent task and the host the task ran on
• Results have content with data returned by Ansible for a task on a host
• Hosts have stats provided by Ansible and facts (if they have been set or gathered)
• A LatestHost relation keeps track of the last playbook a host name was involved in
• Playbooks and Tasks both have a path and a reference to a File
• A file has content compressed and uniquely stored, hashed by sha1

These relationships are also represented in the database model:

Tip

Open the image above in a new tab to see it in full resolution.

Additional fields may only be available in the detailed views. For example:

• Playbooks arguments with /api/v1/playbooks/<id>
• Hosts facts with /api/v1/hosts/<id> or /api/v1/latesthosts
• Results content with /api/v1/results/<id>
• Files content with /api/v1/files/<id>

ARA ships with two built-in API clients to help you get started. You can learn more about those clients in Using ARA API clients.

Using ARA API clients

When installing ARA, you are provided with a REST API server and two API clients out of the box:

• AraOfflineClient can query the API without needing an API server to be running
• AraHttpClient is meant to query a specified API server over http

ARA Offline API client

If your use case doesn’t require a remote or persistent API server, the offline client lets you query the API without needing to start an API server.

In order to use this client, you would instanciate it like this:

#!/usr/bin/env python3
# Import the client
from ara.clients.offline import AraOfflineClient

# Instanciate the offline client
client = AraOfflineClient()

Note that, by default, instanciating an offline client will automatically run SQL migrations.

If you expect the migrations to have already been run when you instanciate the client, you can disable automatic SQL migrations with by specifying run_sql_migrations=False:

client = AraOfflineClient(run_sql_migrations=False)

ARA HTTP API client

AraHttpClient works with the same interface, methods and behavior as AraOfflineClient.

You can set your client to communicate with a remote ara-server API by specifying an endpoint parameter:

#!/usr/bin/env python3
# Import the client
from ara.clients.http import AraHttpClient

endpoint = "https://demo.recordsansible.org"
# Instanciate the HTTP client with an endpoint where an API server is listening
client = AraHttpClient(endpoint=endpoint)

# SSL verification can be disabled with verify=False
client = AraHttpClient(endpoint=endpoint, verify=False)

Example API usage

For more details on the API endpoints, see API Documentation.

Otherwise, once you’ve instanciated your client, you’re ready to query the API.

Here’s a code example to help you get started:

#!/usr/bin/env python3
# Import the client
from ara.clients.http import AraHttpClient

# Instanciate the HTTP client with an endpoint where an API server is listening
client = AraHttpClient(endpoint="https://demo.recordsansible.org")

# Get a list of failed playbooks
# /api/v1/playbooks?status=failed
playbooks = client.get("/api/v1/playbooks", status="failed")

# If there are any results from our query, get more information about the
# failure and print something helpful
template = "{timestamp}: {host} failed '{task}' ({task_file}:{lineno})"

for playbook in playbooks["results"]:
    # Get failed results for the playbook
    results = client.get("/api/v1/results?playbook=%s" % playbook["id"])

    # For each result, print the task and host information
    for result in results["results"]:
        task = client.get("/api/v1/tasks/%s" % result["task"])
        host = client.get("/api/v1/hosts/%s" % result["host"])

        print(template.format(
            timestamp=result["ended"],
            host=host["name"],
            task=task["name"],
            task_file=task["path"],
            lineno=task["lineno"]
        ))

Running this script would then provide an output that looks like the following:

2020-04-18T17:16:13.394056Z: aio1_repo_container-0c92f7a2 failed 'repo_server : Install EPEL gpg keys' (/home/zuul/src/opendev.org/openstack/openstack-ansible-repo_server/tasks/repo_install.yml:16)
2020-04-18T17:14:59.930995Z: aio1_repo_container-0c92f7a2 failed 'repo_server : File and directory setup (root user)' (/home/zuul/src/opendev.org/openstack/openstack-ansible-repo_server/tasks/repo_pre_install.yml:78)
2020-04-18T17:14:57.909155Z: aio1_repo_container-0c92f7a2 failed 'repo_server : Git service data folder setup' (/home/zuul/src/opendev.org/openstack/openstack-ansible-repo_server/tasks/repo_pre_install.yml:70)
2020-04-18T17:14:57.342091Z: aio1_repo_container-0c92f7a2 failed 'repo_server : Check if the git folder exists already' (/home/zuul/src/opendev.org/openstack/openstack-ansible-repo_server/tasks/repo_pre_install.yml:65)
2020-04-18T17:14:56.793499Z: aio1_repo_container-0c92f7a2 failed 'repo_server : Drop repo pre/post command script' (/home/zuul/src/opendev.org/openstack/openstack-ansible-repo_server/tasks/repo_pre_install.yml:53)
2020-04-18T17:14:54.507660Z: aio1_repo_container-0c92f7a2 failed 'repo_server : File and directory setup (non-root user)' (/home/zuul/src/opendev.org/openstack/openstack-ansible-repo_server/tasks/repo_pre_install.yml:32)
2020-04-18T17:14:51.281530Z: aio1_repo_container-0c92f7a2 failed 'repo_server : Create the nginx system user' (/home/zuul/src/opendev.org/openstack/openstack-ansible-repo_server/tasks/repo_pre_install.yml:22)

Distributed sqlite database backend

The ARA API server provides an optional backend that dynamically loads sqlite databases based on the requested URL with the help of a WSGI application middleware.

In summary, it maps an URL such as http://example.org/some/path/ara-report to a location on the file system like /var/www/logs/some/path/ara-report and loads an ansible.sqlite database from that directory, if it exists.

Note

This backend is not enabled by default and is designed with a specific range of use cases in mind. This documentation attempts to explain if this might be a good fit for you.

Use case

Running at least one Ansible playbook with the ARA Ansible callback plugin enabled will generate a database at ~/.ara/server/ansible.sqlite by default.

sqlite, in the context of ARA, is good enough for most use cases:

• it is portable: everything the API server needs is in a single file that you can upload anywhere
• no network dependency or latency: sqlite is on your filesystem and doesn’t rely on a remote database server
• relatively lightweight: Ansible’s own integration tests used ~13MB for 415 playbooks, 1935 files, 12456 tasks, 12762 results, 586 hosts (and host facts)

However, since write concurrency does not scale very well with sqlite, it might not be a good fit if you plan on having a single API server handle data for multiple ansible-playbook commands running at the same time.

The distributed sqlite database backend and WSGI middleware provide an alternative to work around this limitation.

This approach works best if it makes sense to logically split your playbooks into different databases. One such example is in continuous integration (CI) where you might have multiple jobs running Ansible playbooks concurrently.

If each CI job is recording to its own database, you probably no longer have write concurrency issues and the database can be uploaded in your logs or as an artifact after the job has been completed.

The file hierarchy on your log or artifact server might end up looking like this:

/var/www/logs/
├── 1
│   ├── ara-report
│   │   └── ansible.sqlite
│   └── console.txt
├── 2
│   ├── logs.tar.gz
│   └── some
│       └── path
│           └── ara-report
│               └── ansible.sqlite
└── 3
    ├── builds.txt
    ├── dev
    │   └── ara-report
    │       └── ansible.sqlite
    └── prod
        └── ara-report
            └── ansible.sqlite

With the above example file tree, a single instance of the API server with the distributed sqlite backend enabled would be able to respond to queries at the following endpoints:

• http://example.org/1/ara-report
• http://example.org/2/some/path/ara-report
• http://example.org/3/dev/ara-report
• http://example.org/3/prod/ara-report

Configuration

For enabling and configuring the distributed sqlite backend, see:

• ARA_DISTRIBUTED_SQLITE
• ARA_DISTRIBUTED_SQLITE_PREFIX
• ARA_DISTRIBUTED_SQLITE_ROOT

When recording data to a sqlite database, the location of the database can be defined with ARA_DATABASE_NAME.

Running ARA API server container images

The ARA API server is a good candidate for being served out of a container as the configuration and state can be kept in persistent files and databases.

The project maintains different scripts that are used to build and push simple container images to DockerHub.

The scripts are designed to yield images that are opinionated and “batteries-included” for the sake of simplicity. They install the necessary packages for connecting to MySQL and PostgreSQL databases and set up gunicorn as the application server.

You are encouraged to use these scripts as a base example that you can build, tweak and improve the container image according to your specific needs and preferences.

For example, precious megabytes can be saved by installing only the things you need and you can change the application server as well as it’s configuration.

Building an image with buildah

You will need to install buildah.

The different scripts to build container images are available in the git repository:

• fedora-distribution.sh: Builds an image from Fedora 38 distribution packages
• fedora-pypi.sh: Builds an image from PyPi packages on Fedora 38
• fedora-source.sh: Builds an image from git source on Fedora 38
• centos-pypi.sh: Builds an image from PyPi packages on CentOS 9 Stream
• centos-source.sh: Builds an image from git source on CentOS 9 Stream

The scripts have no arguments other than the ability to specify an optional name and tag:

$ git clone https://github.com/ansible-community/ara
$ cd ara/contrib/container-images
$ ./fedora-source.sh ara-api:latest
# [...]
Getting image source signatures
Copying blob 59bbb69efd73 skipped: already exists
Copying blob ccc3e7c17eae done
Copying config fb679fc301 done
Writing manifest to image destination
Storing signatures
fb679fc301dde7007b4d219f1d30060b3b4b0d5883b030ee7058d7e9f5969fbe

The image will be available for use once the script has finished running:

$ buildah images
REPOSITORY          TAG      IMAGE ID       CREATED          SIZE
localhost/ara-api   latest   fb679fc301dd   25 minutes ago   451 MB

Running an image with podman

You will need to install podman.

Once an image has been built with the scripts above, you can validate that it is available to podman:

$ podman images
REPOSITORY          TAG      IMAGE ID       CREATED          SIZE
localhost/ara-api   latest   fb679fc301dd   31 minutes ago   451 MB

First, create a directory where settings, logs and sqlite databases will persist inside a volume and then start the container:

$ mkdir -p ~/.ara/server
$ podman run --name api-server --detach --tty \
     --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \
     localhost/ara-api
bc4b7630c265bdac161f2e08116f3f45c2db519fb757ddf865bb0f212780fa8d

You can validate if the container is running properly with podman:

$ podman ps
CONTAINER ID  IMAGE                     COMMAND               CREATED         STATUS             PORTS                   NAMES
bc4b7630c265  localhost/ara-api:latest  /usr/bin/gunicorn...  12 seconds ago  Up 11 seconds ago  0.0.0.0:8000->8000/tcp  api-server

$ podman logs api-server
[ara] No setting found for SECRET_KEY. Generating a random key...
[ara] Writing default settings to /opt/ara/settings.yaml
[ara] Using settings file: /opt/ara/settings.yaml
Operations to perform:
Apply all migrations: admin, api, auth, contenttypes, db, sessions
Running migrations:
Applying contenttypes.0001_initial... OK
Applying auth.0001_initial... OK
Applying admin.0001_initial... OK
Applying admin.0002_logentry_remove_auto_add... OK
Applying admin.0003_logentry_add_action_flag_choices... OK
Applying api.0001_initial... OK
Applying api.0002_remove_host_alias... OK
Applying api.0003_add_missing_result_properties... OK
Applying api.0004_duration_in_database... OK
Applying api.0005_unique_label_names... OK
Applying contenttypes.0002_remove_content_type_name... OK
Applying auth.0002_alter_permission_name_max_length... OK
Applying auth.0003_alter_user_email_max_length... OK
Applying auth.0004_alter_user_username_opts... OK
Applying auth.0005_alter_user_last_login_null... OK
Applying auth.0006_require_contenttypes_0002... OK
Applying auth.0007_alter_validators_add_error_messages... OK
Applying auth.0008_alter_user_username_max_length... OK
Applying auth.0009_alter_user_last_name_max_length... OK
Applying auth.0010_alter_group_name_max_length... OK
Applying auth.0011_update_proxy_permissions... OK
Applying db.0001_initial... OK
Applying sessions.0001_initial... OK
[2020-05-05 17:29:22 +0000] [1] [INFO] Starting gunicorn 20.0.4
[2020-05-05 17:29:22 +0000] [1] [INFO] Listening at: http://0.0.0.0:8000 (1)
[2020-05-05 17:29:22 +0000] [1] [INFO] Using worker: sync
[2020-05-05 17:29:22 +0000] [5] [INFO] Booting worker with pid: 5
[2020-05-05 17:29:22 +0000] [6] [INFO] Booting worker with pid: 6
[2020-05-05 17:29:23 +0000] [7] [INFO] Booting worker with pid: 7
[2020-05-05 17:29:23 +0000] [8] [INFO] Booting worker with pid: 8

At this point, the API server will be running but it’ll be empty.

Data must be sent to it by running an Ansible playbook with the ARA callback installed and configured to use this API server.

Sending data to the API server

Here’s an example of how it works:

# Create and source a python3 virtual environment
python3 -m venv ~/.ara/virtualenv
source ~/.ara/virtualenv/bin/activate

# Install Ansible and ARA
pip3 install ansible ara

# Configure Ansible to know where ARA's callback plugin is located
export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins)

# Set up the ARA callback to know where the API server is
export ARA_API_CLIENT=http
export ARA_API_SERVER="http://127.0.0.1:8000"

# Run any of your Ansible playbooks as you normally would
ansible-playbook playbook.yml

As each task from the playbook starts and completes, their data will be available on the API server in real time as you refresh your queries.

Common operations

Modifying ARA’s API server settings

Settings for the API server will be found in ~/.ara/server/settings.yaml (or /opt/ara/settings.yaml inside the container) and modifications are effective after a container restart:

podman restart api-server

See the documentation for the full list of available options.

Running outside of localhost

To run an API server that can be queried from other hosts, edit ~/.ara/server/settings.yaml and add the desired hostname (or IP) in ALLOWED_HOSTS.

Connecting to mysql, mariadb or postgresql backends

The ARA API server is a good candidate for living in a container because the state can be stored on remote database servers.

To connect to database backends other than the sqlite default, edit ~/.ara/server/settings.yaml and look for the following settings:

• DATABASE_ENGINE
• DATABASE_NAME
• DATABASE_USER
• DATABASE_PASSWORD
• DATABASE_HOST
• DATABASE_PORT
• DATABASE_CONN_MAX_AGE

Running SQL migrations

The container image will automatically take care of running SQL migrations before starting.

However, if you need to run them manually, either for a new database or after an upgrade, the command ara-manage migrate can be run from inside the container:

$ podman exec -it api-server ara-manage migrate
[ara] Using settings file: /opt/ara/settings.yaml
Operations to perform:
Apply all migrations: admin, api, auth, contenttypes, db, sessions
Running migrations:
Applying contenttypes.0001_initial... OK
Applying auth.0001_initial... OK
Applying admin.0001_initial... OK
Applying admin.0002_logentry_remove_auto_add... OK
Applying admin.0003_logentry_add_action_flag_choices... OK
Applying api.0001_initial... OK
Applying api.0002_remove_host_alias... OK
Applying api.0003_add_missing_result_properties... OK
Applying api.0004_duration_in_database... OK
Applying api.0005_unique_label_names... OK
Applying contenttypes.0002_remove_content_type_name... OK
Applying auth.0002_alter_permission_name_max_length... OK
Applying auth.0003_alter_user_email_max_length... OK
Applying auth.0004_alter_user_username_opts... OK
Applying auth.0005_alter_user_last_login_null... OK
Applying auth.0006_require_contenttypes_0002... OK
Applying auth.0007_alter_validators_add_error_messages... OK
Applying auth.0008_alter_user_username_max_length... OK
Applying auth.0009_alter_user_last_name_max_length... OK
Applying auth.0010_alter_group_name_max_length... OK
Applying auth.0011_update_proxy_permissions... OK
Applying db.0001_initial... OK
Applying sessions.0001_initial... OK

CLI: ara API client

Installing ara provides an ara command line interface client in order to query API servers from shell scripts or from the terminal.

ara

$ ara --help
usage: ara [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug]

A CLI client to query ARA API servers

optional arguments:
  --version            show program's version number and exit
  -v, --verbose        Increase verbosity of output. Can be repeated.
  -q, --quiet          Suppress output except warnings and errors.
  --log-file LOG_FILE  Specify a file to log output. Disabled by default.
  -h, --help           Show help message and exit.
  --debug              Show tracebacks on errors.

Commands:
  complete       print bash completion command (cliff)
  expire         Expires objects that have been in the running state for too long
  help           print detailed help for another command (cliff)
  host delete    Deletes the specified host and associated resources
  host list      Returns a list of hosts based on search queries
  host metrics   Provides metrics about hosts
  host show      Returns a detailed view of a specified host
  play delete    Deletes the specified play and associated resources
  play list      Returns a list of plays based on search queries
  play show      Returns a detailed view of a specified play
  playbook delete  Deletes the specified playbook and associated resources
  playbook list  Returns a list of playbooks based on search queries
  playbook metrics  Provides metrics about playbooks
  playbook prune  Deletes playbooks beyond a specified age in days
  playbook show  Returns a detailed view of a specified playbook
  record delete  Deletes the specified record and associated resources
  record list    Returns a list of records based on search queries
  record show    Returns a detailed view of a specified record
  result delete  Deletes the specified result and associated resources
  result list    Returns a list of results based on search queries
  result show    Returns a detailed view of a specified result
  task delete    Deletes the specified task and associated resources
  task list      Returns a list of tasks based on search queries
  task metrics   Provides metrics about actions in tasks
  task show      Returns a detailed view of a specified task

ara expire

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara expire --help
usage: ara expire [-h] [--client <client>] [--server <url>]
                  [--timeout <seconds>] [--username <username>]
                  [--password <password>] [--ssl-cert <path/to/certificate>]
                  [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                  [--insecure] [--hours HOURS] [--order <order>]
                  [--limit <limit>] [--confirm]

Expires objects that have been in the running state for too long

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --hours HOURS         Expires objects that have been running state for this
                        many hours (default: 24)
  --order <order>       Orders objects by a field ('id', 'created', 'updated',
                        'started', 'ended')
                        Defaults to 'started' descending so the oldest objects
                        would be expired first.
                        The order can be reversed by using '-': ara expire
                        --order=-started
  --limit <limit>       Only expire the first <limit> determined by the
                        ordering. Defaults to ARA_CLI_LIMIT or 200.
  --confirm             Confirm expiration of objects, otherwise runs without
                        expiring any objects

Examples:

# Return which objects would be expired by ommitting --confirm
ara expire

# Expire running objects without updates faster than the default
ara expire --hours 4 --confirm

ara playbook list

$ ara playbook list --help
usage: ara playbook list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                         [--quote {all,minimal,none,nonnumeric}] [--noindent]
                         [--max-width <integer>] [--fit-width] [--print-empty]
                         [--sort-column SORT_COLUMN]
                         [--sort-ascending | --sort-descending]
                         [--client <client>] [--server <url>]
                         [--timeout <seconds>] [--username <username>]
                         [--password <password>]
                         [--ssl-cert <path/to/certificate>]
                         [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                         [--insecure] [--label <label>]
                         [--ansible_version <ansible_version>]
                         [--client_version <client_version>]
                         [--server_version <server_version>]
                         [--python_version <python_version>] [--user <user>]
                         [--controller <controller>] [--name <name>]
                         [--path <path>] [--status <status>] [--long]
                         [--order <order>] [--limit <limit>]

Returns a list of playbooks based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --label <label>       List playbooks matching the provided label
  --ansible_version <ansible_version>
                        List playbooks that ran with the specified Ansible
                        version (full or partial)
  --client_version <client_version>
                        List playbooks that were recorded with the specified
                        ara client version (full or partial)
  --server_version <server_version>
                        List playbooks that were recorded with the specified
                        ara server version (full or partial)
  --python_version <python_version>
                        List playbooks that were recorded with the specified
                        python version (full or partial)
  --user <user>         List playbooks that were run by the specified user
                        (full or partial)
  --controller <controller>
                        List playbooks that ran from the provided controller
                        (full or partial)
  --name <name>         List playbooks matching the provided name (full or
                        partial)
  --path <path>         List playbooks matching the provided path (full or
                        partial)
  --status <status>     List playbooks matching a specific status
                        ('completed', 'running', 'failed')
  --long                Don't truncate paths and include additional fields:
                        name, plays, files, records
  --order <order>       Orders playbooks by a field ('id', 'created',
                        'updated', 'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        playbook is at the top.
                        The order can be reversed by omitting the '-': ara
                        playbook list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Query a running API server for the 10 latest failed playbooks:

ara playbook list --client http \
  --server https://demo.recordsansible.org \
  --status failed \
  --limit 10

Get a list of playbooks matching a partial path and order the results by duration using the default offline API client:

ara playbook list --path="playbooks/site.yaml" --order=duration

Get a list of playbooks and format the results as json or yaml instead of pretty tables:

ara playbook list -f json
ara playbook list -f yaml

ara playbook show

$ ara playbook show --help
usage: ara playbook show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                         [--noindent] [--prefix PREFIX]
                         [--max-width <integer>] [--fit-width] [--print-empty]
                         [--client <client>] [--server <url>]
                         [--timeout <seconds>] [--username <username>]
                         [--password <password>]
                         [--ssl-cert <path/to/certificate>]
                         [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                         [--insecure]
                         <playbook-id>

Returns a detailed view of a specified playbook

positional arguments:
  <playbook-id>         Playbook to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Show details about a playbook from a running API server and format the result in json:

ara playbook show --client http --server https://demo.recordsansible.org 1 -f json

Show details about a playbook from a local installation using the default offline API client and format the result in yaml:

ara playbook show 1 -f yaml

ara playbook delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara playbook delete --help
usage: ara playbook delete [-h] [--client <client>] [--server <url>]
                           [--timeout <seconds>] [--username <username>]
                           [--password <password>]
                           [--ssl-cert <path/to/certificate>]
                           [--ssl-key <path/to/key>]
                           [--ssl-ca <path/to/cacert>] [--insecure]
                           <playbook-id>

Deletes the specified playbook and associated resources

positional arguments:
  <playbook-id>         Playbook to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara playbook metrics

$ ara playbook metrics --help
usage: ara playbook metrics [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                            [--quote {all,minimal,none,nonnumeric}]
                            [--noindent] [--max-width <integer>] [--fit-width]
                            [--print-empty] [--sort-column SORT_COLUMN]
                            [--sort-ascending | --sort-descending]
                            [--client <client>] [--server <url>]
                            [--timeout <seconds>] [--username <username>]
                            [--password <password>]
                            [--ssl-cert <path/to/certificate>]
                            [--ssl-key <path/to/key>]
                            [--ssl-ca <path/to/cacert>] [--insecure]
                            [--aggregate {name,path,ansible_version,controller}]
                            [--label <label>]
                            [--ansible_version <ansible_version>]
                            [--client_version <client_version>]
                            [--server_version <server_version>]
                            [--python_version <python_version>]
                            [--name <name>] [--controller <controller>]
                            [--path <path>] [--status <status>] [--long]
                            [--order <order>] [--limit <limit>]

Provides metrics about playbooks

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --aggregate {name,path,ansible_version,controller}
                        Aggregate playbooks by path, name, ansible version or
                        controller. Defaults to path.
  --label <label>       List playbooks matching the provided label
  --ansible_version <ansible_version>
                        List playbooks that ran with the specified Ansible
                        version (full or partial)
  --client_version <client_version>
                        List playbooks that were recorded with the specified
                        ara client version (full or partial)
  --server_version <server_version>
                        List playbooks that were recorded with the specified
                        ara server version (full or partial)
  --python_version <python_version>
                        List playbooks that were recorded with the specified
                        python version (full or partial)
  --name <name>         List playbooks matching the provided name (full or
                        partial)
  --controller <controller>
                        List playbooks that ran from the provided controller
                        (full or partial)
  --path <path>         List playbooks matching the provided path (full or
                        partial)
  --status <status>     List playbooks matching a specific status
                        ('completed', 'running', 'failed')
  --long                Don't truncate paths and include additional fields:
                        name, plays, files, records
  --order <order>       Orders playbooks by a field ('id', 'created',
                        'updated', 'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        playbook is at the top.
                        The order can be reversed by omitting the '-': ara
                        playbook list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 1000.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# Return metrics about more than the last 1000 playbooks
ara playbook metrics --limit 10000

# Return playbook metrics in json or csv
ara playbook metrics -f json
ara playbook metrics -f csv

# Return metrics about playbooks matching a (full or partial) path
ara playbook metrics --path site.yml

# Return metrics for playbooks matching a label
ara playbook metrics --label "check:False"

# Return additional metrics without truncating paths
ara playbook metrics --long

# Aggregate metrics by playbook path (default), name, by ansible version or by controller
ara playbook metrics --aggregate name
ara playbook metrics --aggregate ansible_version
ara playbook metrics --aggregate controller

ara playbook prune

Pruning keeps the database size in check and the performance optimal by deleting older playbooks.

Unused disk space can be reclaimed after pruning depending on your database backend, for example:

• sqlite: sqlite3 ~/.ara/server/ansible.sqlite vacuum
• mysql/mariadb: mysqlcheck --optimize --databases ara
• postgresql: vacuumdb --dbname=ara

It is recommended to run this command inside a task scheduler (such as cron) since the server does not run this command automatically.

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara playbook prune --help
usage: ara playbook prune [-h] [--client <client>] [--server <url>]
                          [--timeout <seconds>] [--username <username>]
                          [--password <password>]
                          [--ssl-cert <path/to/certificate>]
                          [--ssl-key <path/to/key>]
                          [--ssl-ca <path/to/cacert>] [--insecure]
                          [--days DAYS] [--label <label>] [--name <name>]
                          [--user <user>]
                          [--ansible_version <ansible_version>]
                          [--client_version <client_version>]
                          [--server_version <server_version>]
                          [--python_version <python_version>]
                          [--controller <controller>] [--path <path>]
                          [--status <status>] [--order <order>]
                          [--limit <limit>] [--confirm]

Deletes playbooks beyond a specified age in days

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --days DAYS           Delete playbooks started this many days ago (default:
                        31)
  --label <label>       Only delete playbooks matching the provided label
  --name <name>         Only delete playbooks matching the provided name (full
                        or partial)
  --user <user>         Only delete playbooks that were executed by the
                        specified user (full or partial)
  --ansible_version <ansible_version>
                        Only delete playbooks that ran with the specified
                        Ansible version (full or partial)
  --client_version <client_version>
                        Only delete playbooks that were recorded with the
                        specified ara client version (full or partial)
  --server_version <server_version>
                        Only delete playbooks that were recorded with the
                        specified ara server version (full or partial)
  --python_version <python_version>
                        Only delete playbooks that were recorded with the
                        specified python version (full or partial)
  --controller <controller>
                        Only delete playbooks that ran from the provided
                        controller (full or partial)
  --path <path>         Only delete only playbooks matching the provided path
                        (full or partial)
  --status <status>     Only delete playbooks matching a specific status
                        ('completed', 'running', 'failed')
  --order <order>       Orders playbooks by a field ('id', 'created',
                        'updated', 'started', 'ended', 'duration')
                        Defaults to 'started' descending so the oldest
                        playbook would be deleted first.
                        The order can be reversed by using '-': ara playbook
                        list --order=-started
  --limit <limit>       Only delete the first <limit> determined by the
                        ordering. Defaults to ARA_CLI_LIMIT or 200.
  --confirm             Confirm deletion of playbooks, otherwise runs without
                        deleting any playbook

Examples:

# Return which playbooks would be deleted by ommitting --confirm
ara playbook prune

# Different retention for completed, failed and expired playbooks
ara playbook prune --status completed --days 30 --confirm
ara playbook prune --status failed --days 90 --confirm
ara playbook prune --status expired --days 3 --confirm

# Different retention based on labels
ara playbook prune --label dev --days 7 --confirm
ara playbook prune --label prod --days 90 --confirm

# Different retention based on name or path
ara playbook prune --name demo --days 7
ara playbook prune --path /home/jenkins --days 14

# Delete more than 200 playbooks per command execution
ara playbook prune --limit 9000 --confirm

ara play list

$ ara play list --help
usage: ara play list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                     [--quote {all,minimal,none,nonnumeric}] [--noindent]
                     [--max-width <integer>] [--fit-width] [--print-empty]
                     [--sort-column SORT_COLUMN]
                     [--sort-ascending | --sort-descending]
                     [--client <client>] [--server <url>]
                     [--timeout <seconds>] [--username <username>]
                     [--password <password>]
                     [--ssl-cert <path/to/certificate>]
                     [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                     [--insecure] [--playbook <playbook_id>] [--name <name>]
                     [--uuid <uuid>] [--status <status>] [--long] [--resolve]
                     [--order <order>] [--limit <limit>]

Returns a list of plays based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List plays for the specified playbook
  --name <name>         List plays matching the provided name (full or
                        partial)
  --uuid <uuid>         List plays matching the provided uuid (full or
                        partial)
  --status <status>     List plays matching a specific status ('completed',
                        'running', 'failed')
  --long                Don't truncate paths
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders plays by a field ('id', 'created', 'updated',
                        'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        playbook is at the top.
                        The order can be reversed by omitting the '-': ara
                        play list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# List the top 25 longest plays
ara play list --order=-duration --limit 25

# List plays matching a name (full or partial)
ara play list --name apache

# List the plays for a specific playbook and format the result in json
ara play list --playbook 1 -f json

ara play show

$ ara play show --help
usage: ara play show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                     [--noindent] [--prefix PREFIX] [--max-width <integer>]
                     [--fit-width] [--print-empty] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--ssl-cert <path/to/certificate>]
                     [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                     [--insecure]
                     <play-id>

Returns a detailed view of a specified play

positional arguments:
  <play-id>             Play to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# Show a specific play and format the results as json
ara play show 9001 -f json

ara play delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara play delete --help
usage: ara play delete [-h] [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>]
                       [--ssl-cert <path/to/certificate>]
                       [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                       [--insecure]
                       <play-id>

Deletes the specified play and associated resources

positional arguments:
  <play-id>             Play to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara host list

$ ara host list --help
usage: ara host list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                     [--quote {all,minimal,none,nonnumeric}] [--noindent]
                     [--max-width <integer>] [--fit-width] [--print-empty]
                     [--sort-column SORT_COLUMN]
                     [--sort-ascending | --sort-descending]
                     [--client <client>] [--server <url>]
                     [--timeout <seconds>] [--username <username>]
                     [--password <password>]
                     [--ssl-cert <path/to/certificate>]
                     [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                     [--insecure] [--name <name>] [--playbook <playbook_id>]
                     [--latest] [--with-changed | --without-changed]
                     [--with-failed | --without-failed]
                     [--with-unreachable | --without-unreachable] [--resolve]
                     [--long] [--order <order>] [--limit <limit>]

Returns a list of hosts based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --name <name>         List hosts matching the provided name (full or
                        partial)
  --playbook <playbook_id>
                        List hosts for a specified playbook id
  --latest              Return only the latest playbook report for each host
  --with-changed        Return hosts with changed results
  --without-changed     Don't return hosts with changed results
  --with-failed         Return hosts with failed results
  --without-failed      Don't return hosts with failed results
  --with-unreachable    Return hosts with unreachable results
  --without-unreachable
                        Don't return hosts with unreachable results
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --long                Don't truncate paths
  --order <order>       Orders hosts by a field ('id', 'created', 'updated',
                        'name')
                        Defaults to '-updated' descending so the most recent
                        host is at the top.
                        The order can be reversed by omitting the '-': ara
                        host list --order=updated
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Note

From the perspective of ARA, each host is unique to a playbook run. Their records contain the Ansible host facts as well as their stats for a particular playbook run.

Examples:

# List the last 25 host reports
ara host list --limit 25

# List only the latest playbook report for each host
ara host list --latest

# List host records for a specific host name
ara host list --name localhost

# List all the host results for a specific playbook and format the result in json
ara host list --playbook 1 -f json

# Only return hosts with or without unreachable task results
ara host list --with-unreachable
ara host list --without-unreachable

# Only return hosts with or without changed task results
ara host list --with-changed
ara host list --without-changed

# Only return hosts with or without failed task results
ara host list --with-failed
ara host list --without-failed

ara host show

$ ara host show --help
usage: ara host show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                     [--noindent] [--prefix PREFIX] [--max-width <integer>]
                     [--fit-width] [--print-empty] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--ssl-cert <path/to/certificate>]
                     [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                     [--insecure] [--with-facts]
                     <host-id>

Returns a detailed view of a specified host

positional arguments:
  <host-id>             Host to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --with-facts          Also include host facts in the response (use with '-f
                        json' or '-f yaml')

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Note

From the perspective of ARA, each host is unique to a playbook run. Their records contain the Ansible host facts as well as their stats for a particular playbook run.

Return stats for a specified host as well as a link to the playbook report it is involved in:

ara host show 1

Include host facts as well formatted in json:

# Facts do not render well in the default pretty table format
ara host show 1 --with-facts -f json

ara host delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara host delete --help
usage: ara host delete [-h] [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>]
                       [--ssl-cert <path/to/certificate>]
                       [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                       [--insecure]
                       <host-id>

Deletes the specified host and associated resources

positional arguments:
  <host-id>             Host to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara host metrics

$ ara host metrics --help
usage: ara host metrics [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                        [--quote {all,minimal,none,nonnumeric}] [--noindent]
                        [--max-width <integer>] [--fit-width] [--print-empty]
                        [--sort-column SORT_COLUMN]
                        [--sort-ascending | --sort-descending]
                        [--client <client>] [--server <url>]
                        [--timeout <seconds>] [--username <username>]
                        [--password <password>]
                        [--ssl-cert <path/to/certificate>]
                        [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                        [--insecure] [--name <name>]
                        [--playbook <playbook_id>]
                        [--with-changed | --without-changed]
                        [--with-failed | --without-failed]
                        [--with-unreachable | --without-unreachable]
                        [--order <order>] [--limit <limit>]

Provides metrics about hosts

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --name <name>         Filter for hosts matching the provided name (full or
                        partial)
  --playbook <playbook_id>
                        Filter for hosts for a specified playbook id
  --with-changed        Filter for hosts with changed results
  --without-changed     Filter out hosts without changed results
  --with-failed         Filter for hosts with failed results
  --without-failed      Filter out hosts without failed results
  --with-unreachable    Filter for hosts with unreachable results
  --without-unreachable
                        Filter out hosts without unreachable results
  --order <order>       Orders hosts by a field ('id', 'created', 'updated',
                        'name')
                        Defaults to '-updated' descending so the most recent
                        host is at the top.
                        The order can be reversed by omitting the '-': ara
                        host list --order=updated
                        This influences the API request, not the ordering of
                        the metrics.
  --limit <limit>       Return metrics for the first <limit> determined by the
                        ordering. Defaults to ARA_CLI_LIMIT or 1000.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# Return metrics about more than the last 1000 hosts
ara host metrics --limit 10000

# Return host metrics in json or csv
ara host metrics -f json
ara host metrics -f csv

# Return metrics for hosts matching a name
ara host metrics --name localhost

# Return metrics for hosts involved in a specific playbook
ara host metrics --playbook 9001

# Return metrics only for hosts with changed, failed or unreachable results
ara host metrics --with-changed
ara host metrics --with-failed
ara host metrics --with-unreachable

# Return metrics only for hosts without changed, failed or unreachable results
ara host metrics --without-changed
ara host metrics --without-failed
ara host metrics --without-unreachable

ara record list

$ ara record list --help
usage: ara record list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                       [--quote {all,minimal,none,nonnumeric}] [--noindent]
                       [--max-width <integer>] [--fit-width] [--print-empty]
                       [--sort-column SORT_COLUMN]
                       [--sort-ascending | --sort-descending]
                       [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>]
                       [--ssl-cert <path/to/certificate>]
                       [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                       [--insecure] [--playbook <playbook_id>] [--key <key>]
                       [--long] [--resolve] [--order <order>]
                       [--limit <limit>]

Returns a list of records based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List records for the specified playbook
  --key <key>           List records matching the specified key
  --long                Don't truncate paths
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders records by a field ('id', 'created', 'updated',
                        'key')
                        Defaults to '-updated' descending so the most recent
                        record is at the top.
                        The order can be reversed by omitting the '-': ara
                        record list --order=updated
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# List records for a specific key
ara record list --key log_url

# List records for a specific playbook
ara record list --playbook 9001

ara record show

$ ara record show --help
usage: ara record show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                       [--noindent] [--prefix PREFIX] [--max-width <integer>]
                       [--fit-width] [--print-empty] [--client <client>]
                       [--server <url>] [--timeout <seconds>]
                       [--username <username>] [--password <password>]
                       [--ssl-cert <path/to/certificate>]
                       [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                       [--insecure]
                       <record-id>

Returns a detailed view of a specified record

positional arguments:
  <record-id>           Record to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# Show a specific record and format the results as json
ara record show 9001 -f json

ara record delete

$ ara record delete --help
usage: ara record delete [-h] [--client <client>] [--server <url>]
                         [--timeout <seconds>] [--username <username>]
                         [--password <password>]
                         [--ssl-cert <path/to/certificate>]
                         [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                         [--insecure]
                         <record-id>

Deletes the specified record and associated resources

positional arguments:
  <record-id>           Record to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara result list

$ ara result list --help
usage: ara result list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                       [--quote {all,minimal,none,nonnumeric}] [--noindent]
                       [--max-width <integer>] [--fit-width] [--print-empty]
                       [--sort-column SORT_COLUMN]
                       [--sort-ascending | --sort-descending]
                       [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>]
                       [--ssl-cert <path/to/certificate>]
                       [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                       [--insecure] [--playbook <playbook_id>]
                       [--play <play_id>] [--task <task_id>]
                       [--host <host_id>] [--status <status>]
                       [--ignore-errors] [--changed] [--long] [--resolve]
                       [--order <order>] [--limit <limit>]

Returns a list of results based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List results for the specified playbook
  --play <play_id>      List results for the specified play
  --task <task_id>      List results for the specified task
  --host <host_id>      List results for the specified host
  --status <status>     List results matching a specific status:
                        ok, failed, skipped, unreachable, changed, ignored,
                        unknown
  --ignore-errors       Return only results with 'ignore_errors: true',
                        defaults to false
  --changed             Return only changed results, defaults to false
  --long                Don't truncate paths and include additional fields:
                        changed, ignore_errors, play
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders results by a field ('id', 'started', 'updated',
                        'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        result is at the top.
                        The order can be reversed by omitting the '-': ara
                        result list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Return the 10 most recent failed results:

ara result list --status failed --limit 10

Return the 15 results with the highest duration for a specific playbook:

ara result list --playbook 389 --order=-duration --limit 15

ara result show

$ ara result show --help
usage: ara result show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                       [--noindent] [--prefix PREFIX] [--max-width <integer>]
                       [--fit-width] [--print-empty] [--client <client>]
                       [--server <url>] [--timeout <seconds>]
                       [--username <username>] [--password <password>]
                       [--ssl-cert <path/to/certificate>]
                       [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                       [--insecure] [--with-content]
                       <result-id>

Returns a detailed view of a specified result

positional arguments:
  <result-id>           Result to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --with-content        Also include the result content in the response (use
                        with '-f json' or '-f yaml')

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Return detailed information about a specific result:

ara result show 9001

Return detailed information about a specific result, including formatted content:

ara result show 9001 --with-content -f json

ara result delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara result delete --help
usage: ara result delete [-h] [--client <client>] [--server <url>]
                         [--timeout <seconds>] [--username <username>]
                         [--password <password>]
                         [--ssl-cert <path/to/certificate>]
                         [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                         [--insecure]
                         <result-id>

Deletes the specified result and associated resources

positional arguments:
  <result-id>           Result to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara task list

$ ara task list --help
usage: ara task list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                     [--quote {all,minimal,none,nonnumeric}] [--noindent]
                     [--max-width <integer>] [--fit-width] [--print-empty]
                     [--sort-column SORT_COLUMN]
                     [--sort-ascending | --sort-descending]
                     [--client <client>] [--server <url>]
                     [--timeout <seconds>] [--username <username>]
                     [--password <password>]
                     [--ssl-cert <path/to/certificate>]
                     [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                     [--insecure] [--playbook <playbook_id>]
                     [--status <status>] [--name <name>] [--uuid <uuid>]
                     [--path <path>] [--action <action>] [--long] [--resolve]
                     [--order <order>] [--limit <limit>]

Returns a list of tasks based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List tasks for a specified playbook id
  --status <status>     List tasks matching a specific status ('completed',
                        'expired', 'failed', 'running' or 'unknown')
  --name <name>         List tasks matching the provided name (full or
                        partial)
  --uuid <uuid>         List tasks matching the provided uuid (full or
                        partial)
  --path <path>         List tasks matching the provided path (full or
                        partial)
  --action <action>     List tasks matching a specific action/ansible module
                        (ex: 'debug', 'package', 'set_fact')
  --long                Don't truncate paths and include additional fields:
                        path, lineno, handler, play
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders tasks by a field ('id', 'created', 'updated',
                        'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        task is at the top.
                        The order can be reversed by omitting the '-': ara
                        task list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Note

ara doesn’t have the concept of roles but it is possible to search for them by path, for example: ara task list --path "roles/install_apache"

Role names are included in the task names and it is possible to search for role-specific tasks there as well: ara task list --name install_apache.

Examples:

# Return the top 25 longest running tasks
ara task list --order=-duration --limit 25

# Return tasks from a specific playbook
ara task list --playbook 9001

# Return tasks for the package action
ara task list --action package

# Return tasks matching a path (partial or full)
ara task list --path="roles/install_apache"

# Return tasks matching a name (partial or full)
ara task list --name install_apache

ara task show

$ ara task show --help
usage: ara task show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                     [--noindent] [--prefix PREFIX] [--max-width <integer>]
                     [--fit-width] [--print-empty] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--ssl-cert <path/to/certificate>]
                     [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                     [--insecure]
                     <task-id>

Returns a detailed view of a specified task

positional arguments:
  <task-id>             Task to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Return detailed information about a specific task:

ara task show 9001

ara task delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara task delete --help
usage: ara task delete [-h] [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>]
                       [--ssl-cert <path/to/certificate>]
                       [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                       [--insecure]
                       <task-id>

Deletes the specified task and associated resources

positional arguments:
  <task-id>             Task to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara task metrics

$ ara task metrics --help
usage: ara task metrics [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                        [--quote {all,minimal,none,nonnumeric}] [--noindent]
                        [--max-width <integer>] [--fit-width] [--print-empty]
                        [--sort-column SORT_COLUMN]
                        [--sort-ascending | --sort-descending]
                        [--client <client>] [--server <url>]
                        [--timeout <seconds>] [--username <username>]
                        [--password <password>]
                        [--ssl-cert <path/to/certificate>]
                        [--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
                        [--insecure] [--aggregate {action,name,path}]
                        [--playbook <playbook_id>] [--status <status>]
                        [--name <name>] [--uuid <name>] [--path <path>]
                        [--action <action>] [--long] [--order <order>]
                        [--limit <limit>]

Provides metrics about actions in tasks

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --ssl-cert <path/to/certificate>
                        If a client certificate is required, the path to the
                        certificate to use, defaults to ARA_API_CERT or None
  --ssl-key <path/to/key>
                        If a client certificate is required, the path to the
                        private key to use, defaults to ARA_API_KEY or None
  --ssl-ca <path/to/cacert>
                        Path to a certificate authority for trusting the API
                        server certificate, defaults to ARA_API_CA or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --aggregate {action,name,path}
                        Aggregate tasks by action, name or path. Defaults to
                        action.
  --playbook <playbook_id>
                        Filter for tasks for a specified playbook id
  --status <status>     Filter for tasks matching a specific status
                        ('completed', 'expired', 'failed', 'running', or
                        'unknown')
  --name <name>         Filter for tasks matching the provided name (full or
                        partial)
  --uuid <name>         Filter for tasks matching the provided uuid (full or
                        partial)
  --path <path>         Filter for tasks matching the provided path (full or
                        partial)
  --action <action>     Filter for tasks matching a specific action/ansible
                        module (ex: 'debug', 'package', 'set_fact')
  --long                Don't truncate paths and include additional status
                        fields: completed, expired, failed, running & unknown
  --order <order>       Orders tasks by a field ('id', 'created', 'updated',
                        'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        task is at the top.
                        The order can be reversed by omitting the '-': ara
                        task metrics --order=started
                        This influences the API request, not the ordering of
                        the metrics.
  --limit <limit>       Return metrics for the first <limit> determined by the
                        ordering. Defaults to ARA_CLI_LIMIT or 1000.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated
  --sort-ascending      sort the column(s) in ascending order
  --sort-descending     sort the column(s) in descending order

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# Return metrics about more than the last 1000 tasks
ara task metrics --limit 10000

# Return task metrics in json or csv
ara task metrics -f json
ara task metrics -f csv

# Don't truncate paths and include additional task status fields
ara task metrics --long

# Return metrics about tasks from a specific playbook
ara task metrics --playbook 9001

# Return metrics for tasks matching a (full or partial) path
ara task metrics --path ansible-role-foo

# Only return metrics about a specific action
ara task metrics --action package

# Return metrics for tasks matching a name
ara task metrics --name apache

# Return metrics about the longest tasks and then sort them by total duration
ara task metrics --order=-duration --sort-column duration_total

# Aggregate metrics by task name rather than action
ara task metrics --aggregate name

# Aggregate metrics by task file rather than action
ara task metrics --aggregate path

CLI: ara-manage (django API server)

ara-manage is a command provided by ARA when the API server dependencies are installed.

It is an alias to the python manage.py command interface provided by Django and they can be used interchangeably if you are running ARA from source.

Note

Django comes with a lot of built-in commands and they are not all used or relevant in the context of ARA so they might not be exposed, tested or documented.

This documentation provides information about commands which we think are relevant.

If you do not find a command documented here, you can find more information about it in the Django documentation.

Please feel free to send a patch if we’re missing anything !

ara-manage

$ ara-manage --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml

Type 'ara-manage help <subcommand>' for help on a specific subcommand.

Available subcommands:

[api]
    prune

[auth]
    changepassword
    createsuperuser

[contenttypes]
    remove_stale_contenttypes

[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    inspectdb
    loaddata
    makemessages
    makemigrations
    migrate
    sendtestemail
    shell
    showmigrations
    sqlflush
    sqlmigrate
    sqlsequencereset
    squashmigrations
    startapp
    startproject
    test
    testserver

[health_check]
    health_check

[rest_framework]
    generateschema

[sessions]
    clearsessions

[staticfiles]
    collectstatic
    findstatic
    runserver

[ui]
    generate

ara-manage prune

Warning

ara-manage prune has been replaced by ara playbook prune in ara 1.5. It will be removed in ara 1.6.

Used to delete playbooks that are older than a specified amount of days.

$ ara-manage prune --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage prune [-h] [--client CLIENT] [--endpoint ENDPOINT]
                        [--username USERNAME] [--password PASSWORD]
                        [--insecure] [--timeout TIMEOUT] [--days DAYS]
                        [--confirm] [--version] [-v {0,1,2,3}]
                        [--settings SETTINGS] [--pythonpath PYTHONPATH]
                        [--traceback] [--no-color] [--force-color]
                        [--skip-checks]

Deletes playbooks from the database based on their age

optional arguments:
  -h, --help            show this help message and exit
  --client CLIENT       API client to use for the query: 'offline' or 'http'
                        (default: 'offline')
  --endpoint ENDPOINT   API endpoint to use for the query (default:
                        'http://127.0.0.1:8000')
  --username USERNAME   API username to use for the query (default: None)
  --password PASSWORD   API password to use for the query (default: None)
  --insecure            Disables SSL certificate validation
  --timeout TIMEOUT     Timeout for API queries (default: 10)
  --days DAYS           Delete playbooks started this many days ago (default:
                        31)
  --confirm             Confirm deletion of playbooks, otherwise runs without
                        deleting any playbook
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

ara-manage changepassword

Change the password for a user.

Relevant when working with authentication.

$ ara-manage changepassword --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage changepassword [-h] [--database DATABASE] [--version]
                                 [-v {0,1,2,3}] [--settings SETTINGS]
                                 [--pythonpath PYTHONPATH] [--traceback]
                                 [--no-color] [--force-color]
                                 [username]

Change a user's password for django.contrib.auth.

positional arguments:
  username              Username to change password for; by default, it's the
                        current username.

optional arguments:
  -h, --help            show this help message and exit
  --database DATABASE   Specifies the database to use. Default is "default".
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage createsuperuser

Superusers are relevant when setting up authentication.

$ ara-manage createsuperuser --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage createsuperuser [-h] [--username USERNAME] [--noinput]
                                  [--database DATABASE] [--email EMAIL]
                                  [--version] [-v {0,1,2,3}]
                                  [--settings SETTINGS]
                                  [--pythonpath PYTHONPATH] [--traceback]
                                  [--no-color] [--force-color] [--skip-checks]

Used to create a superuser.

optional arguments:
  -h, --help            show this help message and exit
  --username USERNAME   Specifies the login for the superuser.
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind. You must use --username with --noinput, along
                        with an option for any other required field.
                        Superusers created with --noinput will not be able to
                        log in until they're given a valid password.
  --database DATABASE   Specifies the database to use. Default is "default".
  --email EMAIL         Specifies the email for the superuser.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

ara-manage makemigrations

Generally used to generate new SQL migrations after modifying the database model files.

$ ara-manage makemigrations --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage makemigrations [-h] [--dry-run] [--merge] [--empty]
                                 [--noinput] [-n NAME] [--no-header] [--check]
                                 [--version] [-v {0,1,2,3}]
                                 [--settings SETTINGS]
                                 [--pythonpath PYTHONPATH] [--traceback]
                                 [--no-color] [--force-color] [--skip-checks]
                                 [app_label [app_label ...]]

Creates new migration(s) for apps.

positional arguments:
  app_label             Specify the app label(s) to create migrations for.

optional arguments:
  -h, --help            show this help message and exit
  --dry-run             Just show what migrations would be made; don't
                        actually write them.
  --merge               Enable fixing of migration conflicts.
  --empty               Create an empty migration.
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind.
  -n NAME, --name NAME  Use this name for migration file(s).
  --no-header           Do not add header comments to new migration file(s).
  --check               Exit with a non-zero status if model changes are
                        missing migrations.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

ara-manage migrate

Runs SQL migrations.

They need to be run at least once before the API server can start.

$ ara-manage migrate --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage migrate [-h] [--noinput] [--database DATABASE] [--fake]
                          [--fake-initial] [--plan] [--run-syncdb] [--check]
                          [--version] [-v {0,1,2,3}] [--settings SETTINGS]
                          [--pythonpath PYTHONPATH] [--traceback] [--no-color]
                          [--force-color] [--skip-checks]
                          [app_label] [migration_name]

Updates database schema. Manages both apps with migrations and those without.

positional arguments:
  app_label             App label of an application to synchronize the state.
  migration_name        Database state will be brought to the state after that
                        migration. Use the name "zero" to unapply all
                        migrations.

optional arguments:
  -h, --help            show this help message and exit
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind.
  --database DATABASE   Nominates a database to synchronize. Defaults to the
                        "default" database.
  --fake                Mark migrations as run without actually running them.
  --fake-initial        Detect if tables already exist and fake-apply initial
                        migrations if so. Make sure that the current database
                        schema matches your initial migration before using
                        this flag. Django will only check for an existing
                        table name.
  --plan                Shows a list of the migration actions that will be
                        performed.
  --run-syncdb          Creates tables for apps without migrations.
  --check               Exits with a non-zero status if unapplied migrations
                        exist.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

ara-manage runserver

Runs the embedded development server.

Note

Good for small scale usage.

Consider deploying with a WSGI application server and a web server for production use.

$ ara-manage runserver --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage runserver [-h] [--ipv6] [--nothreading] [--noreload]
                            [--nostatic] [--insecure] [--version]
                            [-v {0,1,2,3}] [--settings SETTINGS]
                            [--pythonpath PYTHONPATH] [--traceback]
                            [--no-color] [--force-color]
                            [addrport]

Starts a lightweight Web server for development and also serves static files.

positional arguments:
  addrport              Optional port number, or ipaddr:port

optional arguments:
  -h, --help            show this help message and exit
  --ipv6, -6            Tells Django to use an IPv6 address.
  --nothreading         Tells Django to NOT use threading.
  --noreload            Tells Django to NOT use the auto-reloader.
  --nostatic            Tells Django to NOT automatically serve static files
                        at STATIC_URL.
  --insecure            Allows serving static files even if DEBUG is False.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage generate

Generates a static version of the built-in reporting web interface.

Note

Good for small scale usage but inefficient and contains a lot of small files at a large scale.

$ ara-manage generate --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage generate [-h] [--version] [-v {0,1,2,3}]
                           [--settings SETTINGS] [--pythonpath PYTHONPATH]
                           [--traceback] [--no-color] [--force-color]
                           [--skip-checks]
                           path

Generates a static tree of the web application

positional arguments:
  path                  Path where the static files will be built in

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

Contributing to ARA

ARA Records Ansible is a free and open source community project that welcomes and appreciates contributions.

While this page focuses around development of the project itself, contributions aren’t only about pull requests, code or code reviews.

They can be in the form of documentation, feedback and comments, suggestions and ideas, issues and bug reports, or just helping out other users in the chat rooms.

Code contributions

Pull requests welcome

The ara repository is hosted on GitHub and every pull request is automatically tested with linters, unit tests as well as a variety of integration test scenarios.

This results in higher standards, better code, improved testing coverage, less regressions and increased stability.

There are many tutorials on how to create a pull request on GitHub but the process generally looks like the following:

• Fork the ara repository on GitHub
• Run git clone on your fork
• Create a new branch: git checkout -b cool_feature
• Do your changes and test or preview them locally, as appropriate
• Commit your changes with git commit
• Push your commit to your fork with git push origin cool_feature
• Open a pull request using the proposed link returned by the git push command

Testing changes locally

You are encouraged to test your changes in a local environment before sending them for review.

Most of the tests that are run against a pull request are fast and can be run from your development environment without any changes to the system.

Tox handles the creation of a python virtual environment in which the tests are run from and must be installed:

• tox -e py3 for unit tests
• tox -e linters for pep8/flake8/bandit/bashate/black/isort/etc
• tox -e docs for testing and building documentation to docs/build/html
• tox -e ansible-integration installs ansible and runs integration tests

Changes to the server, API, Ansible plugins or web interface can generally be manually tested and previewed from within a tox virtual environment like this:

tox -e ansible-integration --notest
source .tox/ansible-integration/bin/activate
export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins)
export ANSIBLE_ACTION_PLUGINS=$(python3 -m ara.setup.action_plugins)
export ANSIBLE_LOOKUP_PLUGINS=$(python3 -m ara.setup.lookup_plugins)
ansible-playbook tests/integration/smoke.yaml
ara-manage runserver
# Browse to http://127.0.0.1:8000

FAQ

Where is the source code ?

ARA is currently composed of three different free and open source projects:

• https://github.com/ansible-community/ara for the REST API server and Ansible plugins
• https://github.com/ansible-community/ara-web for the standalone web interface
• https://github.com/ansible-community/ara-infra for project-specific infrastructure needs (such as the ara.recordsansible.org website)

What’s an Ansible callback ?

Ansible Callbacks are essentially hooks provided by Ansible. Ansible will send an event and you can react to it with a callback. You could use a callback to do things like print additional details or, in the case of ARA, record the playbook run data in a database.

What versions of Ansible are supported ?

The upstream Ansible community and maintainers provide support for the latest three major stable releases and ARA follows the same support cycle.

For example, if the latest version of Ansible is 2.9, then the latest release of ARA will support 2.9 as well as 2.8 and 2.7.

For more information on Ansible’s release and maintenance cycle, you can refer to the Ansible documentation.

If you are using a release of Ansible that is no longer supported, it doesn’t mean that ARA won’t work but it will no longer be tested. We strongly encourage you to upgrade as soon as possible in order to benefit from the latest features and security fixes not just in ARA but in Ansible as well.

Older unsupported versions of Ansible can contain unfixed security vulnerabilities (CVE).

Why ARA instead of <X> ?

Ansible is an awesome tool. It can be used for a lot of things.

Reading and interpreting the output of an ansible-playbook run, especially one that is either long running, involves a lot of hosts or prints a lot of output can be hard to understand and troubleshoot.

This is especially true when you happen to be running Ansible hundreds of times during the day, through automated means – for example when doing continuous integration or continuous delivery.

ARA aims to do one thing and do it well: Record Ansible playbooks and provide you with the tools you need to make your playbook results intuitive for you and for your systems.

The great thing about ARA is that it is not mutually exclusive with other software and systems you might already be using Ansible with today.

There is nothing preventing you from using ARA with other tools such as Ansible Tower (or AWX), Zuul, Jenkins or Rundeck since all you need to get started is to install and enable the ARA Ansible callback plugin.

Can I set up the different components of ARA on different servers ?

Yes.

The defaults are set to have the callback use the offline API client which expects the server dependencies installed and the data is saved to a local sqlite database.

However, the callback can also be configured to send data to a specified API server address and the API server can be configured to use a remote database server such as PostgreSQL or MySQL.

The web client interface provided by ara-web is stateless and requires an API server address to connect to. It can be installed anywhere that has access to the API server.

Troubleshooting

This page documents issues that are commonly encountered and provides advice on how to troubleshoot them.

Increasing verbosity and obtaining debug logging

When there is an exception, an error or something doesn’t work, it is likely that increasing verbosity or looking at the debug logs can point us in the right direction.

The ansible and ansible-playbook commands do not run with enough verbosity by default to display tracebacks from Ansible plugins.

In order to retrieve the tracebacks, run these commands with increased verbosity (-vvv):

> ansible-playbook playbook.yml
# ...
TASK [Gathering Facts] *****************************************************
[WARNING]: Failure using method (v2_playbook_on_task_start) in callback plugin (<ansible.plugins.callback.ara_default.CallbackModule object at 0x7f6d4abcfe50>):
# ...

> ansible-playbook -vvv playbook.yml
# ...
TASK [Gathering Facts] *****************************************************
[WARNING]: Failure using method (v2_playbook_on_task_start) in callback plugin (<ansible.plugins.callback.ara_default.CallbackModule object at 0x7f1e7fd5ce50>):
Callback Exception:
  File "/usr/lib/python3.9/site-packages/ansible/executor/task_queue_manager.py", line 389, in send_callback
    method(*new_args, **kwargs)
  File "/usr/lib/python3.9/site-packages/ara/plugins/callback/ara_default.py", line 354, in v2_playbook_on_task_start
    raise Exception
# ...

Additional debug logging from ara’s perspective can be added by setting ARA_DEBUG to true and ARA_LOG_LEVEL to DEBUG:

> export ARA_DEBUG=true
> export ARA_LOG_LEVEL=DEBUG
> export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins)
> ansible-playbook tests/integration/hosts.yaml

[WARNING]: No inventory was parsed, only implicit localhost is available
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
Operations to perform:
Apply all migrations: admin, api, auth, contenttypes, db, sessions
Running migrations:
No migrations to apply.
2021-04-20 09:56:14,678 DEBUG ara.plugins.callback.default: v2_playbook_on_start
2021-04-20 09:56:14,679 DEBUG ara.plugins.callback.default: Ignoring argument: extra_vars
2021-04-20 09:56:14,680 DEBUG urllib3.connectionpool: Starting new HTTP connection (1): localhost:35697
2021-04-20 09:56:14,708 DEBUG urllib3.connectionpool: http://localhost:35697 "POST /api/v1/playbooks HTTP/1.1" 201 1116
2021-04-20 09:56:14,708 DEBUG ara.clients.http: HTTP 201: post on /api/v1/playbooks
2021-04-20 09:56:14,708 DEBUG ara.plugins.callback.default: File not in cache, getting or creating: /home/dmsimard/dev/git/ansible-community/ara/tests/integration/hosts.yaml
2021-04-20 09:56:14,723 DEBUG urllib3.connectionpool: http://localhost:35697 "POST /api/v1/files HTTP/1.1" 201 1784
2021-04-20 09:56:14,724 DEBUG ara.clients.http: HTTP 201: post on /api/v1/files

PLAY [Create fake hosts for host tests] ****************************************************************************************************************************************************************************************************************************************************
2021-04-20 09:56:14,726 DEBUG ara.plugins.callback.default: v2_playbook_on_play_start
2021-04-20 09:56:14,726 DEBUG ara.plugins.callback.default: Updating playbook labels to match: check:False,tags:all
2021-04-20 09:56:14,750 DEBUG urllib3.connectionpool: http://localhost:35697 "PATCH /api/v1/playbooks/13 HTTP/1.1" 200 1172
2021-04-20 09:56:14,751 DEBUG ara.clients.http: HTTP 200: patch on /api/v1/playbooks/13
2021-04-20 09:56:14,806 DEBUG urllib3.connectionpool: http://localhost:35697 "POST /api/v1/plays HTTP/1.1" 201 294
2021-04-20 09:56:14,807 DEBUG ara.clients.http: HTTP 201: post on /api/v1/plays

# [...]

Playbooks are not recorded

If it is expected that playbooks should be recorded but they are not, there are a few things to double check:

1. Are both ara and ansible installed and running under python >=3.5 ?
2. Are the ara and ansible packages installed for the same python interpreter ? Mixing packages from distributions (such as rpm or deb) and PyPi tends to be problematic.
3. Is the ara callback enabled ? This can be done with export ANSIBLE_CALLBACK_PLUGINS=$(python3 -m ara.setup.callback_plugins) prior to running playbooks.
4. By default, playbooks are saved in a sqlite database at ~/.ara/server/ansible.sqlite. Are playbooks running under a different user or location than the server ?

Database exceptions

By default, ara’s Ansible callback plugin takes care of creating a sqlite database and runs SQL migrations automatically.

Attempting to start the server process or run CLI commands (such as ara playbook list) before running these SQL migrations can result in exceptions such as:

> ara playbook list
2021-04-15 20:01:23,224 ERROR django.request: Internal Server Error: /api/v1/playbooks
Traceback (most recent call last):
File "/usr/local/lib/python3.6/site-packages/django/db/backends/utils.py", line 84, in _execute
    return self.cursor.execute(sql, params)
File "/usr/local/lib/python3.6/site-packages/django/db/backends/sqlite3/base.py", line 383, in execute
    return Database.Cursor.execute(self, query, params)
sqlite3.OperationalError: no such table: playbooks

SQL migrations can be run manually by executing ara-manage migrate.

For MySQL and PostgreSQL, the database must have already been created before attempting to run migrations.

Bad Request (400) and ALLOWED_HOSTS

Attempting to browse the API server or it’s built-in reporting UI can result in a HTTP 400 (Bad Request) error if the hostname is not included in the ARA_ALLOWED_HOSTS of ~/.ara/server/settings.yaml.

This error in also manifested in the server’s logs as such:

2021-04-20 10:32:45,219 ERROR django.security.DisallowedHost: Invalid HTTP_HOST header: 'ara.example.org:8000'. You may need to add 'ara.example.org' to ALLOWED_HOSTS.
2021-04-20 10:32:45,250 WARNING django.request: Bad Request: /

Adding the hostname to your settings.yaml configuration file and restarting the server should resolve the issue.

Improving playbook recording performance

Recording playbooks with ara introduces a performance overhead because instead of just printing to the console there’s now an additional Ansible callback plugin, an API server and a database involved:

In no particular order, here’s high-level advice that have proven to be useful in order to minimize the overhead and improve performance:

• The built-in Django development server provided by the default offline API client and ara-manage runserver is simple and convenient but it isn’t meant to provide the best scalability and performance
• The API server should be run as a service with a WSGI application server like gunicorn, uwsgi or mod_wsgi with apache2/httpd
• There should be a frontend, reverse-proxy or load balancer such as apache, nginx, haproxy or traefik in front of the API server in order to handle TLS termination, caching and authentication
• When enabling authentication, consider using EXTERNAL_AUTH instead of the Django built-in user management to avoid a database lookup performance hit on every query
• While SQLite is good and fast enough at a small scale, it has been reported to run into concurrency and locking issues that can make MySQL or PostgreSQL a better option at a larger scale
• When using MySQL or PostgreSQL, performance can be significantly improved by enabling callback multi-threading by setting ARA_API_CLIENT=http and ARA_CALLBACK_THREADS=4
• When using MySQL or PostgreSQL, set ARA_DATABASE_CONN_MAX_AGE to a value >= 60 to allow database connections to be re-used until the specified timeout, avoiding the overhead of closing and opening connections for every query
• The latency between the Ansible control node, the API server and the database server should be kept as small as possible because it adds up multiplicatively (tasks * hosts) over the course of a playbook
• While not specific to ara, consider tuning Ansible’s SSH pipelining, forks and other parameters to yield significant performance improvements

Changelog and release notes

1.7.0 (2023-09-10)

https://github.com/ansible-community/ara/releases/tag/1.7.0

This is the 1.7.0 stable release of ara.

It features a refresh of the built-in web interface with the upgrade
from bootstrap 4.6.0 to 5.3.0.

It lifts the supported version of django up to the latest LTS, 4.2, and
raises the minimum version of python to >=3.8 as a result.

There's also bug fixes and new features.

Changes since 1.6.1:

UI
--
Boostrap and CSS:

- Update bootstrap CSS from 4.6.0 to 5.3.0 and fix broken layout and
  components as a result of the update
- Removed separate light/dark themes via bootstrap-darkly and
  bootstrap-flatly: bootstrap 5.3 features a new built-in dark theme
- Re-worked the dark/light theme selection to match the new bootstrap
  built-in dark theme including pygments highlighting for pretty-printed
  output
- Removed jquery, it is no longer required with bootstrap
- Re-worked implementation of file line highlighting since it relied on
  jquery
- Fixed tooltip implementation (i.e, for task tags) since the
  implementation in bootstrap had changed

Site-wide minor cleanups and improvements:

- Headers and font size made generally larger and more consistent
- Improved the about and CLI argument modals
- Improved display for the report and CLI argument buttons
- Improved the playbook report header card
- Adjusted search accordions to match new bootstrap theme
- Improvements to responsiveness of layout at smaller (e.g, mobile)
  resolutions
- Truncate excessively long controller hostnames such that they do not
  needlessly take up all the table's available width
- Added support for colored diff when viewing task results
- Fixed the API link when viewing tasks to properly direct to
  /api/v1/tasks

Django templating:

- Large chunks of templating were moved out to partials/tables and
  partials/search in order to improve readability.
- Round of template cleanups and fixes as reported by djlint
- Will continue to be a work in progress to simplify and standardize
  templates.

API Server
----------

- Raised the requirement on django from >=3.2,<3.3 to >=3.2,<4.3 to
  allow installation with the latest LTS release of django.
- Raised the requirement on python from >=3.6 to >=3.8 to accomodate
  django 4.2.
- Ignored Django warning about the lack of a STATIC_ROOT directory.
  ara uses whitenoise for serving static files which makes the warning
  superfluous. (#492)

Ansible callback plugin
-----------------------

- Added ARA_RECORD_CONTROLLER_NAME and ARA_RECORD_USER_NAME settings to
  override the automatic detection of the controller hostname and user
  name for the specified values.
- Added ARA_RECORD_TASK_CONTENT which defaults to true but can be set to
  false to prevent ara from recording the task content for use cases
  where it is not important or to avoid leaking sensitive information.

Maintenance
-----------

Update versions, CI test jobs and container images:

- containers: updated fedora base image from 36 to 38
- containers: updated centos-pypi image from stream8 to stream9
- zuul: Update fedora base image from 36 to 38
- zuul: Update ansible version tested from 6.4.0 to 8.3.0
- zuul: Update versions of ansible-core tested (2.14, 2.15)
- Dropped testing for Ansible 2.9 which has been EOL for over a year.

Upgrade notes
-------------

There are no API changes or SQL migrations in this release.

1.6.1 (2022-12-12)

https://github.com/ansible-community/ara/releases/tag/1.6.1

This is the 1.6.1 stable release of ara.

This is a minor release with two changes:

- callback: Changed how ANSIBLE_TMP is found to work around a behavior
  change in ansible-core 2.14 that ended up creating a directory named
  {{ ANSIBLE_HOME ~ "
  For more information: https://github.com/ansible-community/ara/issues/469

- Added a mysql extra to the python packaging for installing the
  mysqlclient library. This is in addition to the existing server and
  postgresql extra. They are used like this:
  pip install ara[server,mysql,postgresql]

1.6.0 (2022-12-01)

https://github.com/ansible-community/ara/releases/tag/1.6.0

This is the 1.6.0 stable release of ara.

It features a new "tasks" page to browse and search for tasks across playbook runs
as well as many updates, fixes and improvements.

Instructions for upgrading are included in the upgrade notes.

Changes since 1.5.8:

UI
--

- Added a new "Tasks" page similar to the existing pages for Playbooks and Hosts.
  It provides a browseable and searchable overview of tasks across playbook runs.
- Refreshed the host index page:
  - Added a column as well as search arguments for playbook name (or path)
  - Replaced the playbook status by a concise summary of task status for the host

- Updated the playbook summary card to include the playbook id, the version of ara as
  well as the version of python.
- Re-ordered and resized columns in tables to optimize width and improve consistency
- Resized and aligned fields in search forms to use the full width available
- Improved how task tags are displayed
- Updated HTML page titles to be consistent across pages
- Replaced fields for searching by task ID and host ID by task name and host name
- Truncate name fields to prevent exceedinly large names to distort entire tables
- Corrected card header font sizes in the host report page

callback plugin
---------------

- Added support for recording the user who ran the playbook
- Added support for recording the version of ara as well as the version of
  python used when running the playbook
- Added options ARA_RECORD_USER and ARA_RECORD_CONTROLLER that can be
  set to false to avoid recording the user and controller hostname
- Added support for specifying a SSL key, certificate and certificate
  authority for authenticating with a remote ara API server using
  ARA_API_KEY, ARA_API_CERT and ARA_API_CA respectively.
- Fixed host fact recording to ensure it works when using FQCN-style tasks
  (ex: setup & ansible.builtin.setup)
- Increased reliability and accuracy when recording results that can arrive
  out of order when using multi-threading or the free strategy by using the
  task uuid provided by Ansible
- Truncate playbook, play, host and label names in circumstances where their
  length exceeds 255 characters
- Ignore and don't record files in ~/.ansible/tmp by default

API Server
----------

- Bumped django requirement from 2.2 LTS to 3.2 LTS and removed the pin
  on the version of psycopg2 accordingly
- Added a new configuration option, ARA_BASE_PATH, to let the server
  listen on an alternate path. It will continue to default to "/" but it
  could, for example, be set to "/ara/".
- Lifted requirement on tzlocal, improve timezone detection and mitigate
  when the timezone can't be found by defaulting to UTC

- Several new database model and API fields:
  - Added client_version and server_version fields to playbooks, meant to
    represent the version of the ara callback and server used in recording
    the playbook
  - Added python_version field to playbooks to save the version of python
    used by Ansible and the callback plugin when recording a playbook
  - Added a new "failed" status for tasks that is used by the callback plugin
    when there is at least one failed result for a given task
  - Added a new "uuid" field for tasks which is the uuid provided by Ansible
    for a task. It is used by the callback plugin to increase the reliability
    and accuracy when recording results even if they arrive out of order.

- Several fixes and improvements for the distributed sqlite database backend:
  - Added a new index page for listing and linking to available databases.
    This is a work in progress that is intended to be improved in the future.
  - Return a HTTP 405 error when trying to write to read-only endpoints
  - Fixed the /healthcheck/ endpoint to make sure it is routed properly
  - Improved database engine settings and WSGI application configuration
    The WSGI application should now always be "ara.server.wsgi" instead of
    needing to specify "ara.server.wsgi.distributed_sqlite"

API client
----------

- Added support for specifying a SSL key, certificate and certificate
  authority for authenticating with a remote ara API server
- Remove InsecureRequestWarning for insecure requests when SSL verification
  is not enabled.

CLI
---

- Fixed wrong parsing of durations longer than 24 hours
- Added support for searching playbooks by user
- Added support for specifying a SSL key, certificate and certificate
  authority for authenticating with a remote ara API server using
  ARA_API_KEY, ARA_API_CERT and ARA_API_CA respectively.

Docs
----

- Refreshed and improved the README, reformatted it from rst to markdown
- Added a CONTRIBUTING.md file and refreshed contribution documentation
- Explicitly call out and recommend setting up authentication for production
  use in order to prevent leaking sensitive information
- Improved troubleshooting documentation and tips to improve playbook recording
  performance

Tests and miscellaneous
-----------------------

- Bumped the black linter to the latest version and reformatted bits
  of code accordingly
- Updated isort to version 5 and reformatted bits of code accordingly
- Reformatted bits of code using pyupgrade in consideration of dropping
  support for python3.5
- Updated versions of ansible(-core) we run integration tests with to include
  2.9, 2.11, 2.12, 2.13, 2.14 and 6.4.0.
  Although 2.9 is EOL, we will keep it for a while longer.

container-images (contrib)
--------------------------

- The 'latest' tag of container images are now tagged from the latest
  PyPI release instead of the latest git source
- Container images have been updated to the latest distribution images:
  CentOS 8 to CentOS 9 and Fedora 35 to Fedora 36
- Add a centos-source.sh script so we can test from source in addition
  to PyPI
- Install everything from PyPI (except ara when from source) in order
  to avoid mixing distribution packages with PyPI packages

Upgrade notes
-------------

- ara 1.5.8 was the last version to support python3.5.
  Starting with ara 1.6.0, python3.6 or later is required.

- ara 1.6.0 includes several database migrations and it is highly recommended
  to take a backup of the server database before updating.
  Database migrations are run automatically in many circumstances and can be run
  manually using "ara-manage migrate".

- There are a few backwards incompatible changes introduced in ara 1.6.0 which
  makes it important to run the same version of ara everywhere to avoid running
  into problems if the version of the callback plugin and server do not match.

- There is a database migration which grows the maximum length of the name fields
  for plays and labels which was later reverted due to potential issues when using
  the MySQL database backend.

1.5.8 (2022-03-24)

https://github.com/ansible-community/ara/releases/tag/1.5.8

This is the 1.5.8 stable release of ara.

It features new callback and server settings as well as fixes and
maintenance.

Instructions for upgrading are included in the upgrade notes.

Callback plugin
---------------

- Improved debug logging to include some hooks that were missing (#374)
- Added a localhost_to_hostname toggle in the callback (#336)
  This adds two configuration parameters to the callback:
  - ARA_LOCALHOST_AS_HOSTNAME
  - ARA_LOCALHOST_AS_HOSTNAME_FORMAT

  These are useful in use cases where playbooks are run against localhost,
  whether directly (with ansible-playbook) or indirectly (via
  ansible-pull).

  When enabled, ara will save results under the hostname (or fqdn) of
  'localhost' instead of associating every result to localhost.
  This is meant to make it easier to distinguish results between different
  hosts even though the playbooks may have all run against 'localhost'.

Server
------

- Added a setting for CSRF_TRUSTED_ORIGINS (#345)
- Fixed logging configuration to avoid conflicting with ansible (#367)
  See upgrade notes for changes to the server's settings.yaml.

UI
--

- API browser: disable forms to improve performance (#323)
- Include the version of ara when generating static reports (#318)
- Add a column in task results for displaying the task's tags (#281,#375)

CLI
---

- Added "--latest" to "ara host list" to show only the latest playbook (#327)

Docs
----

- Refreshed authentication docs and recommend using EXTERNAL_AUTH
  with nginx or apache in front (#319)
- Add database and authentication tips to troubleshooting (#355)

Packaging and dependencies
--------------------------

- API Server container images have been bumped to fedora35 and centos8-stream
- Updated setup.cfg to fix a deprecation warning for python 3.10 (#371)
- Fixed distutils.sysconfig deprecation warning on python 3.10 (#369)
- Fixed dynaconf deprecation warning when loading settings (#369)
- psycopg2 has been pinned to <2.9 due to incompatibility with django 2.2 (#321,#326)
- dynaconf has been pinned to <3.0 when using python3.5 (#372)
  dynaconf>=3.0 supports python>=3.6.

Misc
----

- General CI maintenance
- Updated Zuul to test the latest versions of ansible and ansible-core
- Re-enabled container image updates on DockerHub and Quay.io
- Added an example script with ansible-runner (#343)

Upgrade notes
-------------

- There have been fixes to logging which requires changes to the
  server's settings.yaml or LOGGING configuration. (#367)
  A warning will be printed if the configuration file must be updated
  and it can be updated manually or by generating a new configuration file.

- ara 1.5.8 is the last release that will support python3.5.
  Python 3.5 reached the end of its life on September 13th, 2020.
  An upcoming release will update the version of django to the next LTS (2.2 to 3.2)
  which will bump the requirement to python>=3.6.

1.5.7 (2021-07-31)

https://github.com/ansible-community/ara/releases/tag/1.5.7

This is the 1.5.7 stable release of ara.

It features a new "hosts" page to browse and search playbook reports by host
as well as fixes and improvements.

Instructions for upgrading are included in the upgrade notes.

Changes since 1.5.6:

UI
--

- Added a new "hosts" page to browse and search reports by host name
- Improved page HTML titles to be dynamic based on the context
- Added a note highlighting if a task has been delegated to another host
  (https://github.com/ansible-community/ara/issues/282)
- Improved how long file paths or playbook names are truncated and displayed

API
---

- Added a new read-only API endpoint: /api/v1/latesthosts
  It provides the latest playbook result for each host name.
  Under the hood, it implements the machinery for updating the latest host
  every time a host is created or deleted and includes a SQL migration to
  initially populate a new database table with the latest hosts.
- Added a `delegated_to` field to results in order to record a host id to which
  a task has been delegated.
- Added support for finding results delegated to a specific host:
  /api/v1/results?delegated_to=<host_id>

Callback plugin
---------------

- Fixed tasks and results being recorded out of order when using "strategy: free"
  (https://github.com/ansible-community/ara/issues/260)
- Added support for recording 'delegate_to' on tasks

Documentation
-------------

- Removed an unused sphinx lexer to allow recent versions of sphinx>=4
- Created a new troubleshooting guide with common issues:
  https://ara.readthedocs.io/en/latest/troubleshooting.html
- Added a database relationship graph to the endpoint documentation:
  https://ara.readthedocs.io/en/latest/api-documentation.html#relationship-between-objects

Upgrade notes
-------------

It is always recommended to take a backup of your database before upgrading.

This release includes two database migrations that must be run:
- One for populating the data for the new /api/v1/latesthosts endpoint as well
  as the new 'hosts' page
- One for adding a `delegated_to` field in the results.
  Note that delegated tasks will only be recorded as such from 1.5.7 on.

After upgrading to 1.5.7, database migrations can be run manually with the
`ara-manage migrate` command if they are not taken care of automatically by the
callback plugin.

Known issues
------------

ara will not record task delegation for tasks that are skipped or for
items in a loop that are skipped because Ansible doesn't provide the
necessary information in those cases.

1.5.6 (2021-04-14)

https://github.com/ansible-community/ara/releases/tag/1.5.6

This is the 1.5.6 stable release of ara.

It features a refresh of the playbook reporting interface included with the API server as well as fixes and improvements.

Changes since 1.5.5:

UI
--

- Refactored the built-in reporting UI with the bootstrap CSS framework using themes from bootswatch
- Added a dark theme in addition to the default light theme (toggle at the top right)
- Improved the mobile version of the reporting interface
- Improved the playbook and task result tables
- Revamped search forms for playbook and playbook results
- Revamped hosts table in playbook reports
- Added task results to the host details page that includes host facts
- Moved ansible-playbook CLI arguments to a modal
- Added an "about" modal with the version of ara and links to resources
- Moved the link to the documentation to the "about" modal
- Clicking on a host or task name in a playbook report will now filter results for that host or task
- bugfix: Links to files including a lineno will now highlight that line (https://github.com/ansible-community/ara/issues/154)
- bugfix: Fixed broken documentation link to ara_record (https://github.com/ansible-community/ara/issues/219)

API
---

- Playbook references will now always include CLI arguments, for example:
  /api/v1/tasks/1 ->
  {
    "id": 1,
    "playbook": {
      "id": 1,
      "arguments": {
        #...
      }
    }
  }

Callback plugin
---------------

- bugfix: Truncate play UUIDs given back by ansible-runner when running in serial (https://github.com/ansible-community/ara/issues/211)

1.5.5 (2021-01-29)

https://github.com/ansible-community/ara/releases/tag/1.5.5

This is the 1.5.5 stable release of ara.

Changes since 1.5.4:

API
---

- Added support for searching playbooks by ansible_version, for example:
  /api/v1/playbooks?ansible_version=2.10

UI
--

- Added syntax highlighting to task results
- Added support for rendering nested results for tasks with loops
- Added support for rendering diffs provided by "ansible-playbook --diff"
- Added support for searching playbooks by ansible_version
- The playbook links in the index no longer filter to changed results
- Ordering by date or duration no longer discards existing search arguments
- Clicking on the logo or the "playbooks" link now discards existing search arguments

CLI
---

- Added support for searching playbooks by ansible_version
- Added missing argument for --controller to "ara playbook metrics"

1.5.4 (2020-12-18)

https://github.com/ansible-community/ara/releases/tag/1.5.4

This is the 1.5.4 stable release of ara.

Changes since 1.5.3:

CLI
---

New commands were added to the 'ara' CLI:

- ara playbook metrics: provides stats aggregated by name, path, ansible version or controller
- ara host metrics: provides task result stats for hosts across playbooks
- ara task metrics: provides duration stats aggregated by task name, action/module or path

Refer to the documentation for examples and more information on these commands:
https://ara.readthedocs.io/en/latest/cli.html

Callback plugin
---------------

- Threading is now disabled by default to avoid running into sqlite locking contention
  For details, see: https://github.com/ansible-community/ara/issues/195
- The callback didn't provide a timezone for timestamps which could result in a wrong
  interpretation by the API server. Timestamps are now provided as UTC.

Controller hostname
-------------------

The hostname of the controller that ran the playbook is now recorded by ara.

Playbooks can be filtered by controller in the UI as well as the API:

    /api/v1/playbooks?controller=localhost

As well as with the CLI, for example:

    ara playbook list --controller=localhost
    ara playbook metrics --controller=localhost

Container images
----------------

- ARA API server container images are now published to quay.io/recordsansible/ara-api
  in addition to hub.docker.com/r/recordsansible/ara-api.
- Fedora 32 images were replaced by images based on Fedora 33
- The 'which' package is now installed as a dependency
- Removed a temporary workaround for dynaconf switching from PyYAML to ruamel.yaml

UI
--

- Added missing information about the play when browsing details for a task result

Upgrade notes
-------------

The new controller hostname feature introduces a SQL migration to update the database schema.
After upgrading, database migrations will need to be run at least once using 'ara-manage migrate'.

Because the hostname was not previously saved and can't be recovered retroactively,
playbooks that were recorded before the upgrade will have the controller set to 'localhost'.

1.5.3 (2020-10-23)

https://github.com/ansible-community/ara/releases/tag/1.5.3

This is the 1.5.3 stable release of ARA.

This release works around a bug introduced in 1.5.2 which could
sometimes cause the Ansible playbook execution to lock up when using the
default offline API client.

For details, see https://github.com/ansible-community/ara/issues/183

1.5.2 (2020-10-16)

https://github.com/ansible-community/ara/releases/tag/1.5.2

This is the 1.5.2 stable release of ARA.

Changes since 1.5.1:

Ansible callback plugin
-----------------------

- Significant performance improvement by running non-blocking API calls in threads
  https://github.com/ansible-community/ara/issues/171
- Handler tasks are now also recorded in addition to regular tasks
  https://github.com/ansible-community/ara/issues/178

API
---

- Add support for searching handler tasks (ex: /api/v1/tasks?handler=true)

UI
--

- Hosts in the playbook report are now sorted alphabetically by hostname
- Added a column to display the number of tasks in the playbook summary

1.5.1 (2020-09-23)

https://github.com/ansible-community/ara/releases/tag/1.5.1

This is a re-release of the 1.5.0 stable version of ara in order to fix
a release issue to PyPi.

1.5.0.1 (2020-09-23)

https://github.com/ansible-community/ara/releases/tag/1.5.0.1

This is a re-release of the 1.5.0 stable version of ara in order to fix
a release issue to PyPi.

1.5.0 (2020-09-23)

https://github.com/ansible-community/ara/releases/tag/1.5.0

This is the 1.5.0 stable release of ARA.

Changes since 1.4.3:

CLI
---

A new 'ara' CLI API client is now available with the following commands:

- expire           Expires objects that have been in the running state for too long
- host delete      Deletes the specified host and associated resources
- host list        Returns a list of hosts based on search queries
- host show        Returns a detailed view of a specified host
- play delete      Deletes the specified play and associated resources
- play list        Returns a list of plays based on search queries
- play show        Returns a detailed view of a specified play
- playbook delete  Deletes the specified playbook and associated resources
- playbook list    Returns a list of playbooks based on search queries
- playbook prune   Deletes playbooks beyond a specified age in days
- playbook show    Returns a detailed view of a specified playbook
- record delete    Deletes the specified record and associated resources
- record list      Returns a list of records based on search queries
- record show      Returns a detailed view of a specified record
- result delete    Deletes the specified result and associated resources
- result list      Returns a list of results based on search queries
- result show      Returns a detailed view of a specified result
- task delete      Deletes the specified task and associated resources
- task list        Returns a list of tasks based on search queries
- task show        Returns a detailed view of a specified task

More information on the CLI commands is available in the docs:
https://ara.readthedocs.io/en/latest/cli.html

API server
----------

New settings have been added:

- ARA_EXTERNAL_AUTH for enabling Django's external authentication
- ARA_DATABASE_OPTIONS for passing options to the Django database backend such as SSL.

More information on the API server settings are available in the docs:
https://ara.readthedocs.io/en/latest/api-configuration.html

API
---

- Added created/updated fields to list views (ex: /api/v1/playbooks, /api/v1/results)
- Added support for filtering hosts based on their results, for example:
  - return hosts with no changes: /api/v1/hosts?changed__lt=1
  - return hosts with failures: /api/v1/hosts?failed__gt=0
  - return hosts with unreachable tasks: /api/v1/hosts?unreachable__gt=0
- Added support for searching results by changed (ex: /api/v1/results?changed=true)
- Added support for searching results by play, task or host (ex: /api/v1/results?task=<id>)
- Nested children resources are no longer returned, improving performance
  considerably for larger playbooks. For example, querying a single playbook's
  details no longer returns it's entire hierarchy of plays, tasks, results and hosts.
  These must now instead be queried individually, ex: /api/v1/results?playbook=<id>
  See https://github.com/ansible-community/ara/issues/158 for details.
- The result statuses "changed" and "ignored" have been removed. These weren't
  actually used anywhere, it was instead inferred by a combination of the status
  as well as the "changed" and "ignore_error" fields.
  See https://github.com/ansible-community/ara/issues/150 for details.
- A new status was added for playbooks, plays and tasks: "expired".
  This status is meant to be used to identify resources that have been in the
  "running" state for too long and will never complete.
  Use the new "ara expire" CLI command for expiring resources.
  See https://github.com/ansible-community/ara/issues/26 for details.

UI
--

- URLs have been pluralized to match the endpoints provided by the API.
  For example:
    /playbook/1.html -> /playbooks/1.html
    /result/1.html -> /results/1.html
- Links to playbooks from the index will now filter results by default based on
  their status. For example, a failed playbook will link to results that are failed
  or unreachable while a successful playbook will link to results that are changed.

When browsing a playbook's details:
- Links to files from task actions have been fixed to use the correct anchor
  when linking to a specific line
- Task results are now paginated
- A search form has been added to the task results pane, allowing search
  by host id, task id, status and changed
- The hosts table has been updated to leverage the new search
  capabilities. Clicking on the host will search tasks for this host and
  clicking on the number in status column for a host (i.e, "20" changed)
  will search for that host and that status. As a result, host facts
  have been moved to it's own column.

Ansible plugins
---------------

- New feature: argument labels.
  Based on the configuration, the callback will now automatically label
  playbooks after specified CLI arguments. For example, when "--check" is used,
  it will label the playbook with "check:True" -- or "check:False" when it isn't used.
- Starting with Ansible 2.8, the callback leverages a new hook in order to improve
  the accuracy of task result durations.
  See https://github.com/ansible-community/ara/issues/173 for details.

Documentation
-------------

- Refreshed installation docs into a "getting started" guide
- Added notes about installation on CentOS 7 / RHEL 7 as well as Mac OS
- Refreshed and merged Ansible plugin configuration and use case docs
- Changelogs and release notes have been incorporated in the docs

Upgrade notes
-------------

- The introduction of the new CLI adds a requirement on the cliff python library.
- ara 1.5.0 introduces significant API changes, some of which aren't backwards
  compatible such as no longer returning nested resources.
- Two small SQL migrations have been added to remove result statuses and add the
  expired status for playbooks, plays and tasks. Run them with "ara-manage migrate".
- "ara-manage prune" has been deprecated and is replaced by "ara playbook prune".
  The new prune command provides additional filters in order to only delete
  playbooks matching certain criteria such as label, name, path or status.

1.4.3 (2020-08-11)

https://github.com/ansible-community/ara/releases/tag/1.4.3

This is the 1.4.3 stable release of ARA.

The only change since 1.4.2 is an additional regression fix with the
latest version of dynaconf. For more information, see the issue:
https://github.com/ansible-community/ara/issues/149

1.4.2 (2020-07-02)

https://github.com/ansible-community/ara/releases/tag/1.4.2

This is the 1.4.2 stable release of ARA.

This release comes sooner than expected in order to fix a regression when
installing ara with the latest version of dynaconf (3.0.0) due to a change in
the preferred yaml package.

For more information about this issue, see https://github.com/ansible-community/ara/issues/146

Built-in reporting interface
----------------------------

- Improvements to the interface scaling and rendering for mobile devices
- The playbook index has been refactored from a list of cards to a table view
  and searching/filtering controls are no longer hidden in a submenu
- Sorting by playbook date and duration is now built into the table headers
- The Ansible CLI arguments are now available from the playbook index
- The host stats summary now displays colors and icons for the different statuses
- Task result columns were re-ordered and statuses now have colors and icons
- Long task results or host facts should no longer render off-screen

1.4.1 (2020-05-26)

https://github.com/ansible-community/ara/releases/tag/1.4.1

This is the 1.4.1 stable release of ARA.

Changes since 1.4.0:

Ansible Adhoc command recording
-------------------------------

It is now possible to record "ansible" commands in addition to the
existing support for "ansible-playbook" commands starting with Ansible
2.9.7 and above.

To record Ansible adhoc commands, set 'bin_ansible_callbacks' to true in
your ansible.cfg or run: export ANSIBLE_LOAD_CALLBACK_PLUGINS=true

API
---

- Added search for ignore_errors in results:
    /api/v1/results?status=failed # includes "ignore_errors: true"
    /api/v1/results?status=failed&ignore_errors=false

- Added search for task by action:
    /api/v1/tasks?action=package
    /api/v1/tasks?action=command

- Adjusted search for file paths to be partial:
    /api/v1/files?path=/home/user/ansible/roles/foo/tasks/main.yaml
    /api/v1/files?path=foo

- Added search for task by path:
   /api/v1/tasks?path=/home/user/ansible/roles/foo/tasks/main.yaml
   /api/v1/tasks?path=foo

- Fixed an error 500 when querying playbooks with labels

Built-in UI
-----------

- The path to the playbooks that are displayed when no names are given
  by "ara_playbook_name" are now truncated from the left rather than
  from the right. For example, given:
  /home/user/git/source/organization/repo/playbooks/prod/restart-everything.yaml

  Before:
  /home/user/git/source/organization/repo/playbooks/...
  After:
  ...zation/repo/playbooks/prod/restart-everything.yaml

Container images
----------------

The project now publishes simple container images suitable for use with sqlite,
mysql and postgresql database backends out of the box.

The images are currently available on Docker Hub:
https://hub.docker.com/r/recordsansible/ara-api

You can learn about how the images are built, how you can build
your own and how you can run them in the documentation:
https://ara.readthedocs.io/en/latest/container-images.html

1.4.0 (2020-04-16)

https://github.com/ansible-community/ara/releases/tag/1.4.0

This is the 1.4.0 stable release of ARA.

Changes since 1.3.2:

API
---

- Added support for searching plays, tasks and hosts by name
- Added support for searching playbooks by label
- Fixed label representation to be consistent through different calls
- Reversed the default sort order for playbooks, plays, tasks and results

API server
----------

- Validate that settings.yaml (or ARA_SETTINGS) exists before launching (thank you @zswanson!)
- Template the default settings file without objects generated by python-box

Bundled reporting interface
---------------------------

- Added a default robots.txt to prevent crawling
- Added support for searching by label
- Improved the display of labels in the playbook list
- Added pagination support when browsing the playbook report list
- Use relative links for pagination (thank you @flowerysong !)
- Bumped included patternfly CSS from 2.21.5 to 2.56.3

ara_api Ansible role
------------

- Provide sensible PATH defaults when virtualenvs are not used
- Added support for installing from Fedora packages
- Only run SQL migrations once when necessary
- Allow retries when attempting to run SQL migrations
- Ensure settings.yaml permissions are 0640
- Added "ara_api_secure_logging" variable to control behavior of sensitive tasks with no_log
- Properly default to IPv6 when no IPv4 is available
- Default gunicorn worker count based on number of available CPU cores
- Added support for deploying on EL8

Ansible plugins
---------------

- New Ansible plugins: ara_playbook and ara_api
- Improved consistency of stored task results (thank you @flowerysong!)
- Fix bad logic when determining if labels should be updated
- Added support for not saving files based on patterns (thank you @LaurentDumont!)
- Added support for specifying default playbook labels

Integration tests
-----------------

- Refactored integration tests to simplify and improve coverage across different
  database backends, linux distributions and versions of Ansible

Upgrade notes
-------------

- 1.4 introduces a new SQL migration to ensure labels are unique. If upgrading
  from a previous version, you will need to run SQL migrations with ``ara-manage migrate``.

0.16.7 (2020-04-14)

https://github.com/ansible-community/ara/releases/tag/0.16.7

0.16.7 is a maintenance release for ARA 0.x.

Changes since 0.16.6:

- Fix typo in ara.setup.env for ANSIBLE_ACTION_PLUGINS [1]
- Pin pyfakefs to <4 in order to avoid breaking python2 usage [2]
- Pin junit-xml to <=1.8 in order to avoid deprecation warnings in unit tests

ARA 0.x end of life
-------------------

The code base for ARA 0.x has not been actively maintained and developed
since 2018 and will officially reach end of life June 4th, 2019, one year
after the release of ARA 1.0.

Unless critical bugs are found between this release and June 4th, 0.16.7
will be the last supported release of the 0.x branch.

Please use the latest version of ARA to benefit from the
new features and fixes.

[1]: https://github.com/ansible-community/ara/pull/97
[2]: https://github.com/ansible-community/ara/issues/118

1.3.2 (2019-12-12)

https://github.com/ansible-community/ara/releases/tag/1.3.2

This is the 1.3.2 stable release of ARA.

Changes since 1.3.1:

- Fix compatibility with the new version of
  django-rest-framework, 3.11 [1]

[1]: https://github.com/ansible-community/ara/issues/102

1.3.1 (2019-12-06)

https://github.com/ansible-community/ara/releases/tag/1.3.1

This is the 1.3.1 stable release of ARA.

Changes since 1.3.0:

- bugfix: the callback plugin now properly retrieves host facts for
  both setup and gather_fact tasks
- bugfix: fixed a typo in ara.setup.env which set the
  ANSIBLE_ACTION_PLUGINS to the callback directory instead of the
  action module directory.
- unit tests: use assertLogs instead of patch_logger since
  patch_logger was removed from django 3.
- misc: bumped versions of Ansible used in integration tests

1.3.0 (2019-12-03)

https://github.com/ansible-community/ara/releases/tag/1.3.0

This is the 1.3.0 stable release of ARA.

Changes since 1.2.0:

General
-------

- Removed hard requirement on python 3.6 due to the usage of f-strings.
  ARA should also work on python 3.5 now.

Web user interface
------------------

- Added a tab at the top of the playbook list to search, sort and filter by date
  - Search can be based on the playbook's name, path, or status
  - Sort can be ascending or descending for start date, end date or duration
  - Filter can show playbooks in the last 60 minutes, 24 hours, 7 days or 30 days
- Fixed a bad link to the task file in the detailed result view

API
---

- Added support for searching date fields for playbooks, plays, tasks and results [1]
  For example:

    /api/v1/playbooks?started_before=2019-10-01T09:57:36.489016
    /api/v1/results?created_after=2019-10-01T09:57:36.489016

- The duration of items is now calculated and stored in the database model
  instead of being calculated on demand by the API. This provides the ability to
  easily sort objects based on their duration.
  A SQL migration has been added as a result of this change.

- Added support for ordering objects by most fields [2]
  For example:

    /api/v1/playbooks?order=id (ascending, oldest first)
    /api/v1/playbooks?order=-id (descending, most recent first)

  The currently supported fields available for sorting are:
    - created
    - updated
    - started (for playbooks, plays, tasks, results)
    - ended (for playbooks plays, tasks, results)
    - duration (for playbooks, plays, tasks, results)
    - path (for files)
    - key (for records)
    - ok, skipped, changed, failed and unreachable (for hosts)

- Added support for searching playbooks by their full path or only part of it.
  For example, a playbook with the path ``/home/user/ansible/playbook.yml``
  can be found by searching for either ``user`` or the full path.

- Searching for playbook names now also supports partial search.

- Improved handling of non-ascii/binary output to prevent UnicodeEncodeError
  exceptions [3]

- Standardized the search by status for playbooks, plays, tasks and results

- The built-in development server now checks if psycopg2 or mysqlclient are
  installed before launching when using the postgresql or mysql database backend. [4]

API client
----------

- Added support for ignoring SSL verification [5]

Plugins
-------

- Added the ``ARA_API_INSECURE`` setting to the callback plugin to ignore SSL
  verification.

CLI
---

- Added an ``ara-manage prune`` command to delete playbooks older than a specified
  amount of days. [6]

Documentation
-------------

- Refreshed docs on installation
- First iteration of documentation for the ``ara-manage`` commands
- Docs now require the API server dependencies to be installed so CLI snippets
  can be included automatically with sphinxcontrib-programoutput.

Upgrade notes
-------------

- 1.3.0 introduces a new SQL migration to move durations from the API to the
  database model. If upgrading from a previous version, you will need to run
  SQL migrations with ``ara-manage migrate``.

Referenced or fixed issues
--------------------------

[1]: https://github.com/ansible-community/ara/issues/30
[2]: https://github.com/ansible-community/ara/issues/68
[3]: https://github.com/ansible-community/ara/issues/48
[4]: https://github.com/ansible-community/ara/issues/63
[5]: https://github.com/ansible-community/ara/issues/90
[6]: https://github.com/ansible-community/ara/issues/31

0.16.6 (2019-11-18)

https://github.com/ansible-community/ara/releases/tag/0.16.6

0.16.6 is a maintenance release for ARA 0.x.

Changes since 0.16.5:

- Fixed web application crash due to encoding/decoding of binary
  non-ascii content in task results
- The sqlite middleware was adapted to support running under gunicorn.
- ``python -m ara.setup.env`` now returns commands that use bash expansion to
  take into account existing environment variables

Eventual end of life for ARA 0.x
--------------------------------

All new feature and development effort for more than a year has been spent on
the master branch of ARA which is the basis of version 1.x releases.

Users are encouraged to try the latest release of ARA and create an issue on
GitHub if they encounter any issues or missing features.

ARA 0.16.6 could be the last release of ARA 0.x if no major issues are found.

1.2.0 (2019-10-25)

https://github.com/ansible-community/ara/releases/tag/1.2.0

This is the 1.2.0 stable release of ARA.

Changes since 1.1.0:

New bundled reporting interface
-------------------------------

- A new simple built-in web reporting interface is now bundled with the API server
- The simple web reporting interface can be exported to static html with ``ara-manage generate <path>``

API
---

- An ``items`` field was added to playbook, plays and task objects to display the number of child references
- The task file path is now available as task.path
- Playbook labels as well as ansible_version are now always provided for playbook objects
- The "created" and "updated" fields are now provided when querying a host list

Settings
--------

- New setting to control the timezone used for storing and displaying data: ``ARA_TIME_ZONE``
- New setting to provide a list of regex patterns for whitelisting CORS: ``ARA_CORS_ORIGIN_REGEX_WHITELIST``
- The default for ``ARA_DISTRIBUTED_SQLITE_PREFIX`` was changed from /ara-api to /ara-report

Other changes
-------------

- Significant performance improvements by reducing the amount of API calls to host and file endpoints by the callback plugin during playbook execution
- A basic healthcheck has been implemented at ``/healthcheck/`` to allow simple monitoring of the interface and database connection
- ``python -m ara.setup.env`` now returns commands that use bash expansion to take into account existing environment variables
- The API clients will strip trailing slashes if they are provided in the endpoints
- Removed a needless newline when generating the default settings.yaml file

Upgrade notes
-------------

The new healthcheck feature adds a dependency on the django-health-check library
and includes a SQL migration that needs to be run before it can be used.
SQL migrations can be executed by running ``ara-manage migrate``.

1.1.0 (2019-07-02)

https://github.com/ansible-community/ara/releases/tag/1.1.0

Changes since 1.0.1:
- Added support for dynamically serving multiple sqlite databases
  dynamically from a single API server instance [1]
- ara_record no longer instanciates it's own API client and will
  instead retrieve the client instance used by the callback.
- Django's CONN_MAX_AGE database setting for configuring the
  duration of a database connection is now exposed [2]
- The ARA API client timeout as configured by Ansible through the
  callback plugin is now always an integer.
- The offline API client now has an argument to prevent SQL
  migrations from running automatically [3]

For the ara_api Ansible role [4]:
- The role no longer attempts to set up and manage a PID file when
  setting up a persistent service running with gunicorn.
- The bundled selinux policy file for running out of a user's home
  directory has been updated and is now integration tested.
- Added support and integration tests for deploying Django with the
  MySQL backend

[1]: https://ara.readthedocs.io/en/latest/distributed-sqlite-backend.html
[2]: https://ara.readthedocs.io/en/latest/api-configuration.html#ara-database-conn-max-age
[3]: https://ara.readthedocs.io/en/latest/api-usage.html#ara-offline-api-client
[4]: https://ara.readthedocs.io/en/latest/ansible-role-ara-api.html

0.16.5 (2019-06-04)

https://github.com/ansible-community/ara/releases/tag/0.16.5

Changes since 0.16.4:

- Updated references to the master git branch or documentation
  now that 0.x development work has been moved to stable/0.x

1.0.1 (2019-06-05)

https://github.com/ansible-community/ara/releases/tag/1.0.1

Changes since 1.0.0:

- Updated references to the feature/1.0 git branch or documentation
  now that 1.0 development work has been moved to master
- Fixed an issue preventing the HTTP API client from being used unless
  the server dependencies had been installed.
- Added support for customizing the amount of results per page returned
  by the API with ARA_PAGE_SIZE [1]
- The ara_api role now sets up a basic selinux policy when running
  gunicorn out of a home directory on Red Hat based systems.

[1]: https://ara.readthedocs.io/en/latest/api-configuration.html#ara-page-size

1.0.0 (2019-06-03)

https://github.com/ansible-community/ara/releases/tag/1.0.0

This is the first release of ARA on top of a new framework and API,
dubbed version 1.0.

This new release marks the deprecation of ARA 0.x and while full feature parity
has not yet been achieved, we are moving forward and we will iterate to add
missing features in future releases.

Main changes from ARA 0.x:

- The backend has been re-written from Flask to Django/Django-rest-framework
- A new API as well as built-in API clients are available to record and query playbook results
- The project's dependencies have been decoupled: the Ansible plugins, API backend and web interface can be installed independently from one another
- The web interface has been re-written as a standalone project -- ara-web: https://github.com/ansible-community/ara-web

In summary, all the different components before 1.0, including the web interface,
would communicate directly with the database model.

After 1.0, these components communicate with the new REST API which results in
easier development, maintenance and integration.

0.16.4 (2019-05-22)

https://github.com/ansible-community/ara/releases/tag/0.16.4

This is a stable release of ARA, 0.16.4.

***
WARNING: Please note that the next major version of ARA, 1.0, is
         currently in beta and is not backwards compatible with ARA 0.x.
         In order to avoid upgrading unexpectedly when 1.0 is released,
         we recommend pinning ara to <1.0.0 in your scripts and requirements.
***

Changelog since 0.16.3:
- Fixed a regression when saving tasks with Ansible 2.8 [1]

[1]: https://github.com/ansible-community/ara/issues/46

0.16.3 (2019-01-21)

https://github.com/ansible-community/ara/releases/tag/0.16.3

This is a stable release of ARA, 0.16.3.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL database schema.
***

Changelog:
- Update integration tests to target latest versions of Ansible (2.7.6,
2.6.12 and 2.5.14)
- Adjust how CLI options are saved to support the upcoming release of
  Ansible, 2.8.

0.16.2 (2019-01-02)

https://github.com/ansible-community/ara/releases/tag/0.16.2

This is the newest stable release of ARA, 0.16.2.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL database schema.
***

This release comes thanks to bug fixes contributed by the community:

- Jonathan Herlin fixed the deprecation notice "Call to deprecated
  function CreateFile. Use create_file instead." when generating HTML
  reports.
- Sorin Sbarnea addressed testing warnings and made it so future
  warnings would be considered as errors
- Sorin Sbarnea removed integration testing for the "static: no"
  argument from Ansible includes since this parameter has been removed
  from Ansible after being deprecated.

0.16.1 (2018-09-04)

https://github.com/ansible-community/ara/releases/tag/0.16.1

This is the newest stable release of ARA, 0.16.1.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL database schema.
***

This is a hotfix release to address a bug in host facts sanitization
with the introduction of the "ARA_IGNORE_FACTS" feature in 0.16.0.
While task results were properly sanitized, host facts were not.

0.16.1 addresses the issue by sanitizing both host facts and task
results.

0.16.0 (2018-08-27)

https://github.com/ansible-community/ara/releases/tag/0.16.0

This is the newest stable release of ARA, 0.16.0.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL database schema.
***

This release of ARA is made possible thanks to the following contributions:

- Tristan de Cacqueray from Red Hat resolved an issue where under certain
  circumstances, an empty ARA_LOG_FILE configuration could raise an exception.
- Artem Goncharov from Open Telekom Cloud resolved an issue where configuration
  parameters through environment variables could not taken into account
  properly when using the ara-wsgi and ara-wsgi-sqlite scripts.
- Joshua Harlow from GoDaddy submitted several improvements to performance and
  RAM usage when browsing large reports.
- Sorin Sbarnea from Red Hat contributed documentation on serving static ARA
  reports with nginx and improved the junit export to allow for overrides
- Haikel Guemar from Red Hat identified and fixed usage of reserved key words
  in Python 3.7
- Robert de Bock for suggesting a security improvement around host facts
  and the ansible_env fact.

Other improvements include:

- Improve self-healing when running into a race condition where the playbook
  run is interrupted early enough for the playbook to be created in the
  database but before it's file was saved.
- Prevent ARA's logging configuration from "leaking" into the configuration
  of other python modules at runtime.
- Add a trailing slash to file links in the file tab, resolving an issue
  where reverse proxies might get confused when doing SSL termination.

Security:

Robert de Bock from ING Bank reported that sensitive information might
be stored in environment variables from the Ansible control node and
that as such, there should be a way to prevent the 'ansible_env' host
fact from being recorded by ARA.

As such, we have added a new configuration parameter: ARA_IGNORE_FACTS [1].
ARA_IGNORE_FACTS is a comma-separated list of host facts that ARA will not
record in it's database.
ARA will also sanitize the output of gather_facts and setup tasks to prevent
these facts from displaying in the task results.
By default, only the "ansible_env" fact is ignored due to the high likelihood
of it containing sensitive information.

Maintenance:

- Dropped backwards compatibility layer for supporting Ansible 2.3
- Updated integration jobs to test against the latest versions of Ansible 2.4,
  2.5 and 2.6

[1]: https://ara.readthedocs.io/en/latest/configuration.html#ara-ignore-facts

0.15.0 (2018-05-01)

https://github.com/ansible-community/ara/releases/tag/0.15.0

This is the newest stable release of ARA, 0.15.0.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL database schema.
***

Changelog:

- ARA: Ansible Run Analysis has been "rebranded" to ARA Records Ansible
  (Another Recursive Acronym)
- Significant improvements to memory usage and performance when running ARA as
  a WSGI application with 'ara-wsgi' or 'ara-wsgi-sqlite'.
- Resolved an issue where the 'ara-wsgi-sqlite' middleware could serve a
  cached report instead of the requested one
- Added support for configuring the 'SQLALCHEMY_POOL_SIZE',
  'SQLALCHEMY_POOL_TIMEOUT' and 'SQLALCHEMY_POOL_RECYCLE' parameters.
  See the configuration documentation [1] for more details.
- Logging was fixed and improved to provide better insight when in DEBUG level.
- Vastly improved the default logging configuration.
  ARA will create a default logging configuration file in '~/.ara/logging.yml'
  that you can customize, if need be. Deleting this file will make ARA create
  a new one with updated defaults.
- Added python modules to help configure Ansible to use ARA, for example,
  'python -m ara.setup.callback_plugins' will print the path to ARA's callback
  plugins.
  You can find more examples in the configuration documentation. [1]
- Implemented a workaround for fixing a race condition where an
  'ansible-playbook' command may be interrupted after the playbook was recorded
  in the database but before playbook file was saved.
- Flask 0.12.3 was blacklisted from ARA's requirements [2], this was a broken
  release.
- The ARA CLI can now be called with "python -m ara" if you need to specify a
  specific python interpreter, for example.
- Updated and improved integration tests across different operating systems,
  python2 and python3 with different versions of Ansible. The full test matrix
  is available in the README. [3].

[1]: https://ara.readthedocs.io/en/stable/configuration.html
[2]: https://github.com/openstack/ara/commit/87272840bfc8b4c5db10593e47884e33a0f4af40
[3]: https://github.com/openstack/ara#contributing-testing-issues-and-bugs

0.14.6 (2018-02-05)

https://github.com/ansible-community/ara/releases/tag/0.14.6

This is a maintenance release for the stable version of ARA.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL schema.
         Please see this blog post [1] for details.
***

Changelog:
- Unit and integration changes improvements
- Workaround an issue where Ansible could sometimes return a non-boolean
  value for the "ignore_errors" field.

[1]: https://dmsimard.com/2017/11/22/status-update-ara-1.0/

0.14.5 (2017-10-26)

https://github.com/ansible-community/ara/releases/tag/0.14.5

This is a release for the version 0.14.5 of ARA.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL schema.
         Please see this blog post [1] for details.
***

This version notably fixes an issue when using ansible.cfg to
configure ARA when using Ansible 2.4.0.
0.14.5 is meant to be used with Ansible 2.4.1 and using it with Ansible
2.4.0 is not recommended because it does not contain a necessary bugfix [2].

Changelog:
- ARA can be configured through an ansible.cfg file with Ansible 2.4.1.
- Ansible 2.4.0 is blacklisted in requirements.txt
- Added a WSGI middleware to load sqlite databases at variable locations
  for advanced large-scale usage. See documentation [1] for details.
- Resolved an issue when clicking on permalink icons (blue chain links)
  on Firefox. (Thanks Mohammed Naser)

[1]: http://ara.readthedocs.io/en/latest/advanced.html#serving-ara-sqlite-databases-over-http
[2]: https://github.com/ansible/ansible/pull/31200

0.14.4 (2017-09-20)

https://github.com/ansible-community/ara/releases/tag/0.14.4

0.14.4 adds Ansible 2.4 support for ARA.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL schema.
         Please see this blog post [1] for details.
***

Changelog:
- Add support for Ansible 2.4

0.14.3 (2017-09-17)

https://github.com/ansible-community/ara/releases/tag/0.14.3

0.14.3 is a minor bugfix release for ARA.
Note that ARA does not yet support Ansible 2.4.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL schema.
         Please see this blog post [1] for details.
***

Changelog:
- Bugfix: 'include_role' tasks with 'static: no' are now handled properly
  (See Ansible issue: https://github.com/ansible/ansible/issues/30385 )
- Backport from 1.0: 404 not found errors when generating static reports will
  now be ignored as they are non-fatal.
- Ansible was pinned to <2.4, ARA does not yet support Ansible 2.4.
- Pygments was pinned to >=1.6, prior versions did not have the required
  JSONLexer methods.
- Flask was pinned to >=0.11, prior versions did not provide the
  flask_logging.DEBUG_LOG_OUTPUT variable. The version prior to 0.11 was released
  in 2013.

0.14.2 (2017-08-29)

https://github.com/ansible-community/ara/releases/tag/0.14.2

Bugfix: "logging.config" also needed to be imported for
        the new file configuration option to work properly.

0.14.1 (2017-08-27)

https://github.com/ansible-community/ara/releases/tag/0.14.1

0.14.1 is a minor bugfix release for ARA.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL schema.
         Please see this blog post [1] for details.
***

Changelog:
- Bugfix: Implicit tasks with no specific file and task
  information provided by Ansible (such as "gather_facts")
  now resolve back to the playbook file by default. See upstream
  Ansible bug [2] for details.

- Feature: Logging for ARA and it's components can now be done
  through a logging configuration file [3].

- Integration tests on Fedora 26 with python3.6 were
  added to the existing tests under CentOS 7 and
  Ubuntu 16.04.

[1]: https://dmsimard.com/2017/08/16/whats-coming-in-ara-1.0/
[2]: https://github.com/ansible/ansible/issues/28451
[3]: https://ara.readthedocs.io/en/latest/configuration.html#ara-log-config

0.14.0 (2017-07-31)

https://github.com/ansible-community/ara/releases/tag/0.14.0

0.14.0 is a major release for ARA which brings significant changes
and introduces full Python 3 support with Ansible 2.3.x.

***
WARNING: Please note that the next major version of ARA, 1.0, will contain
         backwards incompatible changes due to significant refactor work
         involving core back end code as well as the SQL schema.
***

Changelog for 0.14.0 (up from 0.13.3):

New features:
- Python 3 now works and is supported
  - All unit and integration tests are passing on python 3
  - New code contributions to ARA are simultaneously gated against py2
    and py3 tests to avoid regressions
- Added the 'ara generate subunit' [1] command in order to export playbook
  run data to the subunit format

Improvements:
- Host facts, task results and records display has been improved with
  highlighting where appropriate
- Addressed a backwards database schema relationship between files and
  tasks (no migration required)

Updates and deprecations:
- Flask has been unpinned from 0.11.1 (latest release is currently 0.12.2)
- Ansible 2.1.x is no longer supported (end of life and out of support upstream as well)
- A regression in unit tests was fixed in order to allow us to unpin Pytest

Docs:
- Improve FAQ on what versions of Ansible are supported [2]
- Added a FAQ on the status of Python 3 support [3]

Misc:
- Preliminary work in order to support the upcoming release of Ansible (2.4)
- ARA has been relicensed from Apache 2.0 to GPLv3 to simplify it's
  relationship with Ansible which is itself GPLv3. Rationale behind the
  change is available in the commit [4]

Special thanks
- Lars Kellogg-Stedman for help on python 3 and database schema troubleshooting
- Jesse Pretorius for contributing support for Subunit generation

[1]: https://ara.readthedocs.io/en/latest/usage.html#generating-a-static-subunit-version-of-the-task-results
[2]: https://ara.readthedocs.io/en/latest/faq.html#what-versions-of-ansible-are-supported
[3]: https://ara.readthedocs.io/en/latest/faq.html#does-ara-support-running-on-python-3
[4]: https://review.openstack.org/#/c/486733/

0.13.3 (2017-06-30)

https://github.com/ansible-community/ara/releases/tag/0.13.3

This release addresses a regression introduced in 0.13.2
where files would no longer be displayed correctly and would
instead show raw HTML.

0.13.2 (2017-06-22)

https://github.com/ansible-community/ara/releases/tag/0.13.2

This is a minor feature/bugfix release for ARA.

Changelog:
- Security: Use the 'escape' jinja2 filter instead of the
  'safe' filter to escape potentially problematic HTML
  characters and prevent them from being interpreted.

- ara_record can now be used as a standalone task outside
  the context of a playbook run to, for example, record data
  on a playbook run that has already been completed.
  An example use case is to attach the ansible-playbook run
  stdout as a record of the playbook [1][2].
  More details is available in the documentation [3].

- ara_record now returns the equivalent of ara_read when
  registering the task where ara_record runs. This avoids
  needing to run ara_read if you don't need to.

Misc:
- Unit test fixes after the release of Ansible 2.3.1
- Work and testing against Ansible Devel (unreleased 2.4) has started

[1]: https://github.com/openstack/ara/blob/a72ece2e7ab69cd4e2882ba207152703b2bc0a90/run_tests.sh#L95-L96
[2]: https://github.com/openstack/ara/blob/a72ece2e7ab69cd4e2882ba207152703b2bc0a90/run_tests.sh#L130
[3]: http://ara.readthedocs.io/en/latest/usage.html#using-the-ara-record-module

0.13.1 (2017-05-21)

https://github.com/ansible-community/ara/releases/tag/0.13.1

This is a minor release to fix the warning that Alembic
0.9.2 started introducing during SQL migrations.

The "About" page has also been improved.

0.13.0 (2017-05-04)

https://github.com/ansible-community/ara/releases/tag/0.13.0

ARA 0.13.0 marks a new major release for ARA, dropping deprecations
and modifying your database schema with automated migrations.

Please read the release notes and back up your database just in
case before upgrading.

General / UI
============
- The home page has been relocated to "about" and the default home
  page is now the report list.
- Playbooks reports now have permanent links.
  Use the blue chain icon on the left hand side of the report list.
- Host facts, files and task results now have permanent links.
  Use the blue chain icon on the top right of the popups.
- Note: Permanent links have slightly grown the weight and amount
  of files generated in a static report but has no significant impact on
  generation time.
- Browsing tips have been improved and folded into "?" tooltips
  inside each panel.
- The file panel was improved to show a file browser interface
  instead of a file list.
- There is a new panel, "Parameters", which contains all parameters
  used as part of your ansible-playbook commands.
- Role names are now included when recording task results, this means
  you can now search for the role name in your task result list.
- Task tags are now included when recording task results, this means
  you can now search for the tag name in your task result list.
- Task results that are provided from a loop (ex: with_items) are now
  properly saved and displayed.
  Note that an upstream Ansible issue can make it so the last item in a
  loop is someetimes not saved (Ansible issue #24207)
- There has been some level of performance improvements which may
  be more noticeable on larger deployments.
- Fixed an issue where tooltips would sometime not display properly
  in the hosts table.
- Fixed an issue that would cause "include" tasks to be recorded and
  displayed twice by ARA on Ansible >= 2.2.
- External CSS and JS libraries are no longer bundled with ARA and
  we now used packaged versions with python-XStatic.
- The UI has been resized a bit in general to be less of a problem on
  larger resolutions (>=1920px wide)

Configuration
=============
- New parameter: ARA_HOST to select the host to bind on default
  with the embedded development web server. (Defaults to '127.0.0.1')
- New parameter: ARA_PORT to select the port on which the
  embedded development web server will listen on. (Defaults to '9191')
- The embedded development web server will now use threads by
  default, improving performance significantly.
- New parameter: ARA_IGNORE_PARAMETERS to avoid saving
  potentially sensitive data when recording ansible-playbook command
  line parameters. (Defaults to 'extra_vars')

Database
========
- There is a new SQL migration to provide the necessary schema for
  ansible metadata (ansible-playbook parameters) as well as task tags.
- Fixed a bad migration statement for a column in the table 'data'

Deprecations and removals
=========================
- The command "ara generate" has been removed, it was deprecated
  and replaced by "ara generate html" in ARA 0.11.
- The URLs under /playbook/ have been removed, they were deprecated
  and redirected to the new playbook reports page in ARA 0.12.

Distribution packaging and unbundling
=====================================
ARA no longer carries in-tree external CSS and JS libraries (jquery,
jquery-datatables, patternfly, patternfly-bootstrap-treeview, bootstrap).
For that effort:
- We've packaged and created new packages on PyPi for missing
  python-XStatic libraries: patternfly, patternfly-bootstrap-treeview
- We've updated the python-XStatic package for jquery-datatables on
  PyPi

ARA 0.13 will be the first version to be packaged for RHEL-derivative
distributions. For that effort we've packaged new packages for Fedora
and EPEL:
- python-xstatic-patternfly
- python-xstatic-patternfly-bootstrap-treeview
- python-xstatic-datatables
- python-pyfakefs

0.12.5 (2017-04-19)

https://github.com/ansible-community/ara/releases/tag/0.12.5

0.12.5 is a small maintenance release.

Changelog:
- Fix encoding/decoding issues when using non-ascii characters
  in playbooks and improve integration testing for this kind of
  problem.
- The full playbook path is no longer printed in the table.
  The playbook path turned out to be too long and truncated most of
  the time. Only the file name is shown now. The full path is still
  available in the tooltip when hovering over the playbook file name.
- Improved performance for the reports page, especially when viewing
  playbook runs with a larger amount of data.
- Considerably reduced package/module size on disk

0.12.4 (2017-04-01)

https://github.com/ansible-community/ara/releases/tag/0.12.4

0.12.4 is primarily a maintenance/bugfix release.

Callback changes:
- Task results as recorded by ARA are now "filtered" by Ansible's
  _dump_results method [1]. This will only be effective on task recording
  moving forward, it will not edit previously recorded playbooks.
  The _dump_results method strips Ansible 'internal' keys (_ansible_*)
  from the task results and also respects the 'no_log: yes' task directive.
  Prior to this change, ARA did not respect the no_log directive and
  recorded the raw task results as well as all the Ansible internal keys.
  Task results should be cleaner now and be properly censored when using
  'no_log'.
  This ultimately results in what is hopefully less unnecessary things
  in the task results and the net effect should be positive.

Internal changes:
- Refactor of ARA's configuration module to fix issues in order to properly
  detect configuration parameters like booleans or lists. This refactor
  also brings cleaner backwards and forwards compatibility from Ansible 2.1
  through 2.3.
- Fixed issue to prevent PBR from throwing exceptions when overriding the
  version
- Different changes in both the CLI and the testing framework in order to
  bootstrap and teardown the application properly to prevent context from
  leaking where it shouldn't be

UI changes:
- Javascript datatables in the UI where most of the content is displayed
  will now throw warnings in the background (javascript console) rather
  than in the foreground (javascript alert). These warnings are fairly
  expected, especially in the case of incomplete or interrupted playbooks.
- Adjust wording when notifying users about a playbook that is incomplete
  or was interrupted to make it more straightforward
- Performance improvements on the home and reports page, more optimization
  will follow in the future.
- Fixed an odd problem where certain webservers (ex: nginx) would not behave
  well for the statically generated version of the reports.

CLI changes:
- The "ara generate html" command will now suppress
  "MissingURLGeneratorWarning" warnings by default. A new configuration
  parameter 'ignore_empty_generation' was introduced to revert back to
  the previous behavior. For context on this change, see the commit [2].
- Alembic messages that are not related to migrations are now sent to the
  background.

Database:
- Fix PosgreSQL support, add documentation for using it it and provide
  instructions for integration testing it

Documentation:
- The project now has a manifesto [3] to express in writing the project's core
  values and philosophy
- Improved contributor documentation
- Added a FAQ on running the ARA callback and the web application on
  different machines

[1]: https://github.com/ansible/ansible/blob/b3251c9585b0b0180fcdf09748e9a0dc439bc1aa/lib/ansible/plugins/callback/__init__.py
[2]: http://git.openstack.org/cgit/openstack/ara/commit/?id=440dac3789ca12c50f63a89850a7e65c1ac93789
[3]: http://ara.readthedocs.io/en/latest/manifesto.html

0.12.3 (2017-03-09)

https://github.com/ansible-community/ara/releases/tag/0.12.3

This is a bugfix release for the 0.12 series.
It includes two fixes for the data and tooltips in the
host panel to display properly.

0.12.2 (2017-03-07)

https://github.com/ansible-community/ara/releases/tag/0.12.2

This is a minor release that aims to significantly improve
web application performance on large scale deployments of
ARA, tested against hundreds of playbooks composed of hundreds
of thousands of tasks, task results and files.

This is achieved by deferring the bulk of the data loading
and processing to AJAX calls in the background.

0.12.1 (2017-03-03)

https://github.com/ansible-community/ara/releases/tag/0.12.1

This is a small bugfix release to ensure pages from
pagination can be detected as html mimetype.

0.12.0 (2017-03-01)

https://github.com/ansible-community/ara/releases/tag/0.12.0

This is a major release which features a complete
rewrite of the web application interface.

The home page now highlights the data recorded by ARA
and the core of the UI now revolves around the one and
single playbook reports page.

There were three main objectives with this UI work:
- Improve UX (ex: being able to search, find & sort things easily
  * Everything is now searchable and sortable
  * Browsing tips have been added to help users get the most out
    of the interface features

- Improve scalability and performance: the interface should be
  fast and easy to browse whether you have dozens or thousands
  of hosts and tasks
  * Every result list or table are now paginated
  * You can customize pagination preferences with the
    ARA_PLAYBOOK_PER_PAGE and ARA_RESULT_PER_PAGE
    configuration parameters.

- Improve static generation time and weight
  Examples of the same data sets before and after:
  * ARA integration tests (5 playbooks, 59 tasks, 69 results):
    * Before: 5.4 seconds, 1.6MB (gzipped), 217 files
    * After: 2 seconds, 1.2MB (gzipped), 119 files
  * OpenStack-Ansible (1 playbook, 1547 tasks, 1667 results):
    * Before: 6m21 seconds, 31MB (gzipped), 3710 files
    * After: 20 seconds, 8.9MB (gzipped), 1916 files

Other features and fixes include:
- First party WSGI support [1]
- Fixed syntax highlighting support when viewing files
- Preparations for supporting the upcoming Ansible 2.3 release
- Preparations for full python 3 support
- Various performance improvements

Misc:
- Jinja HTML templates are now fully indented with no regards
  to line length or PEP8 to privilege readability over long and
  nested content.
- Added some missing web application unit tests
- Various javascript and css optimizations
- The web application backend in itself was significantly
  simplified: less routes, less templates, less code
- Added a configuration parameter ARA_PLAYBOOK_PER_PAGE which
  controls the amount of playbooks per page in the playbook
  report list.
- Added a configuration parameter ARA_RESULT_PER_PAGE which
  controls the amount of results per page in the data results
  table (such as hosts, plays and tasks).

Known issues:
- The file list table in the file panel will eventually
  be replaced by a folder/file hierarchy tree

[1]: http://ara.readthedocs.io/en/latest/webserver.html

0.11.0 (2017-02-13)

https://github.com/ansible-community/ara/releases/tag/0.11.0

- New feature: ARA UI and Ansible version (ARA UI is running with)
  are now shown at the top right
- New feature: The Ansible version a playbook was run is now stored
  and displayed in the playbook reports
- New feature: New command: "ara generate junit": generates a junit
  xml stream of all task results
- New feature: ara_record now supports two new types: "list" and "dict",
  each rendered appropriately in the UI
- UI: Add ARA logo and favicon
- UI: Left navigation bar was removed (top navigation bar will be
  further improved in future versions)
- Bugfix: CLI commands could sometimes fail when trying to format
  as JSON or YAML
- Bugfix: Database and logs now properly default to ARA_DIR if ARA_DIR
  is changed
- Bugfix: When using non-ascii characters (ex: äëö) in playbook files,
  web application or static generation could fail
- Bugfix: Trying to use ara_record to record non strings
  (ex: lists or dicts) could fail
- Bugfix: Ansible config: 'tmppath' is now a 'type_value' instead of a
  boolean
- Deprecation: The "ara generate" command was deprecated and moved to
  "ara generate html"
- Deprecation: The deprecated callback location, ara/callback has been
  removed. Use ara/plugins/callbacks.
- Misc: Various unit and integration testing coverage improvements and
  optimization
- Misc: Slowly started working on full python 3 compatibility

0.10.5 (2017-01-16)

https://github.com/ansible-community/ara/releases/tag/0.10.5

Ansible 2.2.1.0 shipped with a hard dependency on Jinja2 < 2.9 [1].
Since Flask has a requirement on Jinja2 >= 2.4, it would pick up
2.9.4 first and then disregard Ansible's requirement.

[1]: https://github.com/ansible/ansible/commit/6c6570583f6e74521e3a4f95fe42ffddb69634fe

0.10.4 (2017-01-15)

https://github.com/ansible-community/ara/releases/tag/0.10.4

New feature:

- Playbook lists now have an icon to display their
  status, whether it has been completed or not
  and if it has been successful or not.

Bug fixes/maintenance:

- Fix SyntaxError when creating ARA directory
  under Python3
- Update static patternfly assets to 3.17.0
- Fixed some bad logic in integration tests in order
  to properly test different versions of Ansible

0.10.3 (2016-12-12)

https://github.com/ansible-community/ara/releases/tag/0.10.3

This is a minor release that continues ongoing efforts
to streamline some things in order to package ARA for
linux distributions.

Flask-Testing is no longer a dependency and tests have
been rewritten accordingly.

0.10.2 (2016-12-10)

https://github.com/ansible-community/ara/releases/tag/0.10.2

This is a minor release to streamline some things in
order to package ARA for linux distributions.

- pymysql is no longer installed by default
- tests are now shipped inside the module
- misc fixes (pep8, bandit)

0.10.1 (2016-12-05)

https://github.com/ansible-community/ara/releases/tag/0.10.1

This is a bugfix release that resolves an issue that made
it impossible to use MySQL (and potentially other RDBMS).

For more details, see commit [1].

[1]: https://git.openstack.org/cgit/openstack/ara/commit/?id=dd159df4f0c152d28455fedf6c6f1e0b56cd7350

0.10.0 (2016-12-01)

https://github.com/ansible-community/ara/releases/tag/0.10.0

This is a major release.
For the full list of changes between 0.9.3 and 0.10.0, please
view the list of commits on GitHub [1].

Summary:
- Database schema is now stable and automatically migrated.
  Databases created on >= 0.9.0 are supported.
- Significant web interface improvements
- New built-in Ansible modules: ara_record and ara_read for
  recording arbitrary data with ARA
- Improved unit and integration testing coverage

[1]: https://github.com/openstack/ara/compare/0.9.3...0.10.0

0.9.3 (2016-11-14)

https://github.com/ansible-community/ara/releases/tag/0.9.3

0.9.2 (2016-10-22)

https://github.com/ansible-community/ara/releases/tag/0.9.2

This is a maintenance release.

- Update static assets to their latest versions
  (Patternfly, Flask, etc.)
- The location of the callback has been changed from
  ara/callback to ara/plugins/callbacks/. The previous
  location has been deprecated and will be removed in
  a future version.
- Bugfix: The home link in the navigation now behaves
  more as expected and redirect to the root of the web
  application rather than the root of the domain or
  filesystem.
- Misc: Integration test coverage improvements

0.9.1 (2016-09-15)

https://github.com/ansible-community/ara/releases/tag/0.9.1

- Introduced a parameter (defaulting to true) to hide warnings
  introduced in 0.9.0 that are safe to ignore.

0.9.0 (2016-09-13)

https://github.com/ansible-community/ara/releases/tag/0.9.0

- ARA is now hosted by the OpenStack project community infrastructure.
  - ARA's source code is now available at:
    https://git.openstack.org/cgit/openstack/ara
    or mirrored at
    https://github.com/openstack/ara
  - Submitting patches is now done through OpenStack's Gerrit
    system.
    Documentation on how to contribute is available at
    http://ara.readthedocs.io/en/latest/contributing.html
  - Unit and integration testing is no longer done through
    Travis but instead by OpenStack Zuul testing infrastructure.

- UI Revamp: First implementation
  This is the first release in which lands a first implementation of
  a large UI revamp with the Patternfly [1] CSS framework. There are
  some small issues and quirks but we will iterate in order to fix
  them.

- Playbook file storage
  ARA now stores a unique, zipped copy of playbook files allowing you
  to see the content of your task files as they ran in a particular
  ansible-playbook run. The UI leverages that feature and also provides
  a direct link with line highlight to show where a particular action
  took place.

[1]: https://www.patternfly.org/

0.8.1 (2016-06-03)

https://github.com/ansible-community/ara/releases/tag/0.8.1

This reverts commit 00673c1cf231dbd3058ca187295e67e39f6c9fff.
2.1 has a regression [1] that breaks ARA and 2.0.2.0 had other
regressions we are not interested in.

[1]: https://github.com/ansible/ansible/issues/16125

0.8.0 (2016-06-02)

https://github.com/ansible-community/ara/releases/tag/0.8.0

stop catching bare Exceptions

0.7.1 (2016-05-30)

https://github.com/ansible-community/ara/releases/tag/0.7.1

Temporarily pin flask

0.7.0 (2016-05-27)

https://github.com/ansible-community/ara/releases/tag/0.7.0

Try really hard to pretty print json-looking results

0.6.0 (2016-05-21)

https://github.com/ansible-community/ara/releases/tag/0.6.0

0.5.2 (2016-05-18)

https://github.com/ansible-community/ara/releases/tag/0.5.2

0.5.1 (2016-05-17)

https://github.com/ansible-community/ara/releases/tag/0.5.1

iterate over results containing multiple items

0.5.0 (2016-05-14)

https://github.com/ansible-community/ara/releases/tag/0.5.0

Merge development work

0.4.0 (2016-05-10)

https://github.com/ansible-community/ara/releases/tag/0.4.0

0.3.1 (2016-05-09)

https://github.com/ansible-community/ara/releases/tag/0.3.1

This isn't a proper configuration file yet but will allow to
transition toward that goal while improving configurability with
very low effort.

0.3 (2016-05-09)

https://github.com/ansible-community/ara/releases/tag/0.3

- Properly support browsing multiple playbook runs in /playbook
- Add run info at the top
- Minor tweaks to models, effectively just add foreign keys on
  playbook_uuid for sanity

0.2 (2016-05-09)

https://github.com/ansible-community/ara/releases/tag/0.2

0.1 (2016-05-08)

https://github.com/ansible-community/ara/releases/tag/0.1