Add doc for workload-stabilization spec

This patch set adds how-to-use documentation for
Watcher Overload standard deviation algorithm.

Change-Id: I75d7cd0ff8507ca70efb6d9668ae9fbf651a7f97

doc/source/strategies/strategy-template.rst

@@ -91,6 +91,12 @@ Efficacy Indicator
 
 Add here the Efficacy indicator computed by your strategy.
 
+Algorithm
+---------
+
+Add here either the description of your algorithm or
+link to the existing description.
+
 How to use it ?
 ---------------
 

doc/source/strategies/workload-stabilization.rst

@@ -0,0 +1,131 @@
+=============================================
+Watcher Overload standard deviation algorithm
+=============================================
+
+Synopsis
+--------
+
+**display name**: ``workload_stabilization``
+
+**goal**: ``workload_balancing``
+
+    .. watcher-term:: watcher.decision_engine.strategy.strategies.workload_stabilization
+
+Requirements
+------------
+
+Metrics
+*******
+
+The *workload_stabilization* strategy requires the following metrics:
+
+============================ ============ ======= =======
+metric                       service name plugins comment
+============================ ============ ======= =======
+``compute.node.cpu.percent`` ceilometer_  none
+``hardware.memory.used``     ceilometer_  SNMP_
+``cpu_util``                 ceilometer_  none
+``memory.resident``          ceilometer_  none
+============================ ============ ======= =======
+
+.. _ceilometer: http://docs.openstack.org/admin-guide/telemetry-measurements.html#openstack-compute
+.. _SNMP: http://docs.openstack.org/admin-guide/telemetry-measurements.html
+
+Cluster data model
+******************
+
+Default Watcher's Compute cluster data model:
+
+    .. watcher-term:: watcher.decision_engine.model.collector.nova.NovaClusterDataModelCollector
+
+Actions
+*******
+
+Default Watcher's actions:
+
+
+    .. list-table::
+       :widths: 30 30
+       :header-rows: 1
+
+       * - action
+         - description
+       * - ``migration``
+         - .. watcher-term:: watcher.applier.actions.migration.Migrate
+
+Planner
+*******
+
+Default Watcher's planner:
+
+    .. watcher-term:: watcher.decision_engine.planner.default.DefaultPlanner
+
+Configuration
+-------------
+
+Strategy parameters are:
+
+==================== ====== ===================== =============================
+parameter            type   default Value         description
+==================== ====== ===================== =============================
+``metrics``          array  |metrics|             Metrics used as rates of
+                                                  cluster loads.
+``thresholds``       object |thresholds|          Dict where key is a metric
+                                                  and value is a trigger value.
+
+``weights``          object |weights|             These weights used to
+                                                  calculate common standard
+                                                  deviation. Name of weight
+                                                  contains meter name and
+                                                  _weight suffix.
+``instance_metrics`` object |instance_metrics|    Mapping to get hardware
+                                                  statistics using instance
+                                                  metrics.
+``host_choice``      string retry                 Method of host's choice.
+                                                  There are cycle, retry and
+                                                  fullsearch methods. Cycle
+                                                  will iterate hosts in cycle.
+                                                  Retry will get some hosts
+                                                  random (count defined in
+                                                  retry_count option).
+                                                  Fullsearch will return each
+                                                  host from list.
+``retry_count``      number 1                     Count of random returned
+                                                  hosts.
+==================== ====== ===================== =============================
+
+.. |metrics| replace:: ["cpu_util", "memory.resident"]
+.. |thresholds| replace:: {"cpu_util": 0.2, "memory.resident": 0.2}
+.. |weights| replace:: {"cpu_util_weight": 1.0, "memory.resident_weight": 1.0}
+.. |instance_metrics| replace:: {"cpu_util": "hardware.cpu.util", "memory.resident": "hardware.memory.used"}
+
+Efficacy Indicator
+------------------
+
+.. watcher-func::
+  :format: literal_block
+
+  watcher.decision_engine.goal.efficacy.specs.ServerConsolidation.get_global_efficacy_indicator
+
+Algorithm
+---------
+
+You can find description of overload algorithm and role of standard deviation
+here: https://specs.openstack.org/openstack/watcher-specs/specs/newton/implemented/sd-strategy.html
+
+How to use it ?
+---------------
+
+.. code-block:: shell
+
+    $ openstack optimize audittemplate create \
+      at1 workload_balancing --strategy workload_stabilization
+
+    $ openstack optimize audit create -a at1 \
+      -p thresholds='{"memory.resident": 0.05}' \
+      -p metrics='["memory.resident"]'
+
+External Links
+--------------
+
+- `Watcher Overload standard deviation algorithm spec <https://specs.openstack.org/openstack/watcher-specs/specs/newton/implemented/sd-strategy.html>`_

watcher/decision_engine/strategy/strategies/workload_stabilization.py

@@ -16,6 +16,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+"""
+*Workload Stabilization control using live migration*
+
+This is workload stabilization strategy based on standard deviation
+algorithm. The goal is to determine if there is an overload in a cluster
+and respond to it by migrating VMs to stabilize the cluster.
+
+It assumes that live migrations are possible in your cluster.
+
+"""
 
 import copy
 import itertools
@@ -48,35 +58,18 @@ def _set_memoize(conf):
 
 
 class WorkloadStabilization(base.WorkloadStabilizationBaseStrategy):
-    """Workload Stabilization control using live migration
+    """Workload Stabilization control using live migration"""
-
-    *Description*
-
-    This is workload stabilization strategy based on standard deviation
-    algorithm. The goal is to determine if there is an overload in a cluster
-    and respond to it by migrating VMs to stabilize the cluster.
-
-    *Requirements*
-
-    * Software: Ceilometer component ceilometer-compute running
-      in each compute host, and Ceilometer API can report such telemetries
-      ``memory.resident`` and ``cpu_util`` successfully.
-    * You must have at least 2 physical compute nodes to run this strategy.
-
-    *Limitations*
-
-    - It assume that live migrations are possible
-    - Load on the system is sufficiently stable.
-
-    *Spec URL*
-
-    https://review.openstack.org/#/c/286153/
-    """
 
     MIGRATION = "migrate"
     MEMOIZE = _set_memoize(CONF)
 
     def __init__(self, config, osc=None):
+        """Workload Stabilization control using live migration
+
+        :param config: A mapping containing the configuration of this strategy
+        :type config: :py:class:`~.Struct` instance
+        :param osc: :py:class:`~.OpenStackClients` instance
+        """
         super(WorkloadStabilization, self).__init__(config, osc)
         self._ceilometer = None
         self._nova = None