Update Host Maintenance strategy documentation

Add clarifications to the documentation to reflect
the actual strategy usage, including:
 - updating parameter descriptions
 - extending the 'How to Use' section

Closes-Bug: #2111810
Change-Id: Ifd2876056cd8819c50658fb9f213246dc1546d42

doc/source/strategies/host_maintenance.rst

@@ -11,10 +11,6 @@ Synopsis
 
     .. watcher-term:: watcher.decision_engine.strategy.strategies.host_maintenance.HostMaintenance
 
-Requirements
-------------
-
-None.
 
 Metrics
 *******
@@ -56,15 +52,15 @@ Configuration
 
 Strategy parameters are:
 
-==================== ====== ====================================
+==================== ====== ================================ ==================
-parameter            type   default Value description
+parameter            type   description                      required/optional
-==================== ====== ====================================
+==================== ====== ================================ ==================
-``maintenance_node`` String The name of the compute node which
+``maintenance_node`` String The name of the compute node     Required
-                            need maintenance. Required.
+                            which needs maintenance.
-``backup_node``      String The name of the compute node which
+``backup_node``      String The name of the compute node     Optional
-                            will backup the maintenance node.
+                            which will backup the
-                            Optional.
+                            maintenance node.
-==================== ====== ====================================
+==================== ====== ================================ ==================
 
 Efficacy Indicator
 ------------------
@@ -80,13 +76,34 @@ to: https://specs.openstack.org/openstack/watcher-specs/specs/queens/approved/cl
 How to use it ?
 ---------------
 
+Run an audit using Host Maintenance strategy.
+Executing the actions will move the servers from compute01 host
+to a host determined by the Nova scheduler service.
+
+.. code-block:: shell
+
+    $ openstack optimize audit create \
+      -g cluster_maintaining -s host_maintenance \
+      -p maintenance_node=compute01
+
+Run an audit using Host Maintenance strategy with a backup node specified.
+Executing the actions will move the servers from compute01 host
+to compute02 host.
+
 .. code-block:: shell
 
     $ openstack optimize audit create \
       -g cluster_maintaining -s host_maintenance \
       -p maintenance_node=compute01 \
-      -p backup_node=compute02 \
+      -p backup_node=compute02
-      --auto-trigger
+
+Note that after executing this strategy, the *maintenance_node* will be
+marked as disabled, with the reason set to ``watcher_maintaining``.
+To enable the node again:
+
+.. code-block:: shell
+
+   $ openstack compute service set --enable compute01
 
 External Links
 --------------

watcher/decision_engine/strategy/strategies/host_maintenance.py

@@ -27,16 +27,18 @@ LOG = log.getLogger(__name__)
 
 
 class HostMaintenance(base.HostMaintenanceBaseStrategy):
-    """[PoC]Host Maintenance
+    """Host Maintenance
 
     *Description*
 
         It is a migration strategy for one compute node maintenance,
         without having the user's application been interrupted.
-        If given one backup node, the strategy will firstly
+        If given one backup node (where backup node is the
+        destination node for migration), the strategy will firstly
         migrate all instances from the maintenance node to
         the backup node. If the backup node is not provided,
         it will migrate all instances, relying on nova-scheduler.
+        The maintenance node will then be disabled.
 
     *Requirements*
 
@@ -44,11 +46,14 @@ class HostMaintenance(base.HostMaintenanceBaseStrategy):
 
     *Limitations*
 
-       - This is a proof of concept that is not meant to be used in production
-       - It migrates all instances from one host to other hosts. It's better to
-         execute such strategy when load is not heavy, and use this algorithm
-         with `ONESHOT` audit.
        - It assumes that cold and live migrations are possible.
+
+     .. note::
+         It migrates all instances from one host to other hosts.
+         It is recommended to use this strategy in a planned maintenance
+         window where the load is low to minimize impact on the workloads,
+         and use this algorithm with `ONESHOT` audit.
+
     """
 
     INSTANCE_MIGRATION = "migrate"