Metadata-Version: 2.1
Name: ara
Version: 1.5.2
Summary: ARA Records Ansible
Home-page: https://github.com/ansible-community/ara
Author: OpenStack Community
Author-email: openstack-discuss@lists.openstack.org
License: UNKNOWN
Description: ARA Records Ansible
        ===================
        
        ARA Records Ansible playbooks and makes them easier to understand and troubleshoot.
        
        .. image:: doc/source/_static/ara-with-icon.png
        
        How it works
        ============
        
        ARA Records Ansible playbook execution results to local or remote databases by
        using an Ansible `callback plugin <https://docs.ansible.com/ansible/latest/plugins/callback.html>`_.
        
        This callback plugin leverages built-in python API clients to send data to a
        REST API server where data and metrics are made available for querying,
        browsing, monitoring or for integration in other tools and interfaces.
        
        .. image:: doc/source/_static/graphs/recording-workflow.png
        
        What it looks like
        ==================
        
        API browser
        -----------
        
        Included by the API server with django-rest-framework, the API browser allows
        users to navigate the different API endpoints and query recorded data.
        
        .. image:: doc/source/_static/ui-api-browser.png
        
        Reporting interface
        -------------------
        
        A simple reporting interface built-in to the API server without any extra
        dependencies.
        
        .. image:: doc/source/_static/ui-playbook-details.png
        
        ara CLI
        -------
        
        A built-in CLI client for querying and managing playbooks and their recorded data.
        
        .. image:: doc/source/_static/cli-playbook-list.png
        
        The full list of commands, their arguments as well as examples can be found in
        the `CLI documentation <https://ara.readthedocs.io/en/latest/cli.html#cli-ara-api-client>`_.
        
        ara-web
        -------
        
        A project that is a work in progress and would appreciate contributions,
        `ara-web <https://github.com/ansible-community/ara-web>`_ is a stateless
        javascript interface to the API built with react and patternfly.
        
        .. image:: doc/source/_static/ui-ara-web.png
        
        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
        
        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 <https://github.com/ansible-community/ara/issues/99>`_ 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:
        
        .. code-block:: bash
        
            # 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 <https://hub.docker.com/r/recordsansible/ara-api>`_:
        
        .. code-block:: bash
        
            # 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:
        
        .. code-block:: bash
        
            # 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 in the `documentation <https://ara.readthedocs.io/en/latest/container-images.html>`_.
        
        Live demo
        =========
        
        Deployments of the ARA API server and ara-web are available for demonstration
        and test purposes:
        
        - https://api.demo.recordsansible.org
        - https://web.demo.recordsansible.org
        
        These live demos are deployed using the ara_api and ara_web Ansible roles from the ara Ansible collection:
        https://github.com/ansible-community/ara-collection
        
        Documentation
        =============
        
        Documentation for installing, configuring, running and using ARA is
        available on `readthedocs.io <https://ara.readthedocs.io>`_.
        
        Community and getting help
        ==========================
        
        - Bugs, issues and enhancements: https://github.com/ansible-community/ara/issues
        - IRC: #ara on `Freenode <https://webchat.freenode.net/?channels=#ara>`_
        - Slack: https://arecordsansible.slack.com (`invitation link <https://join.slack.com/t/arecordsansible/shared_invite/enQtMjMxNzI4ODAxMDQxLTU2NTU3YjMwYzRlYmRkZTVjZTFiOWIxNjE5NGRhMDQ3ZTgzZmQyZTY2NzY5YmZmNDA5ZWY4YTY1Y2Y1ODBmNzc>`_)
        
        - Website and blog: https://ara.recordsansible.org
        - Twitter: https://twitter.com/recordsansible
        
        Contributing
        ============
        
        Contributions to the project are welcome and appreciated !
        
        Get started with the `contributor's documentation <https://ara.readthedocs.io/en/latest/contributing.html>`_.
        
        Authors
        =======
        
        Contributors to the project can be viewed on
        `GitHub <https://github.com/ansible-community/ara/graphs/contributors>`_.
        
        Copyright
        =========
        
        ::
        
            Copyright (c) 2020 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/>.
        
        
Platform: UNKNOWN
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Development Status :: 5 - Production/Stable
Provides-Extra: postgresql
Provides-Extra: server
Provides-Extra: test
