diff --git a/README.rst b/README.rst index 604b9141..0bc4fe79 100644 --- a/README.rst +++ b/README.rst @@ -5,44 +5,124 @@ ARA Records Ansible playbooks and makes them easier to understand and troublesho .. image:: doc/source/_static/ara-with-icon.png -ARA saves playbook results to a local or remote database by using an Ansible -callback plugin and provides an API to integrate this data in tools and interfaces. +How it works +============ -This project provides ARA's Ansible plugins, the REST API server as well as -simple built-in web interfaces to browse the recorded data. +ARA saves Ansible playbook execution results to local or remote databases by +using an Ansible `callback plugin `_. -A stateless javascript client interface is provided by a different project, -`ara-web `_. +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. -Quickstart -========== +.. image:: doc/source/_static/graphs/recording-workflow.png -Here's how you can get started from scratch with sane defaults with python>=3.5: +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-search.png + +ara-web +------- + +A project that is a work in progress and would appreciate contributions, +`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 +=============== + +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 ARA and Ansible for the current user + # Install Ansible and ARA (with API server dependencies) for the current user python3 -m pip install --user ansible "ara[server]" - # Tell Ansible to use the ARA callback plugin + # Configure Ansible to use the ARA callback plugin export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)" - # Run your playbook - ansible-playbook playbook.yml + # Run an Ansible playbook + ansible-playbook playbook.yaml -If nothing went wrong, your playbook data should have been saved in a local -database at ``~/.ara/server/ansible.sqlite``. + # Start the built-in development server to browse recorded results + ara-manage runserver -You can take a look at the recorded data by running ``ara-manage runserver`` -and pointing your browser at http://127.0.0.1:8000/. +Recording playbooks with an API server +-------------------------------------- -That's it ! +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. -Live demos -========== +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. -You can find live demos deployed by the built-in ara_api_ and ara_web_ Ansible -roles at https://api.demo.recordsansible.org and https://web.demo.recordsansible.org. +Alternatively, the API server can also run from a container image such as the +one available on `DockerHub `_: + +.. code-block:: bash + + # Start an API server from the image on DockerHub: + mkdir -p ~/.ara/server + podman 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 + +Data will be available on the API server in real time as the playbook progresses +and completes. + +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. .. _ara_api: https://ara.readthedocs.io/en/latest/ansible-role-ara-api.html .. _ara_web: https://ara.readthedocs.io/en/latest/ansible-role-ara-web.html @@ -63,17 +143,25 @@ Community and getting help - Website and blog: https://ara.recordsansible.org - Twitter: https://twitter.com/arecordsansible -Contributors +Contributing ============ -See contributors on `GitHub `_. +Contributions to the project are welcome and appreciated ! + +Get started with the `contributor's documentation `_. + +Authors +======= + +Contributors to the project can be viewed on +`GitHub `_. Copyright ========= :: - Copyright (c) 2019 Red Hat, Inc. + 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 @@ -86,4 +174,4 @@ Copyright 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 . \ No newline at end of file + along with ARA Records Ansible. If not, see . diff --git a/doc/source/_static/ara-api-browser-root.png b/doc/source/_static/ara-api-browser-root.png deleted file mode 100644 index d2b100ec..00000000 Binary files a/doc/source/_static/ara-api-browser-root.png and /dev/null differ diff --git a/doc/source/_static/ara-with-icon.png b/doc/source/_static/ara-with-icon.png index 67953256..91981186 100755 Binary files a/doc/source/_static/ara-with-icon.png and b/doc/source/_static/ara-with-icon.png differ diff --git a/doc/source/_static/ara-api-browser-playbook.png b/doc/source/_static/ui-api-browser-playbook.png similarity index 100% rename from doc/source/_static/ara-api-browser-playbook.png rename to doc/source/_static/ui-api-browser-playbook.png diff --git a/doc/source/_static/ara-api-browser-playbooks.png b/doc/source/_static/ui-api-browser-playbooks.png similarity index 100% rename from doc/source/_static/ara-api-browser-playbooks.png rename to doc/source/_static/ui-api-browser-playbooks.png diff --git a/doc/source/_static/ui-api-browser.png b/doc/source/_static/ui-api-browser.png new file mode 100644 index 00000000..59435f08 Binary files /dev/null and b/doc/source/_static/ui-api-browser.png differ diff --git a/doc/source/_static/ui-built-in.png b/doc/source/_static/ui-playbook-results.png similarity index 100% rename from doc/source/_static/ui-built-in.png rename to doc/source/_static/ui-playbook-results.png diff --git a/doc/source/_static/ui-playbook-search.png b/doc/source/_static/ui-playbook-search.png new file mode 100644 index 00000000..e642e73e Binary files /dev/null and b/doc/source/_static/ui-playbook-search.png differ diff --git a/doc/source/api-documentation.rst b/doc/source/api-documentation.rst index 6f3efa31..5394b9d0 100644 --- a/doc/source/api-documentation.rst +++ b/doc/source/api-documentation.rst @@ -12,15 +12,15 @@ 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/``: -.. image:: ../source/_static/ara-api-browser-root.png +.. image:: ../source/_static/ui-api-browser.png You can navigate the interface and drill down to list views, for example: -.. image:: ../source/_static/ara-api-browser-playbooks.png +.. image:: ../source/_static/ui-api-browser-playbooks.png You can also see what a detailed view looks like by querying a specific object id: -.. image:: ../source/_static/ara-api-browser-playbook.png +.. image:: ../source/_static/ui-api-browser-playbook.png Alternatively, you may also find an up-to-date live demonstration of the API at ``https://api.demo.recordsansible.org``. diff --git a/doc/source/faq.rst b/doc/source/faq.rst index 7f6f6d9b..11f01486 100644 --- a/doc/source/faq.rst +++ b/doc/source/faq.rst @@ -10,62 +10,6 @@ ARA is currently composed of three different free and open source projects: - 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) -How does ARA record data from Ansible ? ---------------------------------------- - -ARA Records Ansible playbooks through an Ansible `callback plugin`_. - -.. image:: _static/graphs/recording-workflow.png - -0. ARA is installed and Ansible is configured to use the callback plugin -1. An ``ansible-playbook`` command is executed -2. Ansible triggers the callback plugin for every event (``v2_playbook_on_start``, ``v2_runner_on_failed``, etc.) -3. The relevant information is retrieved from the Ansible playbook execution context and is sent to the API server -4. The API server validates and serializes the data before storing it the configured database backend -5. The API server sends a response back to the API client with the results -6. The callback plugin returns, ending the callback hook -7. Ansible continues running the playbook until it fails or is completed (back to step 2) - -Once the data has been saved in the database, it is made available for query by -the API. - -.. _callback plugin: https://docs.ansible.com/ansible/latest/plugins/callback.html - -How can we browse the data recorded by ARA ? --------------------------------------------- - -There are currently three ways to browse data recorded by ARA: - -Built-in REST API Browser -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ARA API server ships with a built-in REST API browser provided by `django-rest-framework `_. - -.. image:: ../source/_static/ara-api-browser-root.png - -Built-in simple interface -~~~~~~~~~~~~~~~~~~~~~~~~~ - -ARA also provides a simple, but limited, interface for use cases that do not need or require features provided by ara-web. - -.. image:: ../source/_static/ui-built-in.png - -ara-web -~~~~~~~ - -ara-web_ is a stateless javascript API client interface built with react. -It queries a running API server to provide reporting and visualization of playbook runs. - -.. image:: ../source/_static/ui-ara-web.png - -Are there live demos available ? --------------------------------- - -Yes, you can find persistent and up-to-date live demos at -`api.demo.recordsansible.org `_ for the -API and `web.demo.recordsansible.org `_ for -the ara-web_ standalone interface. - What's an Ansible callback ? ----------------------------