From c864d0dafa25b88b99f2ec571014c64bb3dd9cfe Mon Sep 17 00:00:00 2001 From: David Moreau Simard Date: Wed, 29 May 2019 10:52:17 -0400 Subject: [PATCH] Port FAQ docs from 0.x and update for 1.0 - Moved workflow diagram to FAQs - Added live demos - Removed web screenshots - Combined "Why is ARA being developed" with "Why don't you use Ansible Tower (AWX), Rundeck or Semaphore" Change-Id: Id7da538b8bce52f85ef4c4422a48d3b8b7588150 --- doc/source/ara-plugin-configuration.rst | 2 + doc/source/ara-record.rst | 2 + doc/source/architecture.rst | 20 ---- doc/source/faq.rst | 127 ++++++++++++++++++++++++ doc/source/index.rst | 2 +- 5 files changed, 132 insertions(+), 21 deletions(-) delete mode 100644 doc/source/architecture.rst create mode 100644 doc/source/faq.rst diff --git a/doc/source/ara-plugin-configuration.rst b/doc/source/ara-plugin-configuration.rst index a05ad4bd..497543dd 100644 --- a/doc/source/ara-plugin-configuration.rst +++ b/doc/source/ara-plugin-configuration.rst @@ -20,6 +20,8 @@ under the ara namespace, like so: [ara] variable = value +.. _configuration_callback: + ARA callback plugin ------------------- diff --git a/doc/source/ara-record.rst b/doc/source/ara-record.rst index 5f8e5ce4..5c1959e5 100644 --- a/doc/source/ara-record.rst +++ b/doc/source/ara-record.rst @@ -1,3 +1,5 @@ +.. _ara_record: + Recording arbitrary data in playbooks ===================================== diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst deleted file mode 100644 index f6b4cf0f..00000000 --- a/doc/source/architecture.rst +++ /dev/null @@ -1,20 +0,0 @@ -Architecture and Workflows -========================== - -Recording 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) - -.. _callback plugin: https://docs.ansible.com/ansible/latest/plugins/callback.html diff --git a/doc/source/faq.rst b/doc/source/faq.rst new file mode 100644 index 00000000..718aaaf1 --- /dev/null +++ b/doc/source/faq.rst @@ -0,0 +1,127 @@ +FAQ +=== + +What is ARA ? +------------- + +ARA Records `Ansible `_ playbooks and makes them easier to understand and troubleshoot. + +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) + +How does it work ? +------------------ + +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 + +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. + +.. _Ansible Callbacks: https://docs.ansible.com/ansible/dev_guide/developing_plugins.html + +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 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.8, then the latest release +of ARA will support 2.8 as well as 2.7 and 2.6. + +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, we strongly +encourage you to upgrade as soon as possible in order to benefit from the +latest features and security fixes. + +Older unsupported versions of Ansible can contain unfixed security +vulnerabilities (*CVE*). + +What versions of Python are supported ? +--------------------------------------- + +Before version 1.0 of ARA, both python2 and python3 were supported. +Versions of ARA after 1.0 are not designed to support python2 in consideration +that python2 will reach end of life in `January 2020 `_. + +Why ARA instead of ? +------------------------ + +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. + +.. _Ansible Tower: https://www.ansible.com/tower +.. _AWX: https://github.com/ansible/awx +.. _Zuul: https://zuul-ci.org +.. _Jenkins: https://www.redhat.com/en/blog/integrating-ansible-jenkins-cicd-process +.. _Rundeck: https://www.rundeck.com/ansible + +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. + +.. _ara-web: https://github.com/ansible-community/ara-web \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index aea3d082..20261e7d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,6 +8,7 @@ Table of Contents .. toctree:: :maxdepth: 2 + Frequently asked questions Installing ARA Configuring Ansible to use ARA Configuring the ARA Ansible plugins @@ -17,7 +18,6 @@ Table of Contents API: Usage with built-in clients Setting playbook names and labels Recording arbitrary data in playbooks - Architecture and workflows Contributing to ARA .. toctree::