diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst new file mode 100644 index 000000000..a7c8cef39 --- /dev/null +++ b/doc/source/architecture.rst @@ -0,0 +1,170 @@ +.. _architecture: + +=================== +System Architecture +=================== + + +This page presents the current technical Architecture of the Watcher system. + +.. _architecture_overview: + +Overview +======== + +Below you will find a diagram, showing the main components of Watcher: + +.. image:: ./images/architecture.svg + :width: 100% + + +.. _components_definition: + +Components +========== + +.. _amqp_bus_definition: + +AMQP Bus +-------- + +The AMQP message bus handles asynchronous communications between the different +Watcher components. + +.. _cluster_history_db_definition: + +Cluster History Database +------------------------ + +This component stores the data related to the +:ref:`Cluster History `. + +It can potentially rely on any appropriate storage system (InfluxDB, OpenTSDB, +MongoDB,...) but will probably be more performant when using +`Time Series Databases `_ +which are optimized for handling time series data, which are arrays of numbers +indexed by time (a datetime or a datetime range). + +.. _watcher_api_definition: + +Watcher API +----------- + +This component implements the REST API provided by the Watcher system to the +external world. + +It enables the :ref:`Administrator ` of a +:ref:`Cluster ` to control and monitor the Watcher system +via any interaction mechanism connected to this API: + +- :ref:`CLI ` +- Horizon plugin +- Python SDK + +You can also read the detailed description of `Watcher API`_. + +.. _watcher_applier_definition: + +Watcher Applier +--------------- + +This component is in charge of executing the :ref:`Action Plan ` +built by the :ref:`Watcher Decision Engine `. + +It connects to the :ref:`message bus ` and launches the +:ref:`Action Plan ` whenever a triggering message is +received on a dedicated AMQP queue. + +The triggering message contains the Action Plan UUID. + +It then gets the detailed information about the +:ref:`Action Plan ` from the +:ref:`Watcher Database ` which contains the list +of :ref:`Actions ` to launch. + +It then loops on each :ref:`Action `, gets the associated +class and calls the execute() method of this class. +Most of the time, this method will first request a token to the Keystone API +and if it is allowed, sends a request to the REST API of the OpenStack service +which handles this kind of :ref:`atomic Action `. + +Note that as soon as :ref:`Watcher Applier ` starts +handling a given :ref:`Action ` from the list, a +notification message is sent on the :ref:`message bus ` +indicating that the state of the action has changed to **ONGOING**. + +If the :ref:`Action ` is successful, the :ref:`Watcher Applier ` +sends a notification message on :ref:`the bus ` informing +the other components of this. + +If the :ref:`Action ` fails, the +:ref:`Watcher Applier ` tries to rollback to the +previous state of the :ref:`Managed resource ` +(i.e. before the command was sent to the underlying OpenStack service). + +.. _watcher_cli_definition: + +Watcher CLI +----------- + +The watcher command-line interface (CLI) can be used to interact with the +Watcher system in order to control it or to know its current status. + +Please, read `the detailed documentation about Watcher CLI `_ + +.. _watcher_database_definition: + +Watcher Database +---------------- + +This database stores all the Watcher domain objects which can be requested +by the :ref:`Watcher API ` or the +:ref:`Watcher CLI `: + +- :ref:`Audit templates ` +- :ref:`Audits ` +- :ref:`Action plans ` +- :ref:`Actions ` +- :ref:`Goals ` + +The Watcher domain being here "*optimization of some resources provided by an +OpenStack system*". + +.. _watcher_decision_engine_definition: + +Watcher Decision Engine +----------------------- + +This component is responsible for computing a set of potential optimization +:ref:`Actions ` in order to fulfill the :ref:`Goal ` +of an :ref:`Audit `. + +It first reads the parameters of the :ref:`Audit ` from the +associated :ref:`Audit Template ` and knows the +:ref:`Goal ` to achieve. + +It then selects the most appropriate :ref:`Strategy ` +depending on how Watcher was configured for this :ref:`Goal `. + +The :ref:`Strategy ` is then dynamically loaded (via +`stevedore `_). The +:ref:`Watcher Decision Engine ` calls the +**execute()** method of the :ref:`Strategy ` class which +generates a set of :ref:`Actions `. + +These :ref:`Actions ` are scheduled in time by the +:ref:`Watcher Planner ` (i.e., it generates an +:ref:`Action Plan `). + +In order to compute the potential :ref:`Solution ` for the +Audit, the :ref:`Strategy ` relies on two sets of data: + +- the current state of the :ref:`Managed resources ` + (e.g., the data stored in the Nova database) +- the data stored in the :ref:`Cluster History Database ` + which provides information about the past of the :ref:`Cluster ` + +So far, only one :ref:`Strategy ` can be associated to a +given :ref:`Goal ` via the main Watcher configuration file. + +.. _Watcher API: webapi/v1.html diff --git a/doc/source/dev/architecture.rst b/doc/source/dev/architecture.rst deleted file mode 100644 index 875deb765..000000000 --- a/doc/source/dev/architecture.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _architecture: - -=================== -System Architecture -=================== - -Please go to `Wiki Watcher Architecture `_ - -.. _API service: ../webapi/v1.html diff --git a/doc/source/image_src/architecture.dia b/doc/source/image_src/architecture.dia new file mode 100644 index 000000000..2153355fe Binary files /dev/null and b/doc/source/image_src/architecture.dia differ diff --git a/doc/source/images/architecture.svg b/doc/source/images/architecture.svg new file mode 100644 index 000000000..48b9b2c03 --- /dev/null +++ b/doc/source/images/architecture.svg @@ -0,0 +1,275 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AMQP + bus + + + + + + + + + + + + + + + + + + + Watcher + Decision Engine + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Watcher + Actions Applier + + + + + + + + + + + + + + + + + + + Watcher + API + + + + + + + + + + + + + + + + + + + Watcher + CLI + + + + + + + Horizon + + + + + + + + + + + + + + + + + + + Watcher + plugin + + + + + + + Nova + + + + + + + MariaDB Database + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ceilometer API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Strategy + + + + + + + + + + + + + + + + + + + + + + + Watcher DB + + + + + + + + Cluster History DB + + + + + + + + diff --git a/doc/source/index.rst b/doc/source/index.rst index 2c4baf728..115d6cbd2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -22,7 +22,7 @@ Introduction :maxdepth: 1 dev/glossary - dev/architecture + architecture dev/environment dev/contributing dev/plugins