1.0 backport: Add helper modules/scripts to know where ARA is

The location where ARA is installed is hard to predict because it will
depend on the operating system, python2 vs python3 or the usage of
virtualenvs, for example.

That's why we have this rather convenient snippet:
python -c "import os,ara; print(os.path.dirname(ara.__file__))"

This snippet is now further reduced to:
python -m ara.setup.path

But there is also many other variants such as:
- python -m ara.setup.path
- python -m ara.setup.callback_plugins
- python -m ara.setup.action_plugins
- python -m ara.setup.library
- python -m ara.setup.env
- python -m ara.setup.ansible

These can also be imported as such:

from ara.setup import path
from ara.setup import callback_plugins
[...]

This might be expanded upon later but let's stop at this for now.

Change-Id: Ibf1eb495ea0df2f6d8589abeb2220b6e93afdea9
(cherry picked from commit f1e4b5d521)
This commit is contained in:
David Moreau Simard 2017-11-24 14:07:36 -05:00
parent b030fb097e
commit 001ed74273
No known key found for this signature in database
GPG Key ID: 33A07694CBB71ECC
12 changed files with 253 additions and 31 deletions

5
ara/setup/README.rst Normal file
View File

@ -0,0 +1,5 @@
This directory contains scripts meant to help configuring ARA with Ansible.
For more information, visit the documentation_.
.. _documentation: http://ara.readthedocs.io/en/latest/configuration.html

25
ara/setup/__init__.py Normal file
View File

@ -0,0 +1,25 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
import os
# The path where ARA is installed (parent directory)
path = os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
action_plugins = os.path.abspath(os.path.join(path, 'plugins/actions'))
callback_plugins = os.path.abspath(os.path.join(path, 'plugins/callbacks'))
library = os.path.abspath(os.path.join(path, 'plugins/modules'))

View File

@ -0,0 +1,22 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
from __future__ import print_function
from . import action_plugins
if __name__ == "__main__":
print(action_plugins)

29
ara/setup/ansible.py Normal file
View File

@ -0,0 +1,29 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
from __future__ import print_function
from . import callback_plugins, action_plugins, library
config = """
[defaults]
callback_plugins={}
action_plugins={}
library={}
""".format(callback_plugins, action_plugins, library)
if __name__ == "__main__":
print(config.strip())

View File

@ -0,0 +1,22 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
from __future__ import print_function
from . import callback_plugins
if __name__ == "__main__":
print(callback_plugins)

28
ara/setup/env.py Normal file
View File

@ -0,0 +1,28 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
from __future__ import print_function
from . import callback_plugins, action_plugins, library
exports = """
export ANSIBLE_CALLBACK_PLUGINS={}
export ANSIBLE_ACTION_PLUGINS={}
export ANSIBLE_LIBRARY={}
""".format(callback_plugins, action_plugins, library)
if __name__ == "__main__":
print(exports.strip())

22
ara/setup/library.py Normal file
View File

@ -0,0 +1,22 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
from __future__ import print_function
from . import library
if __name__ == "__main__":
print(library)

22
ara/setup/path.py Normal file
View File

@ -0,0 +1,22 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
from __future__ import print_function
from . import path
if __name__ == "__main__":
print(path)

View File

@ -0,0 +1,29 @@
# Copyright (c) 2017 Red Hat, Inc.
#
# This file is part of ARA: Ansible Run Analysis.
#
# ARA 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 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. If not, see <http://www.gnu.org/licenses/>.
from ara.tests.unit.common import TestAra
class TestSetup(TestAra):
""" Tests the utils module """
def setUp(self):
super(TestSetup, self).setUp()
def tearDown(self):
super(TestSetup, self).tearDown()
# TODO: Add tests :D

View File

@ -12,39 +12,47 @@ To begin using ARA, you'll first need to set up Ansible so it knows about the
the ARA :ref:`callback <faq_callback>` and, if necessary, the :ref:`ara_record <ara_record>` and :ref:`ara_read <ara_read>` modules.
The callback and modules are bundled when installing ARA but you need to know
where they have been installed in order to let Ansible know where they are located.
where they have been installed in order to let Ansible know where they are
located.
.. tip::
This location will be different depending on your operating system, how you are
installing ARA and whether you are using Python 2 or Python 3.
The location where ARA will be depends on your operating system and how it
is installed.
Here's some examples of where ARA can be found:
ARA ships a set of convenience Python modules to help you configure Ansible to
use it.
- ``/usr/lib/python2.7/site-packages/ara``
- ``/usr/lib/python3.5/site-packages/ara``
- ``$VIRTUAL_ENV/lib/python2.7/site-packages/ara``
They can be used like so::
If you're not sure where ARA will end up being installed, you can use this
snippet to print its location. It works in both Python 2 and Python 3::
$ python -m ara.setup.path
/usr/lib/python2.7/site-packages/ara
python -c "import os,ara; print(os.path.dirname(ara.__file__))"
$ python -m ara.setup.action_plugins
/usr/lib/python2.7/site-packages/ara/plugins/actions
$ python -m ara.setup.callback_plugins
/usr/lib/python2.7/site-packages/ara/plugins/callbacks
$ python -m ara.setup.library
/usr/lib/python2.7/site-packages/ara/plugins/modules
Using ansible.cfg
~~~~~~~~~~~~~~~~~
Set up your `ansible.cfg`_ file to seek the callback and modules in the appropriate
directories::
This sets up a new `ansible.cfg`_ file to load the callbacks and modules from
the appropriate locations::
$ export ara_location=$(python -c "import os,ara; print(os.path.dirname(ara.__file__))")
$ cat > ansible.cfg <<EOF
$ python -m ara.setup.ansible | tee ansible.cfg
[defaults]
# callback_plugins configuration is required for the ARA callback
callback_plugins = $ara_location/plugins/callbacks
callback_plugins=/usr/lib/python2.7/site-packages/ara/plugins/callbacks
action_plugins=/usr/lib/python2.7/site-packages/ara/plugins/actions
library=/usr/lib/python2.7/site-packages/ara/plugins/modules
# action_plugins and library configuration is required for the ara_record and ara_read modules
action_plugins = $ara_location/plugins/actions
library = $ara_location/plugins/modules
EOF
Or alternatively, if you have a customized `ansible.cfg`_ file, you can retrieve
only what you need using the other helpers such as the following:
- ``python -m ara.setup.callback_plugins``
- ``python -m ara.setup.action_plugins``
- ``python -m ara.setup.library``
.. _ansible.cfg: https://docs.ansible.com/ansible/intro_configuration.html#configuration-file
@ -53,12 +61,16 @@ Using environment variables
Depending on the context and your use case, configuring Ansible using
`environment variables`_ instead of an ``ansible.cfg`` file might be more convenient.
Here's how you can set up Ansible to seek out ARA's callback and modules::
$ export ara_location=$(python -c "import os,ara; print(os.path.dirname(ara.__file__))")
$ export ANSIBLE_CALLBACK_PLUGINS=$ara_location/plugins/callbacks
$ export ANSIBLE_ACTION_PLUGINS=$ara_location/plugins/actions
$ export ANSIBLE_LIBRARY=$ara_location/plugins/modules
ARA provides a helper module that prints out the necessary export commands::
$ python -m ara.setup.env
export ANSIBLE_CALLBACK_PLUGINS=/usr/lib/python2.7/site-packages/ara/plugins/callbacks
export ANSIBLE_ACTION_PLUGINS=/usr/lib/python2.7/site-packages/ara/plugins/actions
export ANSIBLE_LIBRARY=/usr/lib/python2.7/site-packages/ara/plugins/modules
Note that the module doesn't actually run those exports, you'll want to run them
yourself, add them in a bash script or a bashrc, etc.
.. _environment variables: https://docs.ansible.com/ansible/intro_configuration.html#environmental-configuration

View File

@ -166,8 +166,6 @@ Documentation tests::
Integration tests:
::
At the root of the ARA source, you'll find the ``run_tests.sh`` script that
allows you to easily run integration tests across a range of different
configurations.

View File

@ -108,10 +108,18 @@ if [[ $ARA_TEST_PGSQL == 1 ]]; then
pip install psycopg2
fi
# TODO: Improve the testing of those
echo "python -m ara.setup.path: $(python -m ara.setup.path)"
echo "python -m ara.setup.callback_plugins: $(python -m ara.setup.callback_plugins)"
echo "python -m ara.setup.action_plugins: $(python -m ara.setup.action_plugins)"
echo "python -m ara.setup.library: $(python -m ara.setup.library)"
echo "python -m ara.setup.env: $(python -m ara.setup.env)"
echo "python -m ara.setup.ansible: $(python -m ara.setup.ansible)"
# Setup ARA
export ANSIBLE_CALLBACK_PLUGINS="ara/plugins/callbacks"
export ANSIBLE_ACTION_PLUGINS="ara/plugins/actions"
export ANSIBLE_LIBRARY="ara/plugins/modules"
export ANSIBLE_CALLBACK_PLUGINS="$(python -m ara.setup.callback_plugins)"
export ANSIBLE_ACTION_PLUGINS="$(python -m ara.setup.action_plugins)"
export ANSIBLE_LIBRARY="$(python -m ara.setup.library)"
export ARA_DATABASE="${DATABASE}"
# Run linters