Merge "Move terminology definition to class related"

watcher/api/controllers/v1/action.py

@@ -15,6 +15,43 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An :ref:`Action <action_definition>` is what enables Watcher to transform the
+current state of a :ref:`Cluster <cluster_definition>` after an
+:ref:`Audit <audit_definition>`.
+
+An :ref:`Action <action_definition>` is an atomic task which changes the
+current state of a target :ref:`Managed resource <managed_resource_definition>`
+of the OpenStack :ref:`Cluster <cluster_definition>` such as:
+
+-  Live migration of an instance from one compute node to another compute
+   node with Nova
+-  Changing the power level of a compute node (ACPI level, ...)
+-  Changing the current state of an hypervisor (enable or disable) with Nova
+
+In most cases, an :ref:`Action <action_definition>` triggers some concrete
+commands on an existing OpenStack module (Nova, Neutron, Cinder, Ironic, etc.)
+via a :ref:`Primitive <primitive_definition>`.
+
+An :ref:`Action <action_definition>` has a life-cycle and its current state may
+be one of the following:
+
+-  **PENDING** : the :ref:`Action <action_definition>` has not been executed
+   yet by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **ONGOING** : the :ref:`Action <action_definition>` is currently being
+   processed by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **SUCCEEDED** : the :ref:`Action <action_definition>` has been executed
+   successfully
+-  **FAILED** : an error occured while trying to execute the
+   :ref:`Action <action_definition>`
+-  **DELETED** : the :ref:`Action <action_definition>` is still stored in the
+   :ref:`Watcher database <watcher_database_definition>` but is not returned
+   any more through the Watcher APIs.
+-  **CANCELLED** : the :ref:`Action <action_definition>` was in **PENDING** or
+   **ONGOING** state and was cancelled by the
+   :ref:`Administrator <administrator_definition>`
+"""
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/action_plan.py

@@ -15,6 +15,60 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An :ref:`Action Plan <action_plan_definition>` is a flow of
+:ref:`Actions <action_definition>` that should be executed in order to satisfy
+a given :ref:`Goal <goal_definition>`.
+
+An :ref:`Action Plan <action_plan_definition>` is generated by Watcher when an
+:ref:`Audit <audit_definition>` is successful which implies that the
+:ref:`Strategy <strategy_definition>`
+which was used has found a :ref:`Solution <solution_definition>` to achieve the
+:ref:`Goal <goal_definition>` of this :ref:`Audit <audit_definition>`.
+
+In the default implementation of Watcher, an
+:ref:`Action Plan <action_plan_definition>`
+is only composed of successive :ref:`Actions <action_definition>`
+(i.e., a Workflow of :ref:`Actions <action_definition>` belonging to a unique
+branch).
+
+However, Watcher provides abstract interfaces for many of its components,
+allowing other implementations to generate and handle more complex
+:ref:`Action Plan(s) <action_plan_definition>`
+composed of two types of Action Item(s):
+
+-  simple :ref:`Actions <action_definition>`: atomic tasks, which means it
+   can not be split into smaller tasks or commands from an OpenStack point of
+   view.
+-  composite Actions: which are composed of several simple
+   :ref:`Actions <action_definition>`
+   ordered in sequential and/or parallel flows.
+
+An :ref:`Action Plan <action_plan_definition>` may be described using
+standard workflow model description formats such as
+`Business Process Model and Notation 2.0 (BPMN 2.0) <http://www.omg.org/spec/BPMN/2.0/>`_
+or `Unified Modeling Language (UML) <http://www.uml.org/>`_.
+
+An :ref:`Action Plan <action_plan_definition>` has a life-cycle and its current
+state may be one of the following:
+
+-  **RECOMMENDED** : the :ref:`Action Plan <action_plan_definition>` is waiting
+   for a validation from the :ref:`Administrator <administrator_definition>`
+-  **ONGOING** : the :ref:`Action Plan <action_plan_definition>` is currently
+   being processed by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **SUCCEEDED** : the :ref:`Action Plan <action_plan_definition>` has been
+   executed successfully (i.e. all :ref:`Actions <action_definition>` that it
+   contains have been executed successfully)
+-  **FAILED** : an error occured while executing the
+   :ref:`Action Plan <action_plan_definition>`
+-  **DELETED** : the :ref:`Action Plan <action_plan_definition>` is still
+   stored in the :ref:`Watcher database <watcher_database_definition>` but is
+   not returned any more through the Watcher APIs.
+-  **CANCELLED** : the :ref:`Action Plan <action_plan_definition>` was in
+   **PENDING** or **ONGOING** state and was cancelled by the
+   :ref:`Administrator <administrator_definition>`
+"""  # noqa
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/audit.py

@@ -15,6 +15,40 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+In the Watcher system, an :ref:`Audit <audit_definition>` is a request for
+optimizing a :ref:`Cluster <cluster_definition>`.
+
+The optimization is done in order to satisfy one :ref:`Goal <goal_definition>`
+on a given :ref:`Cluster <cluster_definition>`.
+
+For each :ref:`Audit <audit_definition>`, the Watcher system generates an
+:ref:`Action Plan <action_plan_definition>`.
+
+An :ref:`Audit <audit_definition>` has a life-cycle and its current state may
+be one of the following:
+
+-  **PENDING** : a request for an :ref:`Audit <audit_definition>` has been
+   submitted (either manually by the
+   :ref:`Administrator <administrator_definition>` or automatically via some
+   event handling mechanism) and is in the queue for being processed by the
+   :ref:`Watcher Decision Engine <watcher_decision_engine_definition>`
+-  **ONGOING** : the :ref:`Audit <audit_definition>` is currently being
+   processed by the
+   :ref:`Watcher Decision Engine <watcher_decision_engine_definition>`
+-  **SUCCEEDED** : the :ref:`Audit <audit_definition>` has been executed
+   successfully (note that it may not necessarily produce a
+   :ref:`Solution <solution_definition>`).
+-  **FAILED** : an error occured while executing the
+   :ref:`Audit <audit_definition>`
+-  **DELETED** : the :ref:`Audit <audit_definition>` is still stored in the
+   :ref:`Watcher database <watcher_database_definition>` but is not returned
+   any more through the Watcher APIs.
+-  **CANCELLED** : the :ref:`Audit <audit_definition>` was in **PENDING** or
+   **ONGOING** state and was cancelled by the
+   :ref:`Administrator <administrator_definition>`
+"""
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/audit_template.py

@@ -15,6 +15,39 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An :ref:`Audit <audit_definition>` may be launched several times with the same
+settings (:ref:`Goal <goal_definition>`, thresholds, ...). Therefore it makes
+sense to save those settings in some sort of Audit preset object, which is
+known as an :ref:`Audit Template <audit_template_definition>`.
+
+An :ref:`Audit Template <audit_template_definition>` contains at least the
+:ref:`Goal <goal_definition>` of the :ref:`Audit <audit_definition>`.
+
+It may also contain some error handling settings indicating whether:
+
+-  :ref:`Watcher Applier <watcher_applier_definition>` stops the
+   entire operation
+-  :ref:`Watcher Applier <watcher_applier_definition>` performs a rollback
+
+and how many retries should be attempted before failure occurs (also the latter
+can be complex: for example the scenario in which there are many first-time
+failures on ultimately successful :ref:`Actions <action_definition>`).
+
+Moreover, an :ref:`Audit Template <audit_template_definition>` may contain some
+settings related to the level of automation for the
+:ref:`Action Plan <action_plan_definition>` that will be generated by the
+:ref:`Audit <audit_definition>`.
+A flag will indicate whether the :ref:`Action Plan <action_plan_definition>`
+will be launched automatically or will need a manual confirmation from the
+:ref:`Administrator <administrator_definition>`.
+
+Last but not least, an :ref:`Audit Template <audit_template_definition>` may
+contain a list of extra parameters related to the
+:ref:`Strategy <strategy_definition>` configuration. These parameters can be
+provided as a list of key-value pairs.
+"""
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/goal.py

@@ -15,6 +15,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+A :ref:`Goal <goal_definition>` is a human readable, observable and measurable
+end result having one objective to be achieved.
+
+Here are some examples of :ref:`Goals <goal_definition>`:
+
+-  minimize the energy consumption
+-  minimize the number of compute nodes (consolidation)
+-  balance the workload among compute nodes
+-  minimize the license cost (some softwares have a licensing model which is
+   based on the number of sockets or cores where the software is deployed)
+-  find the most appropriate moment for a planned maintenance on a
+   given group of host (which may be an entire availability zone):
+   power supply replacement, cooling system replacement, hardware
+   modification, ...
+"""
+
 from oslo_config import cfg
 
 import pecan