recordsansible/ara
Code Issues Proposed changes

Documentation updates post-merge of plugins/server/clients

Browse Source 
This updates some of the documentation bits that referred to individual
components like ara-server, ara-plugins and ara-clients.

Change-Id: I8ab3fdfb543786daacec22f7f1b90af4f17b5a2b
This commit is contained in:
David Moreau Simard 2019-03-02 09:59:11 -05:00
parent c1218db1ef
commit b89ce1af99
9 changed files with 65 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
README.rst
View File

@ -1,5 +1,5 @@
ara
===
ARA Records Ansible
===================
.. image:: doc/source/_static/ara-with-icon.png
@ -32,10 +32,10 @@ Here's how you can get started from scratch with default settings::
# Run your playbook as your normally would
~/.ara/venv/bin/ansible-playbook playbook.yml
The data is saved in real time during the Ansible playbook execution.
The data will be saved in real time throughout the execution of the Ansible playbook.
What happened behind the scenes is that the ARA Ansible callback plugin used
the offline API client to send the data to the API which then saved it to a
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 !

2
doc/source/_graphs/recording-workflow.xml
View File

@ -1 +1 @@
<mxfile userAgent="Mozilla/5.0 (X11; Fedora; Linux x86_64; rv:62.0) Gecko/20100101 Firefox/62.0" version="9.1.8" editor="www.draw.io" type="device"><diagram id="9906a0a6-bcd4-fe14-221d-85032a32ce87" name="Page-1">7Zxbc5s4FIB/DTPtQzISdx4T95Kd6c5mms5eHmWQbTYycgHnsr9+JZAwSGDjGDtugjvTwBFIQufjHOlIwrAmy6evKVotfqcRJoYJoifD+mSYJvRcl/3hkmchAVZQSuZpHAnZRnAX/4flhUK6jiOcNS7MKSV5vGoKQ5okOMwbMpSm9LF52YySZqkrNMea4C5ERJf+FUf5QkghAJuEGxzPF6Jo3xEJUxTez1O6TkR5hmnNil+ZvEQyL3F9tkARfayJrM+GNUkpzcuj5dMEE964stnK+750pFb1TnGS97nBEXp5QGQtnn1Fs3ye4uwnEVXMn2WzFA+G+a3QsK4fF3GO71Yo5KmPjAQmW+RLIpKrR+Mnc4IyrhPAjkO6jEMhJ2iKyXXVaBNKaMqSEppgnkWe0nsshawt3eJXpUjd8JxmMSG1K2cO/8flNMm/oGVMOIt/4jRCCRJiwR00xXntdlD8mByReJ4wWcgaFLPEa72FRaM/4DTHTzWRaPGvmC5xnj6zS0SqZ1vlLeL1sMXr8rhBzRN8LGqQ2RJwAfe8ynijYHYgdNyhb1/Tt2G6hJVwHcUPPHPxvEz6c80pvBZPXp2zo7n4W9zHW66BibyQJ1xkRRtfsQuguXqq5wJmJTkbmdSOVtTyuaCxLI89YllksxpMXDyBlL41dL+twzhibQMmNMkof6wGw/apGZYkCYY9X2PYDVoYBoczbO5guCQApehiRdbzOMm6ENHu+cA8AOEm/KNMnKZ7csbQWfHD9ZJ8i2eYxAUNK5zG7Dl5438iQny7ke3ikbm5HLFb0uqcELTK4mlRKldxisN1msUP+Dsu37hCStc5L2lSecni0sab0ED93VtmCzYtM5QdkhrWgaNjzV6HAbjWfbGGVw2KFY2TvCjOuTacTwplNM0XdE4TROqcbXQPBtR9pZKduv9S/E6i+8pK9Fa+9K9C94GuetjilZ0BLFrQZtFGze+heU3LbTD01bwJdGd2LNV7UzRFMLSnoenN7Cm4sPo6t5DEmGPQ37kVN4yu7X26Ntuxd7u2FsgHcW0a5bAN89HivRCGTiPyUt8HITyd83NGFI7q/Nrp6I2C7146r+cO7b7uMMPpQxGm6OkNr25/G13h+3SFLvTOyBXq5i/7SRgoOpwfIjxDa8K7cCOPb4hHz/Wkid1CpG+fikh9NHqzXqJkpO5NUQfVLp+OXNssxHGQG0NfxxwO7B0Ks0CDDc/r1QE0rWOMFN0RjdfsKzmu4ptM2+5Fw3HiBp5Gw+0fdz8ygy8Q4P8tWL8JsL79Nkb408chIleivaY0z+mSJeAkuuKrB7iM0PB+p9J7KgxHc3wnqoLJlD5+3giuCwFLkLXahmCnQnkJDUGO0jnusgfyncroOhVzsF0hmk4wwCWoSEgxQTlzyI0atOld5HbLX9JNVo6sjyTMUbIo6ynu2tDDdIWea5eJd7+7HNNuLWcDY5lj+92ub22vZdnkWi03GckL6WyW4dxQ34OqjV/4aow+9DUNpQ8UuOT09y6neQwzKZcX1Vi4Qw+4MpMRytkdGR6t5DYrGfSxkm47FQeaRDdQaPLNXiZRy8h3rO0ZdVitQSwS1ChESTGSu1gR9Dyl9P6dAbgVpaAV0sHRkkv+qsnOfs5Wywf6zUECDIJeZO3rtSEM1OiIKKnVbw8Crh51noiVQdx6M26ztwkuforzv2vH/3BXf+kCW5zXOgNFF6C/pd1uRIFxDNJNZZ1ltep2X9Qtx1IHQWpWA8FeLQVRyhkKdUcn+45RmYk+wRun+tJqcu07+3Jdx9jsa7A3IybgivHrgWRbnoKj5b2MbDsASkb2gVyfethjakBflX0MjeUxXP1Lh6utZo+4LV4N5RjsBAtY9BHWNuM5jrb3i1ib++JhN6d0e0ash1iyAMG4lunEC1jMfVCoXNopAjG6VbhhJTAJwQ/FJrlHmt7PCNMeO1zgpOgKhDSN4mRe9cHALGUdKxNUjqwM2qBG4AZM+SNffb/SWDt8q8srO5wz2+qiTZRqOLkyVFTnyR3Atvjdq4HjF+/Dgs19WGJtCeudFT0iE7BGZU/H62iCmx8/bj8aO3dexZ0rpVgb5wpxDVzkkKDGhRBpqlQHIMs4igo42hDvsJjAaN/QBYYatHSB2cvQbefQUZYtmTK0VzdsVptlG4JEfRr2w6wgBaOQG7gcZfeGOSkMWrZmYBTHOA8v9eVK7wkKeFwoYKDGOFpW7rpHgiLQowktSy0//YuSOe29MrPm4pZyZ3nKhk9p51aHs6NrIMd6oMkprhPNYg5Dm282TVCbBWobgw2yTlyf+v+O83XK93cKm/NGo7JGe0h13/kFOcten/QqF98PP33lNScZLLmjat/4lAN3ZDTc9JWcvhj56seX3LfRwKljn92BOKlRSstyXoaT5e3IaDicINAjkzfFjCdrDYHVCFMFk6/DJAIrg9NkAQUCdaTWlyZTqlhm5IDLfjztOy3UVeWhpoUqp70thlVDL+T9Ga7yzlDCgT3jOo6bkFidyXCdPlSdrb7Q6SzVei7OlgDhgcipc+WWo0yzvHTS/fD5mo5yVOBEhTvrBdrrNRygeu9PmpH+PX8emwp9PJ3pkagIYX8W/pJjgG3vUYSyRVUdfnKLcvZYSSExi3l94/BhQaDsp3L06Lv8HMPQQ1AI9N0quukawXgdMNTFRrDlM0HHI0Pv0FsjGWdChg2bC11gYJ6OjJbJW3sk40zIcFwlzN0y0X88MvQlq85IxpmQ4ZlKJ9PWw4/HI0MfzrsjGWdChmozLBk2PAkZ+iStN5JxJmTYphrxOyUZelTFH8k4EzLUsYnl6p+5OR4Z+lc/gpGMMyEDAmU/qg9bPoE0EBvsdPO57zIytvmouvX5fw==</diagram></mxfile>
<mxfile modified="2019-03-02T14:40:33.544Z" host="www.draw.io" agent="Mozilla/5.0 (X11; Fedora; Linux x86_64; rv:65.0) Gecko/20100101 Firefox/65.0" version="10.3.1" etag="tY1ZUQhwAL4cp4ZSqEVr" type="device"><diagram id="9906a0a6-bcd4-fe14-221d-85032a32ce87" name="Page-1">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</diagram></mxfile>

BIN
doc/source/_static/graphs/recording-workflow.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 167 KiB

After

Width:  |  Height:  |  Size: 168 KiB

38
doc/source/configuring.rst → doc/source/api-configuration.rst
View File

@ -1,13 +1,13 @@
.. _configuring:
ara-server configuration
========================
ARA API server configuration
============================
ara-server ships with sane defaults, supports the notion of different
The API server ships with sane defaults, supports the notion of different
environments (*such as dev, staging, prod*) and allows you to customize the
configuration with files, environment variables or a combination of both.
ara-server is a Django application that leverages django-rest-framework.
The API is a Django application that leverages django-rest-framework.
Both `Django <https://docs.djangoproject.com/en/2.1/ref/settings/>`_ and
`django-rest-framework <https://www.django-rest-framework.org/api-guide/settings/>`_
have extensive configuration options which are not necessarily exposed or made
@ -16,7 +16,7 @@ customizable by ARA for the sake of simplicity.
Overview
--------
This is a brief overview of the different configuration options for ara-server.
This is a brief overview of the different configuration options for the API server.
For more details, click on the configuration parameters.
+--------------------------------+------------------------------------------------------+------------------------------------------+
@ -24,7 +24,7 @@ For more details, click on the configuration parameters.
+================================+======================================================+==========================================+
| ARA_BASE_DIR_ | Default directory for storing data and configuration | ``~/.ara/server`` |
+--------------------------------+------------------------------------------------------+------------------------------------------+
| ARA_SETTINGS_ | Path to an ara-server configuration file | ``None`` |
| ARA_SETTINGS_ | Path to an API server configuration file | ``None`` |
+--------------------------------+------------------------------------------------------+------------------------------------------+
| ARA_ENV_ | Environment to load configuration for | ``default`` |
+--------------------------------+------------------------------------------------------+------------------------------------------+
@ -90,7 +90,7 @@ Changing this location influences the default root directory for the
``ARA_STATIC_ROOT`` and ``ARA_DATABASE_NAME`` parameters.
This is also used to determine the location where the default configuration
file, ``settings.yaml``, will be generated by ara-server.
file, ``settings.yaml``, will be generated by the API server.
ARA_SETTINGS
~~~~~~~~~~~~
@ -101,15 +101,15 @@ ARA_SETTINGS
- **Default**: ``None``
- **Provided by**: dynaconf_
Location of an ara-server configuration file to load settings from.
``ara-server`` generates a default configuration file at
Location of an API server configuration file to load settings from.
The API server will generate a default configuration file at
``~/.ara/server/settings.yaml`` that you can use to get started.
Note that while the configuration file is in YAML by default, it is possible
to have configuration files written in ``ini``, ``json`` and ``toml`` as well.
Settings and configuration parsing in ara-server is provided by the dynaconf_
python module.
Settings and configuration parsing by the API server is provided by the dynaconf_
python library.
.. _dynaconf: https://github.com/rochacbruno/dynaconf
@ -122,9 +122,9 @@ ARA_ENV
- **Default**: ``development``
- **Provided by**: dynaconf_
If you are using ara-server in different environments and would like keep your
configuration in a single file, you can use this variable to select a specific
environment's settings.
If you are using the API server in different environments and would like keep
your configuration in a single file, you can use this variable to select a
specific environment's settings.
For example::
@ -158,7 +158,7 @@ Another approach to environment-specific configuration is to use
or ``prod.yaml`` instead.
.. tip::
If it does not exist, ara-server will generate a default configuration
If it does not exist, the API server will generate a default configuration
file at ``~/.ara/server/settings.yaml``.
This generated file sets up all the configuration keys in the **default**
environment.
@ -207,7 +207,7 @@ ARA_LOG_LEVEL
- **Type**: ``string``
- **Default**: ``INFO``
Log level of the different components from ``ara-server``.
Log level of the different components from the API server.
``ARA_LOG_LEVEL`` changes the log level of the default logging configuration
provided by ARA_LOGGING_.
@ -243,7 +243,7 @@ ARA_LOGGING
level: INFO
version: 1
The python logging configuration for ``ara-server``.
The python logging configuration for the API server.
ARA_CORS_ORIGIN_WHITELIST
~~~~~~~~~~~~~~~~~~~~~~~~~
@ -284,7 +284,7 @@ ARA_ALLOWED_HOSTS
A list of strings representing the host/domain names that this Django site can
serve.
If you are planning on hosting an instance of ``ara-server`` somewhere, you'll
If you are planning on hosting an instance of the API server somewhere, you'll
need to add your domain name to this list.
ARA_DEBUG
@ -345,7 +345,7 @@ ARA_DATABASE_ENGINE
The Django database driver to use.
When using anything other than sqlite3 default driver, make sure to set the
other database settings to allow ara-server to connect to the database.
other database settings to allow the API server to connect to the database.
ARA_DATABASE_NAME
~~~~~~~~~~~~~~~~~

14
doc/source/security.rst → doc/source/api-security.rst
View File

@ -1,9 +1,9 @@
.. security:
Authentication and security
===========================
ARA API Server authentication and security
==========================================
ara-server ships with a default configuration that emphasizes simplicity to
The API server ships with a default configuration that emphasizes simplicity to
let users get started quickly.
By default:
@ -19,7 +19,7 @@ deployments.
Setting a custom secret key
---------------------------
By default, ara-server randomly generates a token for the :ref:`ARA_SECRET_KEY`
By default, the API server randomly generates a token for the :ref:`ARA_SECRET_KEY`
setting if none have been supplied by the user.
This value is persisted in the server configuration file in order to prevent
the key from changing on every instanciation of the server.
@ -34,7 +34,7 @@ configuration file.
User management
---------------
ara-server leverages Django's `user management <https://docs.djangoproject.com/en/2.1/topics/auth/default/>`_
The API server leverages Django's `user management <https://docs.djangoproject.com/en/2.1/topics/auth/default/>`_
but doesn't create any user by default.
.. note::
@ -97,7 +97,7 @@ Managing hosts allowed to serve the API
By default, :ref:`ARA_ALLOWED_HOSTS` authorizes ``localhost``, ``::1`` and
``127.0.0.1`` to serve requests for the API server.
In order to host an instance of ara-server on another domain, the domain must
In order to host an instance of the API server on another domain, the domain must
be part of this list or the application server will deny any requests sent to
it.
@ -106,7 +106,7 @@ Managing CORS (cross-origin resource sharing)
The :ref:`ARA_CORS_ORIGIN_WHITELIST` default is designed to allow a local development
instance of an `ara-web <https://github.com/openstack/ara-web>`_ dashboard to
communicate with a local development instance of ara-server.
communicate with a local development instance of the API server.
The whitelist must contain the domain names where you plan on hosting instances
of ara-web.

37
doc/source/using_api_clients.rst → doc/source/api-usage.rst
View File

@ -1,27 +1,19 @@
Using API clients with ara-server
=================================
Using ARA API clients
=====================
Once you've :ref:`installed <installing>` ara-server, you need to know how
you're going to use it.
When installing ARA, you are provided with an API server and two API clients
out of the box:
Typically, `ara-server <https://github.com/openstack/ara-server>`_ is consumed
by `ara-clients <https://github.com/openstack/ara-clients>`_ which currently
provides two python clients for the API.
- ``AraOfflineClient`` can query the API without needing an API server to be running
- ``AraHttpClient`` is meant to query a specified API server over http
ARA Offline REST API client
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default client, ``AraOfflineClient``, is meant to be used to query the API
without requiring users to start or host an instance of ``ara-server``.
If your use case doesn't require a remote or persistent API server, the offline
client lets you query the API without needing to start an API server.
To use the offline client, first install ``ara-server`` and ``ara-clients``,
for example::
# Install ara-server and ara-clients
python3 -m venv ~/.ara/venv
~/.ara/venv/bin/pip install ara-server ara-clients
Then you can use it like this::
In order to use this client, you would instanciate it like this::
#!/usr/bin/env python3
# Import the client
@ -35,8 +27,6 @@ ARA HTTP REST API client
``AraHttpClient`` works with the same interface, methods and behavior as
``AraOfflineClient``.
The HTTP client does not require ``ara-server`` to be installed in order to be
used but expects a functional API endpoint at a specified location.
You can set your client to communicate with a remote ``ara-server`` API by
specifying an endpoint parameter::
@ -45,7 +35,7 @@ specifying an endpoint parameter::
# Import the client
from ara.clients.http import AraHttpClient
# Instanciate the HTTP client with an endpoint where ara-server is listening
# Instanciate the HTTP client with an endpoint where an API server is listening
client = AraHttpClient(endpoint="https://api.demo.recordsansible.org")
Example API usage
@ -58,6 +48,13 @@ Once you've instanciated your client, you're ready to query the API.
Here's a code example to help you get started::
#!/usr/bin/env python3
# Import the client
from ara.clients.http import AraHttpClient
# Instanciate the HTTP client with an endpoint where an API server is listening
client = AraHttpClient(endpoint="https://api.demo.recordsansible.org")
# Get a list of failed playbooks
# /api/v1/playbooks?status=failed
playbooks = client.get("/api/v1/playbooks", status="failed")

9
doc/source/arch.rst → doc/source/architecture.rst
View File

@ -9,15 +9,12 @@ Recording data from Ansible
0. A human (*or a system, script, etc.*) installs ARA and configures Ansible to use the ARA callback
1. A human (*or a system, script, etc.*) executes an ``ansible-playbook`` command
2. Ansible sends hooks for every event to `callback plugins`_ (``v2_playbook_on_start``, ``v2_runner_on_failed``, etc.)
3. The callback plugin, provided by ara-plugins_, organizes the data sent by Ansible and sends it to the API client
4. The API client, provided by ara-clients_, takes care of actually sending the data to the API over HTTP or locally offline through an internal implementation
5. The API server, provided by ara-server_, receives the POST from the client, validates it and sends it to the database model backend
3. The callback plugin, organizes the data sent by Ansible and sends it to the API client
4. The API client sends the data to the API over HTTP or locally offline through an internal implementation
5. The API server receives the POST from the client, validates it and sends it to the database model backend
6. The API server sends a response back to the client with the results
7. The API client sends the response back to the callback with the results
8. The callback plugin returns, ending the callback hook
9. Ansible continues running until it is complete (back to step 2)
.. _callback plugins: https://docs.ansible.com/ansible/latest/plugins/callback.html
.. _ara-plugins: https://github.com/openstack/ara-plugins
.. _ara-clients: https://github.com/openstack/ara-clients
.. _ara-server: https://github.com/openstack/ara-server

14
doc/source/index.rst
View File

@ -1,5 +1,5 @@
Welcome to the ARA server documentation!
========================================
Welcome to the ARA documentation!
=================================
.. image:: _static/ara.png
Table of Contents
@ -8,8 +8,8 @@ Table of Contents
.. toctree::
:maxdepth: 2
Installing ara-server <installing>
Configuration settings and preferences <configuring>
Authentication and security <security>
Using API clients with ara-server <using_api_clients>
Architecture and workflows <arch>
Installing ARA <installation>
API configuration settings and preferences <api-configuration>
API authentication and security <api-security>
API usage with built-in clients <api-usage>
Architecture and workflows <architecture>

15
doc/source/installing.rst → doc/source/installation.rst
View File

@ -1,9 +1,9 @@
.. _installing:
.. installation:
Installing ara-server
=====================
Installing ARA
==============
``ara-server`` requires a Linux distribution with python 3 in order to work.
ARA should work on any Linux distributions as long as python3 is available.
It is recommended to use a python `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_
in order to avoid conflicts with your Linux distribution python packages::
@ -11,8 +11,5 @@ in order to avoid conflicts with your Linux distribution python packages::
# Create a virtual environment
python3 -m venv ~/.ara/venv
# Install ara-server from source
~/.ara/venv/bin/pip install git+https://git.openstack.org/openstack/ara-server
# or install it from PyPi
~/.ara/venv/bin/pip install ara-server
# Install ARA 1.0 from source
~/.ara/venv/bin/pip install git+https://git.openstack.org/openstack/ara@feature/1.0