Documentation updates post-merge of plugins/server/clients
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
parent
c1218db1ef
commit
b89ce1af99
10
README.rst
10
README.rst
|
|
@ -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 !
|
||||
|
|
|
|||
|
|
@ -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">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</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>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 167 KiB After Width: | Height: | Size: 168 KiB |
|
|
@ -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
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -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.
|
||||
|
|
@ -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,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
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue