From 25d84ba662f21f1cb15f12783ef45c23cb145a70 Mon Sep 17 00:00:00 2001
From: Susanne Balle <sleipnir012@gmail.com>
Date: Wed, 30 Nov 2016 16:17:17 -0500
Subject: [PATCH] Documentation for Workload Balance Migration Strategy Fixed
 comments and added the doc primitive call

Closes-Bug: #1623486

Change-Id: I704536530c576de702434008aa30a7fbbaddff25
---
 doc/source/strategies/workload_balance.rst    | 98 +++++++++++++++++++
 .../strategy/strategies/workload_balance.py   | 31 ++++++
 2 files changed, 129 insertions(+)
 create mode 100644 doc/source/strategies/workload_balance.rst

diff --git a/doc/source/strategies/workload_balance.rst b/doc/source/strategies/workload_balance.rst
new file mode 100644
index 000000000..36dcc5a68
--- /dev/null
+++ b/doc/source/strategies/workload_balance.rst
@@ -0,0 +1,98 @@
+===================================
+Workload Balance Migration Strategy
+===================================
+
+Synopsis
+--------
+
+**display name**: ``workload_balance``
+
+**goal**: ``workload_balancing``
+
+.. watcher-term:: watcher.decision_engine.strategy.strategies.workload_balance
+
+Requirements
+------------
+
+None.
+
+Metrics
+*******
+
+The *workload_balance* strategy requires the following metrics:
+
+======================= ============ ======= =======
+metric                  service name plugins comment
+======================= ============ ======= =======
+``cpu_util``            ceilometer_  none
+======================= ============ ======= =======
+
+.. _ceilometer: http://docs.openstack.org/admin-guide/telemetry-measurements.html#openstack-compute
+
+
+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
+============== ====== ============= ====================================
+``threshold``  Number 25.0          Workload threshold for migration
+``period``     Number 300           Aggregate time period of ceilometer
+============== ====== ============= ====================================
+
+Efficacy Indicator
+------------------
+
+None
+
+Algorithm
+---------
+
+For more information on the Workload Balance Migration Strategy please refer
+to: https://specs.openstack.org/openstack/watcher-specs/specs/mitaka/implemented/workload-balance-migration-strategy.html
+
+How to use it ?
+---------------
+
+.. code-block:: shell
+
+    $ openstack optimize audittemplate create \
+      at1 workload_balancing --strategy workload_balance
+
+    $ openstack optimize audit create -a at1 -p threshold=26.0 \
+            -p period=310
+
+External Links
+--------------
+
+None.
diff --git a/watcher/decision_engine/strategy/strategies/workload_balance.py b/watcher/decision_engine/strategy/strategies/workload_balance.py
index 5dba465b9..e20c0d8cd 100644
--- a/watcher/decision_engine/strategy/strategies/workload_balance.py
+++ b/watcher/decision_engine/strategy/strategies/workload_balance.py
@@ -16,6 +16,37 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+"""
+*[PoC]Workload balance using live migration*
+
+*Description*
+
+This strategy migrates a VM based on the VM workload of the hosts.
+It makes decision to migrate a workload whenever a host's CPU
+utilization % is higher than the specified threshold. The VM to
+be moved should make the host close to average workload of all
+hosts nodes.
+
+*Requirements*
+
+* Hardware: compute node should use the same physical CPUs
+* Software: Ceilometer component ceilometer-agent-compute
+  running in each compute node, and Ceilometer API can
+  report such telemetry "cpu_util" successfully.
+* You must have at least 2 physical compute nodes to run
+  this strategy.
+
+*Limitations*
+
+- This is a proof of concept that is not meant to be used in
+  production.
+- We cannot forecast how many servers should be migrated.
+  This is the reason why we only plan a single virtual
+  machine migration at a time. So it's better to use this
+  algorithm with `CONTINUOUS` audits.
+"""
+
+
 from oslo_log import log
 
 from watcher._i18n import _, _LE, _LI, _LW