Recommend against using --force for evacuate/live migration11.1.0

This copies the same warnings from the API reference change
I85e7c2677f4d5eccc1e7f349de06960b53ef148d to the CLI help
for the various evacuate/live migrate commands. It also
mentions that if a host is not specified, one is selected
by the scheduler (which is what we really want people doing).

Given blueprint remove-force-flag-from-live-migrate-and-evacuate
we really want to discourage people from using the --force
flag.

Change-Id: I15ef933cc09947e2bb3fb7bf17b15735171a9bec

2 files changed, 56 insertions, 16 deletions

diff --git a/doc/source/cli/nova.rst b/doc/source/cli/nova.rst
index a444c297..e14acd5c 100644
--- a/doc/source/cli/nova.rst
+++ b/doc/source/cli/nova.rst
@@ -1248,8 +1248,13 @@ Evacuate server from failed host.
   storage.
 
 ``--force``
-  Force to not verify the scheduler if a host is
-  provided. (Supported by API versions '2.29' -'2.latest')
+  Force an evacuation by not verifying the provided destination host by the
+  scheduler. (Supported by API versions '2.29' -'2.latest')
+
+  .. warning:: This could result in failures to actually evacuate the
+    server to the specified host. It is recommended to either not specify
+    a host so that the scheduler will pick one, or specify a host without
+    ``--force``.
 
 .. _nova_flavor-access-add:
 
@@ -1644,8 +1649,13 @@ Evacuate all instances from failed host.
   the scheduler will select a target.
 
 ``--force``
-  Force to not verify the scheduler if a host is
-  provided. (Supported by API versions '2.29' -'2.latest')
+  Force an evacuation by not verifying the provided destination host by the
+  scheduler. (Supported by API versions '2.29' -'2.latest')
+
+  .. warning:: This could result in failures to actually evacuate the
+    server to the specified host. It is recommended to either not specify
+    a host so that the scheduler will pick one, or specify a host without
+    ``--force``.
 
 ``--strict``
   Evacuate host with exact hypervisor hostname match
@@ -1678,7 +1688,8 @@ Live migrate all instances off the specified host to other available hosts.
 **Optional arguments:**
 
 ``--target-host <target_host>``
-  Name of target host.
+  Name of target host. If no host is specified, the scheduler will choose
+  one.
 
 ``--block-migrate``
   Enable block migration. (Default=auto)
@@ -1689,8 +1700,13 @@ Live migrate all instances off the specified host to other available hosts.
   simultaneously
 
 ``--force``
-  Force to not verify the scheduler if a host is
-  provided. (Supported by API versions '2.30' -'2.latest')
+  Force a live-migration by not verifying the provided destination host by
+  the scheduler. (Supported by API versions '2.30' -'2.latest')
+
+  .. warning:: This could result in failures to actually live migrate the
+    servers to the specified host. It is recommended to either not specify
+    a host so that the scheduler will pick one, or specify a host without
+    ``--force``.
 
 ``--strict``
   live Evacuate host with exact hypervisor hostname match
@@ -2341,7 +2357,8 @@ Migrate running server to a new machine.
   Name or ID of server.
 
 ``<host>``
-  Destination host name.
+  Destination host name. If no host is specified, the scheduler will choose
+  one.
 
 **Optional arguments:**
 
@@ -2351,8 +2368,13 @@ Migrate running server to a new machine.
   '2.25' - '2.latest')
 
 ``--force``
-  Force to not verify the scheduler if a host is provided.
-  (Supported by API versions '2.30' - '2.latest')
+  Force a live-migration by not verifying the provided destination host by
+  the scheduler. (Supported by API versions '2.30' -'2.latest')
+
+  .. warning:: This could result in failures to actually live migrate the
+    server to the specified host. It is recommended to either not specify
+    a host so that the scheduler will pick one, or specify a host without
+    ``--force``.
 
 .. _nova_live-migration-abort:
 
diff --git a/novaclient/v2/shell.py b/novaclient/v2/shell.py
index f6704559..b993fbc0 100644
--- a/novaclient/v2/shell.py
+++ b/novaclient/v2/shell.py
@@ -3425,7 +3425,8 @@ def _print_aggregate_details(cs, aggregate):
 @utils.arg('server', metavar='<server>', help=_('Name or ID of server.'))
 @utils.arg(
     'host', metavar='<host>', default=None, nargs='?',
-    help=_('Destination host name.'))
+    help=_('Destination host name. If no host is specified, the scheduler '
+           'will choose one.'))
 @utils.arg(
     '--block-migrate',
     action='store_true',
@@ -3452,7 +3453,11 @@ def _print_aggregate_details(cs, aggregate):
     dest='force',
     action='store_true',
     default=False,
-    help=_('Force to not verify the scheduler if a host is provided.'),
+    help=_('Force a live-migration by not verifying the provided destination '
+           'host by the scheduler. WARNING: This could result in failures to '
+           'actually live migrate the server to the specified host. It is '
+           'recommended to either not specify a host so that the scheduler '
+           'will pick one, or specify a host without --force.'),
     start_version='2.30')
 def do_live_migration(cs, args):
     """Migrate running server to a new machine."""
@@ -4437,7 +4442,11 @@ def do_quota_class_update(cs, args):
     dest='force',
     action='store_true',
     default=False,
-    help=_('Force to not verify the scheduler if a host is provided.'),
+    help=_('Force an evacuation by not verifying the provided destination '
+           'host by the scheduler. WARNING: This could result in failures to '
+           'actually evacuate the server to the specified host. It is '
+           'recommended to either not specify a host so that the scheduler '
+           'will pick one, or specify a host without --force.'),
     start_version='2.29')
 def do_evacuate(cs, args):
     """Evacuate server from failed host."""
@@ -4890,7 +4899,11 @@ def _hyper_servers(cs, host, strict):
     dest='force',
     action='store_true',
     default=False,
-    help=_('Force to not verify the scheduler if a host is provided.'),
+    help=_('Force an evacuation by not verifying the provided destination '
+           'host by the scheduler. WARNING: This could result in failures to '
+           'actually evacuate the server to the specified host. It is '
+           'recommended to either not specify a host so that the scheduler '
+           'will pick one, or specify a host without --force.'),
     start_version='2.29')
 @utils.arg(
     '--strict',
@@ -4945,7 +4958,8 @@ def _server_live_migrate(cs, server, args):
     '--target-host',
     metavar='<target_host>',
     default=None,
-    help=_('Name of target host.'))
+    help=_('Name of target host. If no host is specified, the scheduler will '
+           'choose one.'))
 @utils.arg(
     '--block-migrate',
     action='store_true',
@@ -4975,7 +4989,11 @@ def _server_live_migrate(cs, server, args):
     dest='force',
     action='store_true',
     default=False,
-    help=_('Force to not verify the scheduler if a host is provided.'),
+    help=_('Force a live-migration by not verifying the provided destination '
+           'host by the scheduler. WARNING: This could result in failures to '
+           'actually live migrate the servers to the specified host. It is '
+           'recommended to either not specify a host so that the scheduler '
+           'will pick one, or specify a host without --force.'),
     start_version='2.30')
 @utils.arg(
     '--strict',