Merge "Documentation update for get-goal-from-strategy"

watcher/api/controllers/v1/strategy.py

@@ -14,6 +14,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+A :ref:`Strategy <strategy_definition>` is an algorithm implementation which is
+able to find a :ref:`Solution <solution_definition>` for a given
+:ref:`Goal <goal_definition>`.
+
+There may be several potential strategies which are able to achieve the same
+:ref:`Goal <goal_definition>`. This is why it is possible to configure which
+specific :ref:`Strategy <strategy_definition>` should be used for each goal.
+
+Some strategies may provide better optimization results but may take more time
+to find an optimal :ref:`Solution <solution_definition>`.
+"""
+
 from oslo_config import cfg
 
 import pecan

watcher/decision_engine/strategy/strategies/base.py

@@ -169,6 +169,29 @@ class DummyBaseStrategy(BaseStrategy):
         return "Dummy goal"
 
 
+@six.add_metaclass(abc.ABCMeta)
+class UnclassifiedStrategy(BaseStrategy):
+    """This base class is used to ease the development of new strategies
+
+    The goal defined within this strategy can be used to simplify the
+    documentation explaining how to implement a new strategy plugin by
+    ommitting the need for the strategy developer to define a goal straight
+    away.
+    """
+
+    @classmethod
+    def get_goal_name(cls):
+        return "UNCLASSIFIED"
+
+    @classmethod
+    def get_goal_display_name(cls):
+        return _("Unclassified")
+
+    @classmethod
+    def get_translatable_goal_display_name(cls):
+        return "Unclassified"
+
+
 @six.add_metaclass(abc.ABCMeta)
 class ServerConsolidationBaseStrategy(BaseStrategy):
 

watcher/decision_engine/strategy/strategies/vm_workload_consolidation.py

@@ -46,10 +46,11 @@ class VMWorkloadConsolidation(base.ServerConsolidationBaseStrategy):
 
     This strategy produces a solution resulting in more efficient
     utilization of cluster resources using following four phases:
-     * Offload phase - handling over-utilized resources
-     * Consolidation phase - handling under-utilized resources
-     * Solution optimization - reducing number of migrations
-     * Deactivation of unused hypervisors
+
+    * Offload phase - handling over-utilized resources
+    * Consolidation phase - handling under-utilized resources
+    * Solution optimization - reducing number of migrations
+    * Deactivation of unused hypervisors
 
     A capacity coefficients (cc) might be used to adjust optimization
     thresholds. Different resources may require different coefficient
@@ -58,7 +59,7 @@ class VMWorkloadConsolidation(base.ServerConsolidationBaseStrategy):
     If the cc equals 1 the full resource capacity may be used, cc
     values lower than 1 will lead to resource under utilization and
     values higher than 1 will lead to resource overbooking.
-    e.g. If targeted utilization is 80% of hypervisor capacity,
+    e.g. If targeted utilization is 80 percent of hypervisor capacity,
     the coefficient in the consolidation phase will be 0.8, but
     may any lower value in the offloading phase. The lower it gets
     the cluster will appear more released (distributed) for the
@@ -397,12 +398,13 @@ class VMWorkloadConsolidation(base.ServerConsolidationBaseStrategy):
         This is done by eliminating unnecessary or circular set of migrations
         which can be replaced by a more efficient solution.
         e.g.:
-         * A->B, B->C => replace migrations A->B, B->C with
-           a single migration A->C as both solution result in
-           VM running on hypervisor C which can be achieved with
-           one migration instead of two.
-         * A->B, B->A => remove A->B and B->A as they do not result
-           in a new VM placement.
+
+        * A->B, B->C => replace migrations A->B, B->C with
+          a single migration A->C as both solution result in
+          VM running on hypervisor C which can be achieved with
+          one migration instead of two.
+        * A->B, B->A => remove A->B and B->A as they do not result
+          in a new VM placement.
 
         :param model: model_root object
         """
@@ -502,10 +504,11 @@ class VMWorkloadConsolidation(base.ServerConsolidationBaseStrategy):
         This strategy produces a solution resulting in more
         efficient utilization of cluster resources using following
         four phases:
-         * Offload phase - handling over-utilized resources
-         * Consolidation phase - handling under-utilized resources
-         * Solution optimization - reducing number of migrations
-         * Deactivation of unused hypervisors
+
+        * Offload phase - handling over-utilized resources
+        * Consolidation phase - handling under-utilized resources
+        * Solution optimization - reducing number of migrations
+        * Deactivation of unused hypervisors
 
         :param original_model: root_model object
         """