6d00938099
This makes it so "pip install ara" would only install a minimal amount of dependencies (pbr and requests as of this commit) required for running the Ansible callback plugin as well as ara_record. The server dependencies can be installed by running "pip install ara[server]". Fixes: https://github.com/ansible-community/ara/issues/36 Change-Id: I67769d28ec24cade7753230dffd0b049358af29a
139 lines
4.6 KiB
ReStructuredText
139 lines
4.6 KiB
ReStructuredText
ARA Records Ansible
|
|
===================
|
|
|
|
.. image:: doc/source/_static/ara-with-icon.png
|
|
|
|
ARA Records Ansible playbook runs and makes the recorded data available and
|
|
intuitive for users and systems.
|
|
|
|
The project provides several distinct components in order to make this happen:
|
|
|
|
- An API server for sending and querying data relative to playbook execution results
|
|
- An API client library for communicating with the API
|
|
- An Ansible callback plugin to record events as they happen throughout the execution
|
|
- An Ansible action module to associate arbitrary key/values to your playbook reports
|
|
|
|
Quickstart
|
|
==========
|
|
|
|
Here's how you can get started from scratch with default settings:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Create a virtual environment and activate it so we don't conflict
|
|
# with system or distribution packages
|
|
python3 -m venv ~/.ara/virtualenv
|
|
source ~/.ara/virtualenv/bin/activate
|
|
|
|
# Install Ansible, ARA and it's API server dependencies
|
|
pip install ansible git+https://github.com/openstack/ara@feature/1.0[server]
|
|
|
|
# Tell Ansible to use the ARA callback plugin
|
|
export ANSIBLE_CALLBACK_PLUGINS="$(python -m ara.setup.callback_plugins)"
|
|
|
|
# Run your playbook as your normally would
|
|
ansible-playbook playbook.yml
|
|
|
|
The data will be saved in real time throughout the execution of the Ansible playbook.
|
|
|
|
What happens behind the scenes is that the ARA Ansible callback plugin used
|
|
the built-in API client to send the data to the API which then saved it to a
|
|
database located by default at ``~/.ara/server/ansible.sqlite``.
|
|
|
|
You're now ready to start poking at the API with the built-in
|
|
`API clients <https://ara.readthedocs.io/en/feature-1.0/api-usage.html>`_ !
|
|
|
|
If you'd like to have the ARA web reporting interface, take a look at
|
|
`ara-web <https://github.com/openstack/ara-web>`_.
|
|
|
|
Documentation
|
|
=============
|
|
|
|
Documentation for installing, configuring, running and using ara is
|
|
available on `readthedocs.io <https://ara.readthedocs.io/en/feature-1.0/>`_.
|
|
|
|
Community and getting help
|
|
==========================
|
|
|
|
You can chat with the ARA community on Slack and IRC.
|
|
The two are transparently bridged with teamchat_ which broadcasts messages from
|
|
one platform to the other.
|
|
|
|
In addition, you can also find ARA on Twitter: `@ARecordsAnsible <https://twitter.com/ARecordsAnsible>`_
|
|
|
|
**IRC**
|
|
|
|
- Server: `irc.freenode.net`_
|
|
- Channel: #ara
|
|
|
|
**Slack**
|
|
|
|
- https://arecordsansible.slack.com
|
|
- Join with the `Slack invitation <https://join.slack.com/t/arecordsansible/shared_invite/enQtMjMxNzI4ODAxMDQxLWU4MmZhZTI4ZjRjOTUwZTM2MzM3MzcwNDU1YzFmNzRlMzI0NTUzNDY1MWJlNThhM2I4ZTViZjUwZTRkNTBiM2I>`_
|
|
|
|
.. _teamchat: https://github.com/dmsimard/teamchat
|
|
.. _irc.freenode.net: https://webchat.freenode.net/
|
|
|
|
Development and testing
|
|
=======================
|
|
|
|
.. code-block:: bash
|
|
|
|
# Retrieve the source and check out the 1.0 branch
|
|
git clone https://github.com/openstack/ara
|
|
cd ara
|
|
git checkout feature/1.0
|
|
|
|
# Install tox from pip or from your distro packages
|
|
pip install tox
|
|
|
|
# Run Ansible integration tests with the latest version of Ansible
|
|
tox -e ansible-integration
|
|
|
|
# Run integration tests with a specific version of Ansible
|
|
# Note: tox will always use the latest version of Ansible to run the playbook which runs the tests.
|
|
# For example, if the latest version of Ansible is 2.7.9, it will use Ansible 2.7.9
|
|
# to install Ansible==2.6.15 in a virtual environment and 2.6.15 is what will be tested.
|
|
tox -e ansible-integration -- -e ara_tests_ansible_version=2.6.15
|
|
|
|
# Run integration tests with Ansible from source
|
|
tox -e ansible-integration -- -e "ara_tests_ansible_name=git+https://github.com/ansible/ansible"
|
|
|
|
# Run unit tests
|
|
tox -e py3
|
|
|
|
# Run linters (pep8, black, isort)
|
|
tox -e linters
|
|
|
|
# Run test server -> http://127.0.0.1:8000/api/v1/
|
|
tox -e runserver
|
|
|
|
# Build docs
|
|
tox -e docs
|
|
|
|
Contributors
|
|
============
|
|
|
|
See contributors on GitHub_.
|
|
|
|
.. _GitHub: https://github.com/openstack/ara/graphs/contributors
|
|
|
|
Copyright
|
|
=========
|
|
|
|
::
|
|
|
|
Copyright (c) 2019 Red Hat, Inc.
|
|
|
|
ARA Records Ansible is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation, either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
ARA Records Ansible is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with ARA Records Ansible. If not, see <http://www.gnu.org/licenses/>. |