From 1d3891e1e412f87fe702764f20353c64235c0f53 Mon Sep 17 00:00:00 2001
From: Edwin Zhai <edwin.zhai@intel.com>
Date: Sat, 25 Jun 2016 04:44:24 +0000
Subject: [PATCH] Documentation for strategy parameters

Add docs of how to define and input parameters of strategy.

Change-Id: I918305b89721d141b7f37630459e6cf5999f4211
Partially-Implements: optimization-threshold
---
 doc/source/deploy/user-guide.rst          | 30 +++++++++++
 doc/source/dev/plugin/strategy-plugin.rst | 64 +++++++++++++++++++++++
 2 files changed, 94 insertions(+)

diff --git a/doc/source/deploy/user-guide.rst b/doc/source/deploy/user-guide.rst
index 2245d6d9b..74be90859 100644
--- a/doc/source/deploy/user-guide.rst
+++ b/doc/source/deploy/user-guide.rst
@@ -99,6 +99,16 @@ or::
 
   $ openstack optimize strategy list --goal-uuid <your_goal_uuid>
 
+You can use the following command to check strategy details including which
+parameters of which format it supports:
+
+.. code:: bash
+
+  $ watcher strategy show <your_strategy>
+
+or::
+
+  $ openstack optimize strategy show <your_strategy>
 
 The command to create your audit template would then be:
 
@@ -140,6 +150,26 @@ or::
 
   $ openstack optimize audit create -a <your_audit_template>
 
+If your_audit_template was created by --strategy <your_strategy>, and it
+defines some parameters (command `watcher strategy show` to check parameters
+format), your can append `-p` to input required parameters:
+
+.. code:: bash
+
+  $ watcher audit create -a <your_audit_template> \
+    -p <your_strategy_para1>=5.5 -p <your_strategy_para2>=hi
+
+or::
+
+  $ openstack optimize audit create -a <your_audit_template> \
+    -p <your_strategy_para1>=5.5 -p <your_strategy_para2>=hi
+
+Input parameter could cause audit creation failure, when:
+
+- no predefined strategy for audit template
+- no parameters spec in predefined strategy
+- input parameters don't comply with spec
+
 Watcher service will compute an :ref:`Action Plan <action_plan_definition>`
 composed of a list of potential optimization :ref:`actions <action_definition>`
 (instance migration, disabling of an hypervisor, ...) according to the
diff --git a/doc/source/dev/plugin/strategy-plugin.rst b/doc/source/dev/plugin/strategy-plugin.rst
index 94046c990..d52c229fd 100644
--- a/doc/source/dev/plugin/strategy-plugin.rst
+++ b/doc/source/dev/plugin/strategy-plugin.rst
@@ -119,6 +119,70 @@ for which the goal has yet to be defined or in case a :ref:`new goal
 <implement_goal_plugin>` has yet to be implemented.
 
 
+Define Strategy Parameters
+==========================
+
+For each new added strategy, you can add parameters spec so that an operator
+can input strategy parameters when creating an audit to control the
+:py:meth:`~.BaseStrategy.execute` behavior of strategy. This is useful to
+define some threshold for your strategy, and tune them at runtime.
+
+To define parameters, just implements :py:meth:`~.BaseStrategy.get_schema` to
+return parameters spec with `jsonschema
+<http://json-schema.org/>`_ format.
+It is strongly encouraged that provide default value for each parameter, or
+else reference fails if operator specify no parameters.
+
+Here is an example showing how you can define 2 parameters for
+``DummyStrategy``:
+
+.. code-block:: python
+
+    class DummyStrategy(base.DummyBaseStrategy):
+
+        @classmethod
+        def get_schema(cls):
+            return {
+                "properties": {
+                    "para1": {
+                        "description": "number parameter example",
+                        "type": "number",
+                        "default": 3.2,
+                        "minimum": 1.0,
+                        "maximum": 10.2,
+                    },
+                    "para2": {
+                        "description": "string parameter example",
+                        "type": "string",
+                        "default": "hello",
+                    },
+                },
+            }
+
+
+You can reference parameters in :py:meth:`~.BaseStrategy.execute`:
+
+.. code-block:: python
+
+    class DummyStrategy(base.DummyBaseStrategy):
+
+        def execute(self):
+            para1 = self.input_parameters.para1
+            para2 = self.input_parameters.para2
+
+            if para1 > 5:
+                ...
+
+
+Operator can specify parameters with following commands:
+
+.. code:: bash
+
+  $ watcher audit create -a <your_audit_template> -p para1=6.0 -p para2=hi
+
+Pls. check user-guide for details.
+
+
 Abstract Plugin Class
 =====================