Achieved goal should be returned by each strategy

Today, there is no way to know what goal is achieved by a given
strategy. The mapping between goal and strategies is done in the
Watcher configuration.

Beyond that, there is no way to know that several strategies achieve
the same optimization goal.
There should be a way to return the list of available goals depending
on which strategies have been deployed on the node where the Watcher
Decision Engine is running.

Change-Id: I57f7e434c41fcbd6606552c186e9a0285ff26e97
Implements: blueprint get-goal-from-strategy

doc/source/conf.py

@@ -72,6 +72,7 @@ copyright = u'%s, Watcher Team' % datetime.date.today().year
 # directories to ignore when looking for source files.
 exclude_patterns = [
     '_build',
+    'image_src/plantuml/README.rst',
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.

doc/source/image_src/plantuml/README.rst

@@ -0,0 +1,13 @@
+plantuml
+========
+
+
+To build an image from a source file, you have to upload the plantuml JAR file available on http://plantuml.com/download.html.
+After, just run this command to build your image:
+
+.. code-block:: shell
+
+    $ cd doc/source/images
+    $ java -jar /path/to/plantuml.jar doc/source/image_src/plantuml/my_image.txt
+    $ ls doc/source/images/
+    my_image.png

doc/source/image_src/plantuml/get_goal_from_strategy_class_diagram.txt

@@ -0,0 +1,31 @@
+@startuml
+
+class "Goal" {
+    int id (primary key)
+    String uuid (unique constraint)
+    String name (not null)
+    String display_name (not null)
+}
+
+class "Strategy" {
+    int id (primary key)
+    String uuid (unique constraint)
+    String name (not null)
+    String display_name (not null)
+    String goal_id (foreign key)
+}
+
+class "Audit Template" {
+    int id (primary key)
+    String uuid (unique constraint)
+    String name (not null)
+    String goal_id (foreign key)
+    String strategy_id (optional foreign key)
+}
+
+Strategy "0" *-- "*" Goal
+
+"Audit Template" "1" *-- "1" Goal
+"Audit Template" "0" *-- "1" Strategy
+
+@enduml

doc/source/image_src/plantuml/get_goal_from_strategy_sync_sequence_diagram.txt

@@ -0,0 +1,27 @@
+@startuml
+actor "Watcher Decision Engine"
+actor "Watcher DB"
+
+"Watcher Decision Engine" -> "Watcher Decision Engine" : start service
+
+group Sync
+
+    "Watcher Decision Engine" -> "Watcher Decision Engine" :\
+discover the resources (goals + strategies)
+    "Watcher Decision Engine" -> "Watcher DB" :\
+fetch current database states (goals and strategies)
+    "Watcher Decision Engine" <-- "Watcher DB" : OK
+    "Watcher Decision Engine" -> "Watcher Decision Engine" :\
+Compare / Check for updates
+    "Watcher Decision Engine" -> "Watcher DB" :\
+Create new goals/strategies DB entries if changed
+    "Watcher Decision Engine" <-- "Watcher DB" : OK
+    "Watcher Decision Engine" -> "Watcher DB" :\
+Soft delete deprecated goals and strategies
+    "Watcher Decision Engine" <-- "Watcher DB" : OK
+    "Watcher Decision Engine" -> "Watcher DB" :\
+Update audit template superseded goal_id and strategy_id \
+foreign keys if necessary
+    "Watcher Decision Engine" <-- "Watcher DB" : OK
+end
+@enduml

specs/newton/approved/get-goal-from-strategy.rst

@@ -75,6 +75,36 @@ In the future, it will also enable Watcher strategies to provide other common
 attributes and methods for a given goal (input parameters, efficacy indicators,
 ...).
 
+
+The synchronization of goals consists in establishing
+data consistency between goals and strategies
+automatically found by the `DefaultLoader` class
+via the function `list_available` to then applying the changes in
+the `Watcher database`_.
+Harmonization of the goals over time should be automatically performed
+by the decision_engine during start.
+We should create a `Synchronizer` class which compares records
+in `Watcher database`_  with those found by the `DefaultLoader`.
+Then, altered goals and strategies will be replaced in order to establish
+identity between the entry points and the `Watcher database`_.
+As a result of the synchronization, all the available goals
+and strategies are updated.
+The synchronization is required for two main reasons.
+The first reason is that we don't want a strong coupling between
+the Watcher API component and the Watcher Decision Engine component.
+In fact, we want the watcher-api only interact with `Watcher database`_
+and the message broker.
+The synchronization avoids the watcher cli having to call the watcher-api
+which would then have to call the watcher-decision-api,
+which is in charge of listing the resources.
+The second one is performance and HA.
+
+Below the strategy class and sequence diagram for syncing the goals.
+
+.. image:: ../../../doc/source/images/get_goal_from_strategy_class_diagram.png
+   :width: 140%
+
+
 Alternatives
 ------------
 
@@ -85,10 +115,45 @@ Data model impact
 -----------------
 
 The list of available goals should be stored in the `Watcher database`_.
-Therefore a new table should be created in the database for this.
-
 For each goal, the list of available strategies should also be stored in the
 `Watcher database`_. A new table should be created in the database for this.
+Therefore a new table should be created in the database for this.
+The proposed modification in the `Watcher database`_.
+is illustrated on the diagram below:
+
+.. image:: ../../../doc/source/images/get_goal_from_strategy_class_diagram.png
+   :width: 140%
+
+In the audit_template object, the 'strategy' attribute is optional.
+If the admin wants to force the trigger of a `Strategy`_ it could
+specify the `Strategy`_ uuid in the `Audit Template`_.
+There may be several strategies applying for a given optimization `Goal`_.
+If the admin didn't specify a `Strategy`_, the watcher strategy
+selector is responsible for selecting an appropriate
+one given the provided `Goal`_.
+This blueprint should reuse the ``DefaultStrategySelector`` class
+that is currently responsible for selecting the strategy.
+This selection of the strategy is complex but likely
+outside the scope of this blueprint (`watcher-strategy-selector`_).
+However, we need to provide a basic/minimum strategy selector.
+So, the strategy selector will select the first available strategy
+for a given goal.
+In the future, we plan have a more complex strategy selector
+that would be able to select the strategy depending on many
+parameters such as the usage of infrastructure, workloads, etc.
+
+The soft delete is a commonly-used pattern and cascading must be
+implemented in order to maintain integrity.
+If a strategy is deleted, we need to update every audit
+template linked to this strategy and setting
+the strategy id to None. So the audit template can still achieve the same
+goal but with a different strategy.
+However, if we delete a goals we didn't plan to maintain the integrity
+as it is outside the scope of this blueprint (`soft-delete-goals`_)
+
+Note: The id attribute is used by oslo.db to handle the soft_delete feature.
+
+
 
 REST API impact
 ---------------
@@ -190,6 +255,9 @@ Assignee(s)
 Primary assignee:
   vincent-francoise
 
+Other contributors:
+jed56
+
 Work Items
 ----------
 
@@ -286,3 +354,5 @@ None
 .. _Watcher Decision Engine: https://factory.b-com.com/www/watcher/doc/watcher/architecture.html#watcher-decision-engine
 .. _Watcher database: https://factory.b-com.com/www/watcher/doc/watcher/architecture.html#watcher-database
 .. _blueprint optimization-threshold: https://blueprints.launchpad.net/watcher/+spec/optimization-threshold
+.. _watcher-strategy-selector: https://blueprints.launchpad.net/watcher/+spec/watcher-strategy-selector
+.. _soft-delete-goals: https://blueprints.launchpad.net/watcher/+spec/soft-delete-goals